Wrappers

Wrappers can alter the way the build is run as well as the build output.

Component: wrappers
Macro:wrapper
Entry Point:jenkins_jobs.wrappers
ansicolor

Translate ANSI color codes to HTML in the console log. Requires the Jenkins Ansi Color Plugin.

Parameters:colormap (string) – (optional) color mapping to use

Examples:

wrappers:
  - ansicolor

# Explicitly setting the colormap
wrappers:
  - ansicolor:
      colormap: vga
build-name

Set the name of the build Requires the Jenkins Build Name Setter Plugin.

Parameters:name (str) – Name for the build. Typically you would use a variable from Jenkins in the name. The syntax would be ${FOO} for the FOO variable.

Example:

wrappers:
  - build-name:
      name: Build-${FOO}
build-user-vars

Set environment variables to the value of the user that started the build. Requires the Jenkins Build User Vars Plugin.

Example:

wrappers:
  - build-user-vars
ci-skip

Skip making a build for certain push. Just add [ci skip] into your commit’s message to let Jenkins know, that you do not want to perform build for the next push. Requires the Jenkins Ci Skip Plugin.

Example:

wrappers:
  - ci-skip
copy-to-slave

Copy files to slave before build Requires the Jenkins Copy To Slave Plugin.

Parameters:
  • includes (list) – list of file patterns to copy
  • excludes (list) – list of file patterns to exclude
  • flatten (bool) – flatten directory structure
  • relative-to (str) – base location of includes/excludes, must be userContent ($JENKINS_HOME/userContent) home ($JENKINS_HOME) or workspace
  • include-ant-excludes (bool) – exclude ant’s default excludes

Example:

wrappers:
  - copy-to-slave:
      includes:
        - file1
        - file2*.txt
      excludes:
        - file2bad.txt
delivery-pipeline

If enabled the job will create a version based on the template. The version will be set to the environment variable PIPELINE_VERSION and will also be set in the downstream jobs.

Requires the Jenkins Delivery Pipeline Plugin.

Parameters:
  • version-template (str) – Template for generated version e.g 1.0.${BUILD_NUMBER} (default: ‘’)
  • set-display-name (bool) – Set the generated version as the display name for the build (default: false)

Example:

wrappers:
    - delivery-pipeline:
        version-template: 1.0.0-${BUILD_NUMBER}
        set-display-name: true
env-file

Add or override environment variables to the whole build process Requires the Jenkins Environment File Plugin.

Parameters:properties-file (str) – path to the properties file (default ‘’)

Example:

wrappers:
  - env-file:
      properties-file: ${WORKSPACE}/foo
env-script

Add or override environment variables to the whole build process. Requires the Jenkins Environment Script Plugin.

Parameters:
  • script-content – The script to run (default: ‘’)
  • only-run-on-parent – Only applicable for Matrix Jobs. If true, run only on the matrix parent job (default: false)

Example:

wrappers:
  - env-script:
      script-content: 'echo foo=bar'
      only-run-on-parent: true
exclusion

Add a resource to use for critical sections to establish a mutex on. If another job specifies the same resource, the second job will wait for the blocked resource to become available.

Requires the Jenkins Exclusion Plugin.

Parameters:resources (list) – List of resources to add for exclusion

Example:

wrappers:
  - exclusion:
      resources:
          - myresource1
          - myresource2
inject

Add or override environment variables to the whole build process Requires the Jenkins EnvInject Plugin.

Parameters:
  • properties-file (str) – path to the properties file (default ‘’)
  • properties-content (str) – key value pair of properties (default ‘’)
  • script-file (str) – path to the script file (default ‘’)
  • script-content (str) – contents of a script (default ‘’)

Example:

wrappers:
  - inject:
      properties-file: /usr/local/foo
      properties-content: PATH=/foo/bar
      script-file: /usr/local/foo.sh
      script-content: echo $PATH
inject-ownership-variables

Inject ownership variables to the build as environment variables. Requires the Jenkins EnvInject Plugin and Jenkins Ownership plugin <https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin>

Parameters:
  • job-variables (bool) – inject job ownership variables to the job (default false)
  • node-variables (bool) – inject node ownership variables to the job (default false)

Example:

wrappers:
  - inject-ownership-variables:
      job-variables: true
      node-variables: true
inject-passwords

Inject passwords to the build as environment variables. Requires the Jenkins EnvInject Plugin.

Parameters:
  • global (bool) – inject global passwords to the job
  • job-passwords (list) –

    key value pair of job passwords

    Parameter:
    • name (str) Name of password
    • password (str) Encrypted password

Example:

wrappers:
  - inject-passwords:
      global: true
      job-passwords:
        - name: ADMIN
          password: 0v8ZCNaHwq1hcx+sHwRLdg9424uBh4Pin0zO4sBIb+U=
jclouds

Uses JClouds to provide slave launching on most of the currently usable Cloud infrastructures. Requires the Jenkins JClouds Plugin.

Parameters:
  • single-use (bool) – Whether or not to terminate the slave after use (default: False).
  • instances (list) – The name of the jclouds template to create an instance from, and its parameters.
  • cloud-name (str) – The name of the jclouds profile containing the specified template.
  • count (int) – How many instances to create (default: 1).
  • stop-on-terminate (bool) – Whether or not to suspend instead of terminate the instance (default: False).

Example:

wrappers:
  - jclouds:
      single-use: True
      instances:
        - jenkins-dev-slave:
            cloud-name: mycloud1
            count: 1
            stop-on-terminate: True
        - jenkins-test-slave:
            cloud-name: mycloud2
            count: 2
            stop-on-terminate: False
locks

Control parallel execution of jobs. Requires the Jenkins Locks and Latches Plugin.

Arg:list of locks to use

Example:

wrappers:
    - locks:
        - FOO
        - FOO2
logfilesize

Abort the build if its logfile becomes too big. Requires the Jenkins Logfilesizechecker Plugin.

Parameters:
  • set-own (bool) – Use job specific maximum log size instead of global config value (default false).
  • fail (bool) – Make builds aborted by this wrapper be marked as “failed” (default false).
  • size (int) – Abort the build if logfile size is bigger than this value (in MiB, default 128). Only applies if set-own is true.

Minimum config example:

wrappers:
  - logfilesize

Full config example:

wrappers:
  - logfilesize:
      set-own: true
      size: 1024
      fail: true
logstash build wrapper

Dump the Jenkins console output to Logstash Requires the Jenkins logstash plugin.

Parameters:
  • use-redis – Boolean to use Redis. (default: true)
  • redis

    Redis config params

    Parameter:
    • host (str) Redis hostname (default ‘localhost’)
    Parameter:
    • port (int) Redis port number (default 6397)
    Parameter:
    • database-number (int) Redis database number (default 0)
    Parameter:
    • database-password (str) Redis database password (default ‘’)
    Parameter:
    • data-type (str) Redis database type (default ‘list’)
    Parameter:
    • key (str) Redis key (default ‘logstash’)

Example:

wrappers:
  - logstash:
      use-redis: True
      redis:
        host: 'localhost'
        port: 6379
        database-number: 0
        database-password: 'password'
        data-type: 'list'
        key: 'logstash'
mask-passwords

Hide passwords in the console log. Requires the Jenkins Mask Passwords Plugin.

Example:

wrappers:
  - mask-passwords
matrix-tie-parent

Tie parent to a node. Requires the Jenkins Matrix Tie Parent Plugin. Note that from Jenkins version 1.532 this plugin’s functionality is available under the “advanced” option of the matrix project configuration.

Parameters:node (str) – Name of the node.

Example:

project-type: matrix
wrappers:
  - matrix-tie-parent:
      node: Unix
pathignore

This plugin allows SCM-triggered jobs to ignore build requests if only certain paths have changed.

Requires the Jenkins Pathignore Plugin.

Parameters:ignored (str) – A set of patterns to define ignored changes

Example:

wrappers:
  - pathignore:
      ignored: "docs, tests"
port-allocator

Assign unique TCP port numbers Requires the Jenkins Port Allocator Plugin.

Parameters:name (str) – Variable name of the port or a specific port number

Example:

wrappers:
  - port-allocator:
      name: SERVER_PORT
pre-scm-buildstep

Execute a Build Step before running the SCM Requires the Jenkins pre-scm-buildstep.

Parameters:buildsteps (list) –

List of build steps to execute

Buildstep:Any acceptable builder, as seen in the example

Example:

wrappers:
  - pre-scm-buildstep:
    - shell: |
        #!/bin/bash
        echo "Doing somethiung cool"
    - shell: |
        #!/bin/zsh
        echo "Doing somethin cool with zsh"
    - ant: "target1 target2"
      ant-name: "Standard Ant"
    - inject:
         properties-file: example.prop
         properties-content: EXAMPLE=foo-bar
rbenv

Set the rbenv implementation. Requires the Jenkins rbenv plugin.

All parameters are optional.

Parameters:
  • ruby-version (str) – Version of Ruby to use (default: 1.9.3-p484)
  • ignore-local-version (bool) – If true, ignore local Ruby version (defined in the ”.ruby-version” file in workspace) even if it has been defined (default: false)
  • preinstall-gem-list (str) – List of gems to install (default: ‘bundler,rake’)
  • rbenv-root (str) – RBENV_ROOT (default: $HOME/.rbenv)
  • rbenv-repo (str) – Which repo to clone rbenv from (default: https://github.com/sstephenson/rbenv.git)
  • rbenv-branch (str) – Which branch to clone rbenv from (default: master)
  • ruby-build-repo (str) – Which repo to clone ruby-build from (default: https://github.com/sstephenson/ruby-build.git)
  • ruby-build-branch (str) – Which branch to clone ruby-build from (default: master)

Example:

wrappers:
  - rbenv:
      ruby-version: 2.0.0-p353
      ignore-local-version: false
      preinstall-gem-list: "bundler,rake"
      rbenv-root: "$HOME/.rbenv"
      rbenv-repo: "https://github.com/sstephenson/rbenv.git"
      rbenv-branch: "master"
      ruby-build-repo: "https://github.com/sstephenson/ruby-build.git"
      ruby-build-branch: "master"
release

Add release build configuration Requires the Jenkins Release Plugin.

Parameters:
  • keep-forever (bool) – Keep build forever (default true)
  • override-build-parameters (bool) – Enable build-parameter override
  • version-template (string) – Release version template
  • parameters (list) – Release parameters (see the Parameters module)
  • pre-build (list) – Pre-build steps (see the Builders module)
  • post-build (list) – Post-build steps (see Builders)
  • post-success (list) – Post successful-build steps (see Builders)
  • post-failed (list) – Post failed-build steps (see Builders)

Example:

wrappers:
  - release:
      keep-forever: false
      parameters:
          - string:
              name: RELEASE_BRANCH
              default: ''
              description: Git branch to release from.
      post-success:
          - shell: |
              #!/bin/bash
              copy_build_artefacts.sh
rvm-env

Set the RVM implementation Requires the Jenkins Rvm Plugin.

Parameters:implementation (str) – Type of implementation. Syntax is RUBY[@GEMSET], such as ‘1.9.3’ or 'jruby@foo‘.

Example:

wrappers:
  - rvm-env:
      implementation: 1.9.3
sauce-ondemand

Allows you to integrate Sauce OnDemand with Jenkins. You can automate the setup and tear down of Sauce Connect and integrate the Sauce OnDemand results videos per test. Requires the Jenkins Sauce OnDemand Plugin.

Parameters:
  • enable-sauce-connect (bool) – launches a SSH tunnel from their cloud to your private network (default false)
  • sauce-host (str) – The name of the selenium host to be used. For tests run using Sauce Connect, this should be localhost. ondemand.saucelabs.com can also be used to conenct directly to Sauce OnDemand, The value of the host will be stored in the SAUCE_ONDEMAND_HOST environment variable. (default ‘’)
  • sauce-port (str) – The name of the Selenium Port to be used. For tests run using Sauce Connect, this should be 4445. If using ondemand.saucelabs.com for the Selenium Host, then use 4444. The value of the port will be stored in the SAUCE_ONDEMAND_PORT environment variable. (default ‘’)
  • override-username (str) – If set then api-access-key must be set. Overrides the username from the global config. (default ‘’)
  • override-api-access-key (str) – If set then username must be set. Overrides the api-access-key set in the global config. (default ‘’)
  • starting-url (str) – The value set here will be stored in the SELENIUM_STARTING_ULR environment variable. Only used when type is selenium. (default ‘’)
  • type (str) –

    Type of test to run (default selenium)

    type values:
    • selenium
    • webdriver
  • platforms (list) – The platforms to run the tests on. Platforms supported are dynamically retrieved from sauce labs. The format of the values has only the first letter capitalized, no spaces, underscore between os and version, underscore in internet_explorer, everything else is run together. If there are not multiple version of the browser then just the first version number is used. Examples: Mac_10.8iphone5.1 or Windows_2003firefox10 or Windows_2012internet_explorer10 (default ‘’)
  • launch-sauce-connect-on-slave (bool) – Whether to launch sauce connect on the slave. (default false)
  • https-protocol (str) – The https protocol to use (default ‘’)
  • sauce-connect-options (str) – Options to pass to sauce connect (default ‘’)

Example:

wrappers:
  - sauce-ondemand:
      enable-sauce-connect: true
      sauce-host: foo
      sauce-port: 8080
      override-username: foo
      override-api-access-key: 123lkj123kh123l;k12323
      type: webdriver
      platforms:
        - Linuxandroid4
        - Linuxfirefox10
        - Linuxfirefox11
      launch-sauce-connect-on-slave: true
ssh-agent-credentials

Sets up the user for the ssh agent plugin for jenkins.

Requires the Jenkins SSH-Agent Plugin.

Parameters:user (str) – The user id of the jenkins user credentials (required)

Example:

wrappers:
  - ssh-agent-credentials:
      user: '49d20745-9889-4c02-b286-fc6fb89c36bd'
timeout

Abort the build if it runs too long. Requires the Jenkins Build Timeout Plugin.

Parameters:
  • fail (bool) – Mark the build as failed (default false)
  • write-description (bool) – Write a message in the description (default false)
  • timeout (int) – Abort the build after this number of minutes (default 3)
  • timeout-var (str) – Export an environment variable to reference the timeout value (optional)
  • type (str) – Timeout type to use (default absolute)
  • elastic-percentage (int) – Percentage of the three most recent builds where to declare a timeout (default 0)
  • elastic-default-timeout (int) – Timeout to use if there were no previous builds (default 3)

Example:

wrappers:
  - timeout:
      timeout: 90
      timeout-var: 'BUILD_TIMEOUT'
      fail: true
      type: absolute
wrappers:
  - timeout:
      fail: false
      type: likely-stuck
 wrappers:
    - timeout:
        timeout-var: 'BUILD_TIMEOUT'
        fail: true
        elastic-percentage: 150
        elastic-default-timeout: 90
        type: elastic
timestamps

Add timestamps to the console log. Requires the Jenkins Timestamper Plugin.

Example:

wrappers:
  - timestamps
workspace-cleanup (pre-build)

Requires the Jenkins Workspace Cleanup Plugin.

The post-build workspace-cleanup is available as a publisher.

Parameters:
  • include (list) – list of files to be included
  • exclude (list) – list of files to be excluded
  • dirmatch (bool) – Apply pattern to directories too

Example:

wrappers:
  - workspace-cleanup:
      include:
        - "*.zip"

Previous topic

Triggers

Next topic

Zuul

This Page