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

class wrappers.Wrappers(registry)

component_list_type = 'wrappers'

The component list type will be used to look up possible implementations of the component type via entry points (entry points provide a list of components, so it should be plural). Set both component_type and component_list_type to None if module doesn’t have components.

component_type = 'wrapper'

The component type for components of this module. This will be used to look for macros (they are defined singularly, and should not be plural). Set both component_type and component_list_type to None if module doesn’t have components.

gen_xml(xml_parent, data)

Update the XML element tree based on YAML data. Override this method to add elements to the XML output. Create new Element objects and add them to the xml_parent. The YAML data structure must not be modified.

:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure

sequence = 80

The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.

android-emulator()

Automates many Android development tasks including SDK installation, build file generation, emulator creation and launch, APK (un)installation…

Requires the Jenkins Android Emulator Plugin.

Parameters:

• avd (str) – Enter the name of an existing Android emulator configuration. If this is exclusive with the ‘os’ arg.

• os (str) – Can be an OS version, target name or SDK add-on

• screen-density (str) – Density in dots-per-inch (dpi) or as an alias, e.g. “160” or “mdpi”. (default mdpi)

• screen-resolution (str) – Can be either a named resolution or explicit size, e.g. “WVGA” or “480x800”. (default WVGA)

• locale (str) – Language and country pair. (default en_US)

• target-abi (str) – Name of the ABI / system image to be used. (optional)

• sd-card (str) – sd-card size e.g. “32M” or “10240K”. (optional)

• wipe (bool) – if true, the emulator will have its user data reset at start-up (default false)

• show-window (bool) – if true, the Android emulator user interface will be displayed on screen during the build. (default false)

• snapshot (bool) – Start emulator from stored state (default false)

• delete (bool) – Delete Android emulator at the end of build (default false)

• startup-delay (int) – Wait this many seconds before attempting to start the emulator (default 0)

• commandline-options (str) – Will be given when starting the Android emulator executable (optional)

• exe (str) – The emulator executable. (optional)

• hardware-properties (list) – Dictionary of hardware properties. Allows you to override the default values for an AVD. (optional)

Example:

wrappers:
  - android-emulator:
      os: android-19
      target-abi: x86
      sd-card: 16MB
      hardware-properties:
        hw.accelerometer: 100
      wipe: true
      show-window: true
      snapshot: true
      delete: true
      startup-delay: 10
      commandline-options: "-gpu on -no-audio"
      exe: emulator-arm

ansicolor()

Translate ANSI color codes to HTML in the console log.

Requires the Jenkins Ansi Color Plugin.

Parameters:

colormap (str) – Color mapping to use (default xterm)

Minimal Example:

wrappers:
  - ansicolor

Full Example:

wrappers:
  - ansicolor:
      colormap: "gnome-terminal"

artifactory-generic()

Wrapper for non-Maven projects.

Requires the Jenkins Artifactory Plugin

Parameters:

• url (str) – URL of the Artifactory server. e.g. https://jfrog.com/artifactory/ (default ‘’)

• name (str) – Artifactory user with permissions use for connected to the selected Artifactory Server (default ‘’)

• repo-key (str) – Release repository name (plugin < 2.3.0) (default ‘’)

• snapshot-repo-key (str) – Snapshots repository name (plugin < 2.3.0) (default ‘’)

• key-from-select (str) – Repository key to use (plugin >= 2.3.0) (default ‘’)

• key-from-text (str) – Repository key to use that can be configured dynamically using Jenkins variables (plugin >= 2.3.0) (default ‘’)

• upload-spec (str) – File Spec schema for uploading files is as follows (default ‘’)

• download-spec (str) – File Spec schema for downloading files is as follows (default ‘’)

• upload-spec-file (str) – File location for uploading Spec schema (default ‘’)

• download-spec-file (str) – File location for downloading Spec schema (default ‘’)

• deploy-pattern (list) – List of patterns for mappings build artifacts to published artifacts. Supports Ant-style wildcards mapping to target directories. E.g.: /.zip=>dir (default [])

• resolve-pattern (list) – List of references to other artifacts that this build should use as dependencies.

• matrix-params (list) – List of properties to attach to all deployed artifacts in addition to the default ones: build.name, build.number, and vcs.revision (default [])

• deploy-build-info (bool) – Deploy jenkins build metadata with artifacts to Artifactory (default false)

• env-vars-include (bool) – Include environment variables accessible by the build process. Jenkins-specific env variables are always included. Use the env-vars-include-patterns and env-vars-exclude-patterns to filter the environment variables published to artifactory. (default false)

• env-vars-include-patterns (list) – List of environment variable patterns for including env vars as part of the published build info. Environment variables may contain the * and the ? wildcards (default [])

• env-vars-exclude-patterns (list) – List of environment variable patterns that determine the env vars excluded from the published build info (default [])

• discard-old-builds (bool) – Remove older build info from Artifactory (default false)

• discard-build-artifacts (bool) – Remove older build artifacts from Artifactory (default false)

Example:

wrappers:
  - artifactory-generic:
      url: http://artifactory.example.net/artifactory
      name: 'test'
      deploy-build-info: true
      repo-key: 'release-repo'
      snapshot-repo-key: 'snapshot-repo'
      deploy-pattern:
      - '*.zip=>results'
      resolve-pattern:
      - 'libs-release-local:prod/*=>prod-jars'
      matrix-params:
      - 'custom_prop=${PROJECT_ENV_VAR}'
      env-vars-include: true
      env-vars-include-patterns:
      - 'PROJECT_*'
      - 'ORG_*'
      discard-old-builds: true
      discard-build-artifacts: true

artifactory-maven()

Wrapper for non-Maven projects.

Requires the Jenkins Artifactory Plugin

Parameters:

• url (str) – URL of the Artifactory server. e.g. https://jfrog.com/artifactory/ (default ‘’)

• name (str) – Artifactory user with permissions use for connected to the selected Artifactory Server (default ‘’)

• repo-key (str) – Name of the repository to search for artifact dependencies. Provide a single repo-key or provide separate release-repo-key and snapshot-repo-key.

• release-repo-key (str) – Release repository name. Value of repo-key take priority over release-repo-key if provided.

• snapshot-repo-key (str) – Snapshots repository name. Value of repo-key take priority over release-repo-key if provided.

Example:

wrappers:
  - artifactory-maven:
      url: http://artifactory.example.net/artifactory
      name: 'test'
      repo-key: repo

artifactory-maven-freestyle()

Wrapper for Free Stype projects.

Requires the Jenkins Artifactory Plugin

Parameters:

• url (str) – URL of the Artifactory server. e.g. https://jfrog.com/artifactory/ (default ‘’)

• name (str) – Artifactory user with permissions use for connected to the selected Artifactory Server (default ‘’)

• release-repo-key (str) – Release repository name (default ‘’)

• snapshot-repo-key (str) – Snapshots repository name (default ‘’)

• publish-build-info (bool) – Push build metadata with artifacts (default false)

• discard-old-builds (bool) – Remove older build info from Artifactory (default true)

• discard-build-artifacts (bool) – Remove older build artifacts from Artifactory (default false)

• include-env-vars (bool) – Include all environment variables accessible by the build process. Jenkins-specific env variables are always included (default false)

• run-checks (bool) – Run automatic license scanning check after the build is complete (default false)

• include-publish-artifacts (bool) – Include the build’s published module artifacts in the license violation checks if they are also used as dependencies for other modules in this build (default false)

• license-auto-discovery (bool) – Tells Artifactory not to try and automatically analyze and tag the build’s dependencies with license information upon deployment (default true)

• enable-issue-tracker-integration (bool) – When the Jenkins JIRA plugin is enabled, synchronize information about JIRA issues to Artifactory and attach issue information to build artifacts (default false)

• aggregate-build-issues (bool) – When the Jenkins JIRA plugin is enabled, include all issues from previous builds up to the latest build status defined in “Aggregation Build Status” (default false)

• filter-excluded-artifacts-from-build (bool) – Add the excluded files to the excludedArtifacts list and remove them from the artifacts list in the build info (default false)

• scopes (str) – A list of dependency scopes/configurations to run license violation checks on. If left empty all dependencies from all scopes will be checked (default ‘’)

• violation-recipients (str) – Recipients that need to be notified of license violations in the build info (default ‘’)

• matrix-params (list) – List of properties to attach to all deployed artifacts in addition to the default ones: build.name, build.number, and vcs.revision (default ‘’)

• black-duck-app-name (str) – The existing Black Duck Code Center application name (default ‘’)

• black-duck-app-version (str) – The existing Black Duck Code Center application version (default ‘’)

• black-duck-report-recipients (str) – Recipients that will be emailed a report after the automatic Black Duck Code Center compliance checks finished (default ‘’)

• black-duck-scopes (str) – A list of dependency scopes/configurations to run Black Duck Code Center compliance checks on. If left empty all dependencies from all scopes will be checked (default ‘’)

• black-duck-run-checks (bool) – Automatic Black Duck Code Center compliance checks will occur after the build completes (default false)

• black-duck-include-published-artifacts (bool) – Include the build’s published module artifacts in the license violation checks if they are also used as dependencies for other modules in this build (default false)

• auto-create-missing-component-requests (bool) – Auto create missing components in Black Duck Code Center application after the build is completed and deployed in Artifactory (default true)

• auto-discard-stale-component-requests (bool) – Auto discard stale components in Black Duck Code Center application after the build is completed and deployed in Artifactory (default true)

• deploy-artifacts (bool) – Push artifacts to the Artifactory Server. The specific artifacts to push are controlled using the deployment-include-patterns and deployment-exclude-patterns. (default true)

• deployment-include-patterns (list) – List of patterns for including build artifacts to publish to artifactory. (default[]’)

• deployment-exclude-patterns (list) – List of patterns for excluding artifacts from deployment to Artifactory (default [])

• env-vars-include (bool) – Include environment variables accessible by the build process. Jenkins-specific env variables are always included. Environment variables can be filtered using the env-vars-include-patterns nad env-vars-exclude-patterns. (default false)

• env-vars-include-patterns (list) – List of environment variable patterns that will be included as part of the published build info. Environment variables may contain the * and the ? wildcards (default [])

• env-vars-exclude-patterns (list) – List of environment variable patterns that will be excluded from the published build info (default [])

Example:

wrappers:
  - artifactory-maven-freestyle:
      url: http://artifactory.example.net/artifactory
      name: 'test'
      repo-key: repo
      matrix-params:
      - 'custom_prop=${PROJECT_ENV_VAR}'
      deployment-include-patterns:
      - '*.zip=>results'
      env-vars-include: true
      env-vars-include-patterns:
      - 'PROJECT_*'
      - 'ORG_*'

build-keeper()

Keep builds based on specific policy.

Requires the Jenkins Build Keeper Plugin.

Parameters:

• policy (str) –

  Policy to keep builds.

  policy values:

  • by-day

  • keep-since

  • build-number

  • keep-first-failed

  • run-condition

• build-period (int) – Number argument to calculate build to keep, depends on the policy. (default 0)

• dont-keep-failed (bool) – Flag to indicate if to keep failed builds. (default false)

• number-of-fails (int) – number of consecutive failed builds in order to mark first as keep forever, only applies to keep-first-failed policy (default 0)

• keep-build (bool) – Build will be kept if there is a problem evaluating the RunCondition (default false)

• token (str) – Token value for the boolean condition (default ‘’)

• build-cause (list) – The cause why the build was triggered (default USER_CAUSE)

• exclusive-cause (bool) – Cause must be the only one causing this build to be triggered (default False)

• command (str) – Contents of your shell script (default ‘’)

• allowed-nodes (str) – Node to be executed on (default ‘’)

• expression (str) – The regular expression used to match the label (default ‘’)

• label (str) – The label that will be tested by the regular expression (default ‘’)

• arg1 (str) – First string argument for strings-match condition (default ‘’)

• arg2 (str) – Second string argument for strings-match condition (default ‘’)

• ignore-case (bool) – Ignore the case of the strings when matching the two string arguments (default False)

Example:

wrappers:
  - build-keeper:
      policy: 'by-day'
      build-period: 10
      dont-keep-failed: true

wrappers:
  - build-keeper:
      policy: 'keep-first-failed'
      number-of-fails: 1

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.

• description (str) – Build description for the build (Optional).

• run-at-start (str) – Set build name before build starts (Optional, default: True).

• run-at-end (str) – Set build name after build ends (Optional, default: True).

Example:

wrappers:
  - build-name:
      name: Build-${FOO}
      description: lorem ipsum dolor
      run-at-start: true
      run-at-end: false

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

config-file-provider()

Provide configuration files (i.e., settings.xml for maven etc.) which will be copied to the job’s workspace.

Requires the Jenkins Config File Provider Plugin.

Parameters:

files (list) –

List of managed config files made up of three parameters

files:

• file-id (str) – The identifier for the managed config file

• target (str) – Define where the file should be created (default ‘’)

• variable (str) – Define an environment variable to be used (default ‘’)

• replace-tokens (bool) – Replace tokens in config file. For example “password: ${PYPI_JENKINS_PASS}” will be replaced with the global variable configured in Jenkins.

Full Example:

wrappers:
  - config-file-provider:
      files:
        - file-id: org.jenkinsci.plugins.configfiles.custom.CustomConfig1234
        - file-id: org.jenkinsci.plugins.configfiles.custom.CustomConfig5678
          target: /foo.txt
          variable: varName
          replace-tokens: true

Minimal Example:

wrappers:
  - config-file-provider:
      files:
        - file-id: org.jenkinsci.plugins.configfiles.custom.CustomConfig1234

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 (optional)

• excludes (list) – list of file patterns to exclude (optional)

• flatten (bool) – flatten directory structure (default false)

• relative-to (str) – base location of includes/excludes, must be home ($JENKINS_HOME), somewhereElse ($JENKINS_HOME/copyToSlave), userContent ($JENKINS_HOME/userContent) or workspace (default userContent)

• include-ant-excludes (bool) – exclude ant’s default excludes (default false)

Minimal Example:

wrappers:
    - copy-to-slave

Full Example:

wrappers:
    - copy-to-slave:
        includes:
            - 'file1'
            - 'file2*.txt'
        excludes:
            - 'file2bad.txt'
        flatten: True
        relative-to: 'somewhereElse'
        include-ant-excludes: True

credentials-binding()

Binds credentials to environment variables using the credentials binding plugin for jenkins.

Requires the Jenkins Credentials Binding Plugin version 1.1 or greater.

Parameters:

binding-type (list) –

List of each bindings to create. Bindings may be of type zip-file, file, username-password, text, username-password-separated or amazon-web-services. username-password sets a variable to the username and password given in the credentials, separated by a colon. username-password-separated sets one variable to the username and one variable to the password given in the credentials. amazon-web-services sets one variable to the access key and one variable to the secret access key. Requires the AWS Credentials Plugin .

Parameters:

• credential-id (str) UUID of the credential being referenced

• variable (str) Environment variable where the credential will be stored

• username (str) Environment variable for the username (Required for binding-type username-password-separated)

• password (str) Environment variable for the password (Required for binding-type username-password-separated)

• access-key (str) Environment variable for the access key (Required for binding-type amazon-web-services)

• secret-key (str) Environment variable for the access secret key (Required for binding-type amazon-web-services)

• key-file-variable (str) Environment variable to be set to the temporary path of the SSH key file during the build.

• username-variable (str) Environment variable to be set to the username during the build. (optional)

• passphrase-variable (str) Environment variable to be set to the password during the build. (optional)

• keystore-variable (str) Environment variable to be set to the temporary keystore location during the build.

• password-variable (str) Environment variable to be set to the password during the build.

• alias-variable (str) Environment variable to be set to the keystore alias name of the certificate during the build.

Example:

wrappers:
 - credentials-binding:
     - zip-file:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caa6
        variable: CONFIG_ZIP
     - file:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caab
        variable: config_file
     - username-password:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caac
        variable: config_username_password
     - text:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caad
        variable: config_text
     - docker-server-creds-binding:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caae
        variable: config_docker_server
 - credentials-binding:
     - username-password-separated:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caag
        username: myUsername
        password: myPassword
 - credentials-binding:
     - amazon-web-services:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caaf
        access-key: AWS_ACCESS_KEY_ID
        secret-key: AWS_SECRET_ACCESS_KEY
 - credentials-binding:
     - ssh-user-private-key:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caah
        key-file-variable: KEY_FILE_VARIABLE
        username-variable: USER_NAME_VARIABLE
        passphrase-variable: PASSPHRASE_VARIABLE
 - credentials-binding:
     - cert-multi-binding:
        credential-id: b3e6f337-5d44-4f57-921c-1632d796caaj
        keystore-variable: KEYSTORE_VARIABLE
        password-variable: PASSWORD_VARIABLE
        alias-variable: ALIAS_VARIABLE

custom-tools()

Requires the Jenkins Custom Tools Plugin.

Parameters:

• tools (list) – List of custom tools to add (optional)

• skip-master-install (bool) – skips the install in top level matrix job (default ‘false’)

• convert-homes-to-upper (bool) – Converts the home env vars to uppercase (default ‘false’)

Example:

wrappers:
  - custom-tools:
      tools:
      - my_custom_tool
      skip-master-install: true
      convert-homes-to-upper: true

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)

Minimal Example:

wrappers:
    - delivery-pipeline

Full Example:

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

docker-custom-build-env()

Allows the definition of a build environment for a job using a Docker container.

Requires the Jenkins CloudBees Docker Custom Build Environment Plugin.

Parameters:

• image-type (str) – Docker image type. Valid values and their additional attributes described in the image_types table

• docker-tool (str) – The name of the docker installation to use (default ‘Default’)

• host (str) – URI to the docker host you are using

• credentials-id (str) – Argument to specify the ID of credentials to use for docker host (optional)

• registry-credentials-id (str) – Argument to specify the ID of credentials to use for docker registry (optional)

• volumes (list) –

  Volumes to bind mound from slave host into container

  volume:

  • host-path (str) Path on host

  • path (str) Path inside container

• verbose (bool) – Log docker commands executed by plugin on build log (default false)

• privileged (bool) – Run in privileged mode (default false)

• force-pull (bool) – Force pull (default false)

• group (str) – The user to run build has to be the same as the Jenkins slave user so files created in workspace have adequate owner and permission set

• command (str) – Container start command (default ‘/bin/cat’)

• net (str) – Network bridge (default ‘bridge’)

• memory-limit (str) – Configure the limit memory constraint (default ‘’)

• cpu-shares (str) – Configure the CPU shares constraint (default ‘’)

Image Type	Description
dockerfile	Build docker image from a Dockerfile in project workspace. With this option, project can define the build environment as a Dockerfile stored in SCM with project source code context-path: (str) Path to docker context (default ‘.’) dockerfile: (str) Use an alternate Dockerfile to build the container hosting this build (default ‘Dockerfile’)
pull	Pull specified docker image from Docker repository image: (str) Image id/tag

Example:

wrappers:
  - docker-custom-build-env:
      image-type: 'pull'
      image: 'centos:7'
      force-pull: true
      privileged: true
      verbose: true
      group: jenkins
      command: /bin/cat
      net: bridge
      memory-limit: memory=L<inf, memory-swap=inf
      cpu-shares: 2

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 (optional)

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 ‘’)

• script-type (str) –

  The script type.

  script-types supported:

  • unix-script (default)

  • power-shell

  • batch-script

• 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

github-pull-request()

Set GitHub commit status with custom context and message.

Requires the Jenkins GitHub Pull Request Builder Plugin.

Parameters:

• show-matrix-status (bool) – Only post commit status of parent matrix job (default false)

• status-context (str) – The context to include on PR status comments (default ‘’)

• triggered-status (str) – The status message to set when the build has been triggered (default ‘’)

• started-status (str) – The status message to set when the build has been started (default ‘’)

• status-url (str) – The status URL to set (default ‘’)

• status-add-test-results (bool) – Add test result one-liner to status message (default false)

• statuses (list) –

  List of custom statuses on the commit for when a build is completed

  Status:

  • message (str) – The message that is appended to a comment when a build finishes with the desired build status. If no status updates should be made when a build finishes with the indicated build status, use “–none–” to alert the trigger. (required)

  • result (str) – Build result. Can be one of ‘SUCCESS’, ‘ERROR’ or ‘FAILURE’. (required)

Minimal Example:

wrappers:
  - github-pull-request

Full Example:

wrappers:
  - github-pull-request:
      show-matrix-status: true
      status-context: "my-build"
      triggered-status: "build was triggered"
      started-status: "build was started"
      status-url: "http://1.2.3.4"
      status-add-test-results: true
      statuses:
        - message: "build has succeeded"
          result: SUCCESS
        - message: "build has failed"
          result: ERROR

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 (optional)

• properties-content (str) – key value pair of properties (optional)

• script-file (str) – path to the script file (optional)

• script-content (str) – contents of a script (optional)

• load-from-master (bool) – load files from master (default false)

• groovy-script (str) – contents of the groovy script (optional)

• groovy-sandbox (bool) – use groovy sandbox (default false)

Minimal Example:

wrappers:
    - inject

Full Example:

wrappers:
    - inject:
        properties-file: example.prop full
        properties-content: EXAMPLE=foo-bar full
        script-file: scriptfull.sh
        script-content: test script content full
        groovy-script: test groovy-script location full
        groovy-sandbox: true

inject-ownership-variables()

Inject ownership variables to the build as environment variables.

Requires the Jenkins EnvInject Plugin and Jenkins Ownership 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

• mask-password-params (bool) – mask password parameters

• 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
        mask-password-params: 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

job-log-logger()

Enable writing the job log to the underlying logging system.

Requires the Jenkins Job Log Logger plugin.

Parameters:

suppress-empty (bool) – Suppress empty log messages (default true)

Example:

wrappers:
  - job-log-logger:
      suppress-empty: false

live-screenshot()

Show live screenshots of running jobs in the job list.

Requires the Jenkins Live-Screenshot Plugin.

Parameters:

• full-size (str) – name of screenshot file (default ‘screenshot.png’)

• thumbnail (str) – name of thumbnail file (default ‘screenshot-thumb.png’)

File type must be .png and they must be located inside the $WORKDIR.

Full Example:

wrappers:
    - live-screenshot:
        full-size: my_screenshot.png
        thumbnail: my_screenshot-thumb.png

Minimal Example:

wrappers:
    - live-screenshot

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.

Full Example:

wrappers:
  - logfilesize:
      set-own: true
      size: 1024
      fail: true

Minimal Example:

wrappers:
  - logfilesize

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'

m2-repository-cleanup()

Configure M2 Repository Cleanup.

Requires the Jenkins M2 Repository Cleanup.

Parameters:

patterns (list) – List of patterns for artifacts to cleanup before building. (optional)

This plugin allows you to configure a maven2 job to clean some or all of the artifacts from the repository before it runs.

Example:

wrappers:
    - m2-repository-cleanup:
        patterns:
            - com/ibm/**
            - com/microsoft/**

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. You can use the top level node parameter to control where the parent job is tied in Jenkins 1.532 and higher.

Parameters:

node (str) – Name of the node (required)

Example:

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

maven-release()

Wrapper for Maven projects

Requires the Jenkins M2 Release Plugin

Parameters:

• release-goals (str) – Release goals and options (default ‘’)

• dry-run-goals (str) – DryRun goals and options (default ‘’)

• num-successful-builds (int) – Number of successful release builds to keep (default 1)

• select-custom-scm-comment-prefix (bool) – Preselect ‘Specify custom SCM comment prefix’ (default false)

• select-append-jenkins-username (bool) – Preselect ‘Append Jenkins Username’ (default false)

• select-scm-credentials (bool) – Preselect ‘Specify SCM login/password’ (default false)

• release-env-var (str) – Release environment variable (default ‘’)

• scm-user-env-var (str) – SCM username environment variable (default ‘’)

• scm-password-env-var (str) – SCM password environment variable (default ‘’)

Example:

wrappers:
  - maven-release:
      release-goals: -Dresume=false release:prepare release:perform
      dry-run-goals: -Dresume=false -DdryRun=true release:prepare
      num-successful-builds: 1
      select-custom-scm-comment-prefix: false
      select-append-jenkins-username: false
      select-scm-credentials: false
      release-env-var: IS_M2RELEASEBUILD
      scm-user-env-var: SCM_USER

mongo-db build wrapper()

Initializes a MongoDB database while running the build.

Requires the Jenkins MongoDB plugin.

Parameters:

• name (str) – The name of the MongoDB install to use (required)

• data-directory (str) – Data directory for the server (default ‘’)

• port (int) – Port for the server (default ‘’)

• startup-params (str) – Startup parameters for the server (default ‘’)

• start-timeout (int) – How long to wait for the server to start in milliseconds. 0 means no timeout. (default 0)

Full Example:

wrappers:
  - mongo-db:
      name: 2.4.6
      data-directory: /var/tmp/mongo
      port: 5555
      startup-params: "--bind_ip 127.0.0.1"
      start-timeout: 5000

Minimal Example:

wrappers:
  - mongo-db:
      name: 2.4.6

nodejs-installator()

Provides Jenkins integration for NodeJS & npm packages.

Requires the Jenkins NodeJS Plugin.

Parameters:

name (str) – nodejs installation name (required)

Example:

wrappers:
  - nodejs-installator:
      name: "latest node"

openstack()

Provision slaves from OpenStack on demand.

Requires the Jenkins Openstack Cloud Plugin.

Parameters:

• instances (list) –

  List of instances to be launched at the beginning of the build.

  instances:

  • cloud-name (str) – The name of the cloud profile which contains the specified cloud instance template (required).

  • template-name (str) – The name of the cloud instance template to create an instance from(required).

  • manual-template (bool) – If True, instance template name will be put in ‘Specify Template Name as String’ option. Not specifying or specifying False, instance template name will be put in ‘Select Template from List’ option. To use parameter replacement, set this to True. (default false)

  • count (int) – How many instances to create (default 1).

• single-use (bool) – Whether or not to terminate the slave after use (default false).

Example:

wrappers:
  - openstack:
      instances:
        - cloud-name: mycloud1
          template-name: jenkins-dev-slave
          count: 1
        - cloud-name: mycloud2
          template-name: jenkins-test-slave
          manual-template: True
          count: 2
      single-use: True

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) – Deprecated, use names instead

• names (list) – Variable list of names of the port or list of specific port numbers

Example:

wrappers:
    - port-allocator:
        names:
            - SERVER_PORT
            - SERVER_PORT2

pre-scm-buildstep()

Execute a Build Step before running the SCM.

Requires the Jenkins Pre SCM BuildStep.

Parameters:

• failOnError (str) – Specifies if the job should fail on error (plugin >= 0.3) (default false).

• buildsteps (list) –

  List of build steps to execute

  Buildstep:

  Any acceptable builder, as seen in the example

Example:

wrappers:
  - pre-scm-buildstep:
      failOnError: true
      buildsteps:
        - shell: |
            #!/bin/bash
            echo "Doing something cool"
        - shell: |
            #!/bin/zsh
            echo "Doing something 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/rbenv/rbenv)

• 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/rbenv/ruby-build)

• 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 (default false)

• version-template (str) – Release version template (default ‘’)

• 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.
          - bool:
              name: FOO
              default: false
              description: "A parameter named FOO, defaults to 'false'."
      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 connect 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

sonar()

Wrapper for SonarQube Plugin.

Requires SonarQube plugin

Parameters:

install-name (str) – Release goals and options (default ‘’)

Minimal Example:

wrappers:
  - sonar

Full Example:

wrappers:
  - sonar:
      install-name: test-sonar-installation

ssh-agent-credentials()

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

Requires the Jenkins SSH-Agent Plugin.

Parameters:

• users (list) – A list of Jenkins users credential IDs (required)

• user (str) – The user id of the jenkins user credentials (deprecated)

• ignore-missing-credentials (bool) – Specifies the option to ignore missing credentials (default false)

Example:

wrappers:
  - ssh-agent-credentials:
        users:
            - '44747833-247a-407a-a98f-a5a2d785111c'
            - 'f1c0f777-7ac6-43fd-b5c7-68b420aa1392'
            - 'dd647a01-be21-402b-bfc5-a4e89be7d0c4'

if both users and user parameters specified, users will be

preferred, user will be ignored.

Example:

wrappers:
    - ssh-agent-credentials:
        user: '49d20745-9889-4c02-b286-fc6fb89c36bd'
        users:
            - '44747833-247a-407a-a98f-a5a2d785111c'
            - 'dd647a01-be21-402b-bfc5-a4e89be7d0c4'

Example:

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

equals to:

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)

• abort (bool) – Mark the build as aborted (default false)

• abort-and-restart (bool) – Mark the build as aborted, then restart. Count of restarts can be set via max-restarts (default false) (Version >= 1.17).

• write-description (bool) – Write a message in the description (default false)

• max-restarts (int) – Count of maximum restarts. 0 means without a limit (default 0) (Version >= 1.17).

• 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, only applies to elastic type. (default 0)

• elastic-number-builds (int) – Number of builds to consider computing average duration, only applies to elastic type. (default 3)

• elastic-default-timeout (int) – Timeout to use if there were no previous builds, only applies to elastic type. (default 3)

• deadline-time (str) – Build terminate automatically at next deadline time (HH:MM:SS), only applies to deadline type. (default 0:00:00)

• deadline-tolerance (int) – Period in minutes after deadline when a job should be immediately aborted, only applies to deadline type. (default 1)

Example (Version < 1.14):

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

Example (Version >= 1.14):

wrappers:
  - timeout:
      timeout: 90
      timeout-var: 'BUILD_TIMEOUT'
      fail: true
      type: absolute

wrappers:
  - timeout:
      timeout: 5
      timeout-var: 'BUILD_TIMEOUT'
      type: no-activity
      abort: true
      write-description: "Blah Blah Blah"

wrappers:
  - timeout:
      timeout: 90
      timeout-var: 'BUILD_TIMEOUT'
      abort: true
      type: likely-stuck

wrappers:
  - timeout:
      elastic-percentage: 150
      elastic-default-timeout: 3
      elastic-number-builds: 14
      timeout-var: 'BUILD_TIMEOUT'
      abort: true
      type: elastic

 wrappers:
    - timeout:
        deadline-time: '0:00:00'
        deadline-tolerance: 1
        timeout-var: 'BUILD_TIMEOUT'
        type: deadline

timestamps()

Add timestamps to the console log.

Requires the Jenkins Timestamper Plugin.

Example:

wrappers:
  - timestamps

vault-secrets()

Inject environment variables from a HashiCorp Vault secret.

Secrets are generally masked in the build log.

Requires the Jenkins HashiCorp Vault Plugin.

Parameters:

• vault-url (str) – Vault URL

• credentials-id (str) – Vault Credential

• engine-version (str) – Vault K/V Engine version

• fail-if-not-found (bool) – Fail if the secret path is not found

• skip-ssl-verification (bool) – Skip verification of SSL certs

• secrets (list) –

  List of secrets

  secrets:

  • secret-path (str) – The path of the secret in the vault server

  • engine-version (str) – Vault K/V Engine version

  secret-values:

  • secret-values (list) – List of key / value pairs

    • env-var (str) – The environment variable to set with the value of the vault key

    • vault-key (str) – The vault key whose value with populate the environment variable

Minimal Example:

wrappers:
  - vault-secrets:
      vault-url: 'http://127.0.0.1:8200'
      credentials-id: 'myCredentials'
      secrets:
        - secret-path: 'secret/my-token'
          secret-values:
            - env-var: 'TOKEN'
              vault-key: 'token'

Full Example:

wrappers:
  - vault-secrets:
      vault-url: 'http://127.0.0.1:8200'
      credentials-id: 'myCredentials'
      fail-if-not-found: 'false'
      skip-ssl-verification: 'true'
      engine-version: '2'
      secrets:
        - secret-path: 'secret/my-secret'
          secret-values:
            - env-var: 'USERNAME'
              vault-key: 'username'
            - env-var: 'PASSWORD'
              vault-key: 'password'
        - secret-path: 'secret/my-secret2'
          engine-version: '2'
          secret-values:
            - env-var: 'USERNAME2'
              vault-key: 'username2'
            - env-var: 'PASSWORD2'
              vault-key: 'password2'

version-number()

Generate a version number for the build using a format string. See the wiki page for more detailed descriptions of options.

Requires the Jenkins Version number plugin.

Parameters:

• variable-name (str) – Name of environment variable to assign version number to (required)

• format-string (str) – Format string used to generate version number (required)

• prefix-variable (str) – Variable that contains version number prefix (optional)

• skip-failed-builds (bool) – If the build fails, DO NOT increment any auto-incrementing component of the version number (default: false)

• display-name (bool) – Use the version number for the build display name (default: false)

• start-date (str) – The date the project began as a UTC timestamp (default 1970-1-1 00:00:00.0 UTC)

• builds-today (int) – The number of builds that have been executed today (optional)

• builds-this-month (int) – The number of builds that have been executed since the start of the month (optional)

• builds-this-year (int) – The number of builds that have been executed since the start of the year (optional)

• builds-all-time (int) – The number of builds that have been executed since the start of the project (optional)

Example:

wrappers:
  - version-number:
      variable-name: relVersion
      prefix-variable: relVersion
      format-string: ${BUILD_DATE_FORMATTED, "yy.M"}.${BUILDS_THIS_MONTH_Z}

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 (default false)

• check-parameter (str) – boolean environment variable to check to determine whether to actually clean up

• external-deletion-command (str) – external deletion command to run against files and directories

• disable-deferred-wipeout (bool) – Disable improved deferred wipeout method (default false)

Full Example:

wrappers:
  - workspace-cleanup:
      include:
        - "_generated.py"
      exclude:
        - "*.py"
      dirmatch: true
      check-parameter: "DO_WS_CLEANUP"
      external-deletion-command: "shred -u %s"
      disable-deferred-wipeout: true

Minimal Example:

wrappers:
  - workspace-cleanup

xvfb()

Enable xvfb during the build.

Requires the Jenkins Xvfb Plugin.

Parameters:

• installation-name (str) – The name of the Xvfb tool installation (default ‘default’)

• auto-display-name (bool) – Uses the -displayfd option of Xvfb by which it chooses it’s own display name (default false)

• display-name (str) – Ordinal of the display Xvfb will be running on, if left empty chosen based on current build executor number (default ‘’)

• assigned-labels (str) – If you want to start Xvfb only on specific nodes specify its name or label (default ‘’)

• parallel-build (bool) – When running multiple Jenkins nodes on the same machine this setting influences the display number generation (default false)

• timeout (int) – A timeout of given seconds to wait before returning control to the job (default 0)

• screen (str) – Resolution and color depth. (default ‘1024x768x24’)

• display-name-offset (int) – Offset for display names. (default 1)

• additional-options (str) – Additional options to be added with the options above to the Xvfb command line (default ‘’)

• debug (bool) – If Xvfb output should appear in console log of this job (default false)

• shutdown-with-build (bool) – Should the display be kept until the whole job ends (default false)

Full Example:

wrappers:
  - xvfb:
      installation-name: default
      auto-display-name: false
      display-name: 123
      assigned-labels: nodes-xxx
      parallel-build: false
      timeout: 10
      screen: 1024x768x16
      display-name-offset: 100
      additional-options: -fbdir /tmp
      debug: true
      shutdown-with-build: false

Minimal Example:

wrappers:
  - xvfb

xvnc()

Enable xvnc during the build.

Requires the Jenkins xvnc plugin.

Parameters:

• screenshot (bool) – Take screenshot upon build completion (default false)

• xauthority (bool) – Create a dedicated Xauthority file per build (default true)

Full Example:

wrappers:
  - xvnc:
      screenshot: true
      xauthority: false

Minimal Example:

wrappers:
  - xvnc