Builders

Builders define actions that the Jenkins job should execute. Examples include shell scripts or maven targets. The builders attribute in the Job definition accepts a list of builders to invoke. They may be components defined below, locally defined macros (using the top level definition of builder:, or locally defined components found via the jenkins_jobs.builders entry point.

Component: builders
Macro:builder
Entry Point:jenkins_jobs.builders

Example:

job:
  name: test_job

  builders:
    - shell: "make test"
ant

Execute an ant target. Requires the Jenkins Ant Plugin.

To setup this builder you can either reference the list of targets or use named parameters. Below is a description of both forms:

1) Listing targets:

After the ant directive, simply pass as argument a space separated list of targets to build.

Parameter:space separated list of Ant targets

Example to call two Ant targets:

builders:
  - ant: "target1 target2"

The build file would be whatever the Jenkins Ant Plugin is set to use per default (i.e build.xml in the workspace root).

2) Using named parameters:

Parameters:
  • targets (str) – the space separated list of ANT targets.
  • buildfile (str) – the path to the ANT build file.
  • properties (list) – Passed to ant script using -Dkey=value (optional)
  • ant-name (str) – the name of the ant installation, (default ‘default’) (optional)
  • java-opts (str) – java options for ant, can have multiples, must be in quotes (optional)

Example specifying the build file too and several targets:

builders:
  - ant:
     targets: "debug test install"
     buildfile: "build.xml"
     properties:
        builddir: "/tmp/"
        failonerror: true
     java-opts:
        - "-ea"
        - "-Xmx512m"
     ant-name: "Standard Ant"
artifact-resolver

Allows one to resolve artifacts from a maven repository like nexus (without having maven installed) Requires the Jenkins Repository Connector Plugin.

Parameters:
  • fail-on-error (bool) – Whether to fail the build on error (default false)
  • repository-logging (bool) – Enable repository logging (default false)
  • target-directory (str) – Where to resolve artifacts to
  • artifacts (list) –

    list of artifacts to resolve

    Artifact:
    • group-id (str) – Group ID of the artifact
    • artifact-id (str) – Artifact ID of the artifact
    • version (str) – Version of the artifact
    • classifier (str) – Classifier of the artifact (default ‘’)
    • extension (str) – Extension of the artifact (default ‘jar’)
    • target-file-name (str) – What to name the artifact (default ‘’)

Example:

builders:
  - artifact-resolver:
      fail-on-error: true
      repository-logging: true
      target-directory: foo
      artifacts:
        - group-id: commons-logging
          artifact-id: commons-logging
          version: "1.1"
          classifier: src
          extension: jar
          target-file-name: comm-log.jar
        - group-id: commons-lang
          artifact-id: commons-lang
          version: "1.2"
batch

Execute a batch command.

Parameter:the batch command to execute

Example:

builders:
  - batch: "foo/foo.bat"
beaker

Execute a beaker build step. Requires the Jenkins Beaker Builder Plugin.

Parameters:
  • content (str) – Run job from string (Alternative: you can choose a path instead)
  • path (str) – Run job from file (Alternative: you can choose a content instead)
  • download-logs (bool) – Download Beaker log files (default false)

Example:

builders:
    - beaker:
        path: 'test.xml'
        download-logs: true

builders:
    - beaker:
        content: |
            <job group='product-QA'>
                <whiteboard>
                    Apache 2.2 test
                </whiteboard>
            </job>
build-name-setter

Define Build Name Setter options which allows your build name to be updated during the build process. Requires the Jenkins Build Name Setter Plugin.

Parameters:
  • name (str) – Filename to use for Build Name Setter, only used if file bool is true. (default ‘version.txt’)
  • template (str) – Macro Template string, only used if macro bool is true. (default ‘#${BUILD_NUMBER}’)
  • file (bool) – Read from named file (default false)
  • macro (bool) – Read from macro template (default false)
  • macro-first (bool) – Insert macro first (default false)

File Example:

builders:
      - build-name-setter:
          name: 'version.txt'
          file: true

Macro Example:

builders:
      - build-name-setter:
          template: '#${BUILD_NUMBER}'
          macro: true
builders-from

Use builders from another project. Requires the Jenkins Template Project Plugin.

Parameters:projectName (str) – the name of the other project

Example:

builders:
  - builders-from: "base-build"
change-assembly-version

Change the assembly version. Requires the Jenkins Change Assembly Version.

Parameters:
  • version (str) – Set the new version number for replace (default 1.0.0)
  • assemblyFile (str) – The file name to search (default AssemblyInfo.cs)

Example:

builders:
  - change-assembly-version:
        version: "1.2.3"
        assembly-file: "AFile"
cloudformation

Create cloudformation stacks before running a build and optionally delete them at the end. Requires the Jenkins AWS Cloudformation Plugin.

Parameters:
  • name (list) – The names of the stacks to create (required)
  • description (str) – Description of the stack (optional)
  • recipe (str) – The cloudformation recipe file (required)
  • parameters (list) – List of key/value pairs to pass into the recipe, will be joined together into a comma separated string (optional)
  • timeout (int) – Number of seconds to wait before giving up creating a stack (default 0)
  • access-key (str) – The Amazon API Access Key (required)
  • secret-key (str) – The Amazon API Secret Key (required)
  • sleep (int) – Number of seconds to wait before continuing to the next step (default 0)
  • region (array) –

    The region to run cloudformation in (required)

    region values:
    • us-east-1
    • us-west-1
    • us-west-2
    • eu-central-1
    • eu-west-1
    • ap-southeast-1
    • ap-southeast-2
    • ap-northeast-1
    • sa-east-1

Example:

builders:
  - cloudformation:
    - name: "foo"
      description: "Build the foo stack"
      recipe: "foo.json"
      parameters:
        - "Key1=foo"
        - "Key2=fuu"
      timeout: 3600
      access-key: "$AWS_ACCESS_KEY"
      secret-key: "$AWS_SECRET_KEY"
      region: us-west-2
      sleep: 5
    - name: "bar"
      description: "Build the bar stack"
      recipe: "bar.json"
      parameters:
        - "Key1=bar"
        - "Key2=baa"
      timeout: 3600
      access-key: "$AWS_ACCESS_KEY"
      secret-key: "$AWS_SECRET_KEY"
      region: us-west-1
cmake

Execute a CMake target. Requires the Jenkins CMake Plugin.

This builder is compatible with both versions 2.x and 1.x of the plugin. When specifying paramenters from both versions only the ones from the installed version in Jenkins will be used, and the rest will be ignored.

Parameters:
  • source-dir (str) – the source code directory relative to the workspace directory. (required)
  • build-type (str) – Sets the “build type” option for CMake (default “Debug”).
  • preload-script (str) – Path to a CMake preload script file. (optional)
  • other-arguments (str) – Other arguments to be added to the CMake call. (optional)
  • clean-build-dir (bool) – If true, delete the build directory before each build (default false).
  • generator (list) –

    The makefile generator (default “Unix Makefiles”).

    type Possible generators:
     
    • Borland Makefiles
    • CodeBlocks - MinGW Makefiles
    • CodeBlocks - Unix Makefiles
    • Eclipse CDT4 - MinGW Makefiles
    • Eclipse CDT4 - NMake Makefiles
    • Eclipse CDT4 - Unix Makefiles
    • MSYS Makefiles
    • MinGW Makefiles
    • NMake Makefiles
    • Unix Makefiles
    • Visual Studio 6
    • Visual Studio 7 .NET 2003
    • Visual Studio 8 2005
    • Visual Studio 8 2005 Win64
    • Visual Studio 9 2008
    • Visual Studio 9 2008 Win64
    • Watcom WMake
Version 2.x:

Parameters that available only to versions 2.x of the plugin

  • working-dir (str): The directory where the project will be built in. Relative to the workspace directory. (optional)

  • installation-name (str): The CMake installation to be used on this builder. Use one defined in your Jenkins global configuration page (default “InSearchPath”).

  • build-tool-invocations (list): list of build tool invocations that will happen during the build:

    Build tool invocations:
     
    • use-cmake (str) – Whether to run the actual build tool

      directly (by expanding $CMAKE_BUILD_TOOL) or to have cmake run the build tool (by invoking cmake --build <dir>) (default false).

    • arguments (str) – Specify arguments to pass to the

      build tool or cmake (separated by spaces). Arguments may contain spaces if they are enclosed in double quotes. (optional)

    • environment-variables (str) – Specify extra

      environment variables to pass to the build tool as key-value pairs here. Each entry must be on its own line, for example:

      DESTDIR=${WORKSPACE}/artifacts/dir

      KEY=VALUE
Version 1.x:

Parameters available only to versions 1.x of the plugin

  • build-dir (str): The directory where the project will be built in. Relative to the workspace directory. (optional)

  • install-dir (str): The directory where the project will be installed in, relative to the workspace directory. (optional)

  • build-type (list): Sets the “build type” option. A custom type different than the default ones specified on the CMake plugin can also be set, which will be automatically used in the “Other Build Type” option of the plugin. (default “Debug”)

    Default types present in the CMake plugin:
     
    • Debug
    • Release
    • RelWithDebInfo
    • MinSizeRel

  • make-command (str): The make command (default “make”).

  • install-command (arg): The install command (default “make install”).

  • custom-cmake-path (str): Path to cmake executable. (optional)

  • clean-install-dir (bool): If true, delete the install dir before each build (default false).

Example (Versions 2.x):

builders:
  - cmake:
      source-dir: 'path/to/source'
      working-dir: 'path/to/build'
      install-dir: 'path/to/install'
      build-type: 'CustomReleaseType'
      generator: 'NMake Makefiles'
      installation-name: 'CMake custom install'
      preload-script: 'path/to/source/cmake.preload'
      other-arguments: '-DCMAKE_FIND_ROOT_PATH="path/to/something/else"'
      clean-build-dir: true
      build-tool-invocations:
        - use-cmake: true
          arguments: 'clean'
          environment-variables: |
            DESTDIR=${WORKSPACE}/artifacts/dir
            URL=http://www.example.org/
        - use-cmake: false
          arguments: 'test'
          environment-variables: |
            RESTRICT="TRUE"
            TARGET="NONE"

Example (Versions 1.x):

builders:
  - cmake:
      source-dir: 'path/to/source'
      build-dir: 'path/to/build'
      install-dir: 'path/to/install'
      build-type: 'CustomReleaseType'
      generator: 'NMake Makefiles'
      make-command: '/usr/bin/make'
      install-command: 'make new-install'
      preload-script: 'path/to/source/cmake.preload'
      other-arguments: '-DCMAKE_FIND_ROOT_PATH="path/to/something/else"'
      custom-cmake-path: '/usr/bin/cmake'
      clean-build-dir: true
      clean-install-dir: true
conditional-step

Conditionally execute some build steps. Requires the Jenkins Conditional BuildStep Plugin.

Depending on the number of declared steps, a Conditional step (single) or a Conditional steps (multiple) is created in Jenkins.

Parameters:
  • condition-kind (str) – Condition kind that must be verified before the steps are executed. Valid values and their additional attributes are described in the conditions table.
  • on-evaluation-failure (str) – What should be the outcome of the build if the evaluation of the condition fails. Possible values are fail, mark-unstable, run-and-mark-unstable, run and dont-run. (default ‘fail’).
  • steps (list) – List of steps to run if the condition is verified. Items in the list can be any builder known by Jenkins Job Builder.
Condition kind Description
always Condition is always verified
never Condition is never verified
boolean-expression

Run the step if the expression expends to a representation of true

condition-expression:
 Expression to expand (required)
build-cause

Run if the current build has a specific cause

cause:

The cause why the build was triggered. Following causes are supported -

USER_CAUSE:build was triggered by a manual interaction. (default)
SCM_CAUSE:build was triggered by a SCM change.
TIMER_CAUSE:build was triggered by a timer.
CLI_CAUSE:build was triggered by via CLI interface
REMOTE_CAUSE:build was triggered via remote interface.
UPSTREAM_CAUSE:build was triggered by an upstream project.

Following supported if XTrigger plugin installed:

FS_CAUSE:build was triggered by a file system change (FSTrigger Plugin).
URL_CAUSE:build was triggered by a URL change (URLTrigger Plugin)
IVY_CAUSE:build triggered by an Ivy dependency version has change (IvyTrigger Plugin)
SCRIPT_CAUSE:build was triggered by a script (ScriptTrigger Plugin)
BUILDRESULT_CAUSE:
 build was triggered by a result of an other job (BuildResultTrigger Plugin)
exclusive-cause:
 

(bool) There might by multiple casues causing a build to be triggered, with this true, the cause must be the only one causing this build this build to be triggered. (default False)
day-of-week

Only run on specific days of the week.

day-selector:

Days you want the build to run on. Following values are supported -

weekend:

Saturday and Sunday (default).
weekday:

Monday - Friday.
select-days:

Selected days, defined by ‘days’ below.
days:

True for days for which the build should run. Definition needed only for ‘select-days’ day-selector, at the same level as day-selector. Define the days to run under this.

SUN:Run on Sunday (default False)
MON:Run on Monday (default False)
TUES:Run on Tuesday (default False)
WED:Run on Wednesday (default False)
THURS:Run on Thursday (default False)
FRI:Run on Friday (default False)
SAT:Run on Saturday (default False)
use-build-time:

(bool) Use the build time instead of the the time that the condition is evaluated. (default False)
execution-node

Run only on selected nodes.

nodes:(list) List of nodes to execute on. (required)
strings-match

Run the step if two strings match

condition-string1:
 First string (optional)
condition-string2:
 Second string (optional)
condition-case-insensitive:
 Case insensitive (default False)
current-status

Run the build step if the current build status is within the configured range

condition-worst:
 Accepted values are SUCCESS, UNSTABLE, FAILURE, NOT_BUILD, ABORTED (default SUCCESS)
condition-best:Accepted values are SUCCESS, UNSTABLE, FAILURE, NOT_BUILD, ABORTED (default SUCCESS)
shell

Run the step if the shell command succeed

condition-command:
 Shell command to execute (optional)
windows-shell

Similar to shell, except that commands will be executed by cmd, under Windows

condition-command:
 Command to execute (optional)
file-exists

Run the step if a file exists

condition-filename:
 Check existence of this file (required)
condition-basedir:
 If condition-filename is relative, it will be considered relative to either workspace, artifact-directory, or jenkins-home. (default ‘workspace’)
files-match

Run if one or more files match the selectors.

include-pattern:
 (list str) List of Includes Patterns. Since the separator in the patterns is hardcoded as ‘,’, any use of ‘,’ would need escaping. (optional)
exclude-pattern:
 (list str) List of Excludes Patterns. Since the separator in the patterns is hardcoded as ‘,’, any use of ‘,’ would need escaping. (optional)
condition-basedir:
 Accepted values are workspace, artifact-directory, or jenkins-home. (default ‘workspace’)
num-comp

Run if the numerical comparison is true.

lhs:Left Hand Side. Must evaluate to a number. (required)
rhs:Right Hand Side. Must evaluate to a number. (required)
comparator:Accepted values are less-than, greater-than, equal, not-equal, less-than-equal, greater-than-equal. (default ‘less-than’)
regex-match

Run if the Expression matches the Label.

regex:The regular expression used to match the label (optional)
label:The label that will be tested by the regular expression. (optional)
time

Only run during a certain period of the day.

earliest-hour:Starting hour (default “09”)
earliest-min:Starting min (default “00”)
latest-hour:Ending hour (default “17”)
latest-min:Ending min (default “30”)
use-build-time:(bool) Use the build time instead of the the time that the condition is evaluated. (default False)
not

Run the step if the inverse of the condition-operand is true

condition-operand:
 Condition to evaluate. Can be any supported conditional-step condition. (required)
and

Run the step if logical and of all conditional-operands is true

condition-operands:
 (list) Conditions to evaluate. Can be any supported conditional-step condition. (required)
or

Run the step if logical or of all conditional-operands is true

condition-operands:
 (list) Conditions to evaluate. Can be any supported conditional-step condition. (required)

Example:

builders:
      - conditional-step:
          condition-kind: current-status
          condition-worst: SUCCESS
          condition-best: FAILURE
          steps:
              - shell: "sl"

builders:
      - conditional-step:
          condition-kind: not
          condition-operand:
              condition-kind: file-exists
              condition-filename: mytestfile
              condition-basedir: workspace
          steps:
              - shell: "touch $WORKSPACE/mytestfile"

builders:
      - conditional-step:
          condition-kind: day-of-week
          day-selector: weekday
          use-build-time: true
          steps:
              - shell: "sl"

builders:
      - conditional-step:
          condition-kind: day-of-week
          day-selector: select-days
          days:
              MON: true
              FRI: true
          use-build-time: true
          steps:
              - shell: "sl"

builders:
    - conditional-step:
        condition-kind: time
        earliest-hour: "4"
        earliest-min: "15"
        latest-hour: "20"
        latest-min: "30"
        steps:
            - shell: "sl"

builders:
    - conditional-step:
        condition-kind: regex-match
        regex: a*b
        label: cadaaab
        steps:
            - shell: "sl"

builders:
      - conditional-step:
          condition-kind: or
          condition-operands:
              - condition-kind: num-comp
                lhs: "2 + 5"
                rhs: "1 + 6"
                comparator: equal
                condition-basedir: "jenkins-home"
              - condition-kind: files-match
                include-pattern:
                    - "inc_pattern1"
                    - "inc_pattern2"
                exclude-pattern:
                    - "exc_pattern1"
                    - "exc_pattern2"
                condition-basedir: "jenkins-home"
          steps:
              - shell: "sl"

builders:
      - conditional-step:
          condition-kind: and
          condition-operands:
              - condition-kind: regex-match
                regex: "*abc*"
                label: "dabcddabc"
              - condition-kind: time
                earliest-hour: "2"
                earliest-min: "0"
                latest-hour: "23"
                latest-min: "40"
                use-build-time: true
          steps:
              - shell: "sl"
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 (optional)
  • variable (str) – Define an environment variable to be used (optional)

Example:

builders:
    - config-file-provider:
        files:
            - file-id: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012
              target: target
              variable: variable
copyartifact

Copy artifact from another project. Requires the Copy Artifact plugin.

Please note using the multijob-build for which-build argument requires the Multijob plugin

Parameters:
  • project (str) – Project to copy from
  • filter (str) – what files to copy
  • target (str) – Target base directory for copy, blank means use workspace
  • flatten (bool) – Flatten directories (default false)
  • optional (bool) – If the artifact is missing (for any reason) and optional is true, the build won’t fail because of this builder (default false)
  • do-not-fingerprint (bool) – Disable automatic fingerprinting of copied artifacts (default false)
  • which-build (str) –

    which build to get artifacts from (optional, default last-successful)

    which-build values:
     
    • last-successful
    • last-completed
    • specific-build
    • last-saved
    • upstream-build
    • permalink
    • workspace-latest
    • build-param
    • downstream-build
    • multijob-build
  • build-number (str) – specifies the build number to get when when specific-build is specified as which-build
  • permalink (str) –

    specifies the permalink to get when permalink is specified as which-build

    permalink values:
     
    • last
    • last-stable
    • last-successful
    • last-failed
    • last-unstable
    • last-unsuccessful
  • stable (bool) – specifies to get only last stable build when last-successful is specified as which-build
  • fallback-to-last-successful (bool) – specifies to fallback to last successful build when upstream-build is specified as which-build
  • param (string) – specifies to use a build parameter to get the build when build-param is specified as which-build
  • upstream-project-name (str) – specifies the project name of downstream when downstream-build is specified as which-build
  • upstream-build-number (str) – specifies the number of the build to find its downstream build when downstream-build is specified as which-build
  • parameter-filters (string) – Filter matching jobs based on these parameters (optional)

Example:

builders:
  - copyartifact:
      project: foo
      filter: "*.tar.gz"
      target: /home/foo
      which-build: specific-build
      build-number: "123"
      optional: true
      flatten: true
      do-not-fingerprint: true
      parameter-filters: PUBLISH=true

Multijob Example:

builders:
  - copyartifact:
      project: foo
      filter: "*.json"
      target: /home/foo
      which-build: multijob-build
      optional: true
      flatten: true
      parameter-filters: PUBLISH=true
critical-block-end

Designate the end of a critical block. Must be used in conjuction with critical-block-start.

Must also add a build wrapper (exclusion), specifying the resources that control the critical block. Otherwise, this will have no effect.

Requires Jenkins Exclusion Plugin.

Example:

- wrapper:
    name: critical-block-exclusion
    wrappers:
      - exclusion:
          resources:
            - myresource1

- job:
    name: critical-block-example
    project-type: freestyle
    wrappers:
      - critical-block-exclusion
    builders:
      - critical-block-start
      - shell:
          #!/bin/bash -ex
          rollback-my-data-base
      - critical-block-end
critical-block-start

Designate the start of a critical block. Must be used in conjuction with critical-block-end.

Must also add a build wrapper (exclusion), specifying the resources that control the critical block. Otherwise, this will have no effect.

Requires Jenkins Exclusion Plugin.

Example:

- wrapper:
    name: critical-block-exclusion
    wrappers:
      - exclusion:
          resources:
            - myresource1

- job:
    name: critical-block-example
    project-type: freestyle
    wrappers:
      - critical-block-exclusion
    builders:
      - critical-block-start
      - shell:
          #!/bin/bash -ex
          rollback-my-data-base
      - critical-block-end
description-setter

This plugin sets the description for each build, based upon a RegEx test of the build log file.

Requires the Jenkins Description Setter Plugin.

Parameters:
  • regexp (str) – A RegEx which is used to scan the build log file (default ‘’)
  • description (str) – The description to set on the build (optional)

Example:

builders:
  - description-setter:
      regexp: ".*(<a href=.*a>)"
      description: "some description"
docker-build-publish

Requires the Jenkins :jenkins-wiki`Docker build publish Plugin <Docker+build+publish+Plugin>`.

Parameters:
  • repo-name (str) – Name of repository to push to.
  • repo-tag (str) – Tag for image. (default ‘’)
  • no-cache (bool) – If build should be cached. (default false)
  • no-force-pull (bool) – Don’t update the source image before building when it exists locally. (default false)
  • skip-build (bool) – Do not build the image. (default false)
  • skip-decorate (bool) – Do not decorate the build name. (default false)
  • skip-tag-latest (bool) – Do not tag this build as latest. (default false)
  • skip-push (bool) – Do not push. (default false)
  • file-path (str) – Project root of Dockerfile. (default ‘’)

Example:

builders:
    - docker-build-publish:
        repo-name: 'test'
        repo-tag: 'test-tag'
        no-cache: true
        no-force-pull: false
        skip-build: false
        skip-decorate: false
        skip-latest: false
        skip-tag: false
        file-path: '/tmp/'
doxygen

Builds doxygen HTML documentation. Requires the Jenkins Doxygen plugin.

Parameters:
  • doxyfile (str) – The doxyfile path (required)
  • install (str) – The doxygen installation to use (required)
  • ignore-failure (bool) – Keep executing build even on doxygen generation failure (default false)
  • unstable-warning (bool) – Mark the build as unstable if warnings are generated (default false)

Example:

builders:
  - doxygen:
      doxyfile: Doxyfile
      install: doxygen
      ignore-failure: true
      unstable-warning: true
dsl

Process Job DSL

Requires the Jenkins Job DSL plugin.

Parameters:
  • script-text (str) – dsl script which is Groovy code (Required if targets is not specified)
  • targets (str) – Newline separated list of DSL scripts, located in the Workspace. Can use wildcards like ‘jobs/*/*/*.groovy’ (Required if script-text is not specified)
  • ignore-existing (str) – Ignore previously generated jobs and views
  • removed-job-action (str) – Specifies what to do when a previously generated job is not referenced anymore, can be ‘IGNORE’, ‘DISABLE’, or ‘DELETE’ (default ‘IGNORE’)
  • removed-view-action (str) – Specifies what to do when a previously generated view is not referenced anymore, can be ‘IGNORE’ or ‘DELETE’. (default ‘IGNORE’)
  • lookup-strategy (str) – Determines how relative job names in DSL scripts are interpreted, can be ‘JENKINS_ROOT’ or ‘SEED_JOB’. (default ‘JENKINS_ROOT’)
  • additional-classpath (str) – Newline separated list of additional classpath entries for the Job DSL scripts. All entries must be relative to the workspace root, e.g. build/classes/main. (optional)

Example:

builders:
  - dsl:
      script-text: "job { name 'dsljob' }"
      ignore-existing: "true"
      removed-job-action: "DISABLE"
      removed-view-action: "DELETE"
      lookup-strategy: "SEED_JOB"
      additional-classpath: "*.jar"

builders:
  - dsl:
      target: "jobs/**/*.groovy"
      ignore-existing: "true"
      removed-job-action: "DISABLE"
      removed-view-action: "DELETE"
      lookup-strategy: "SEED_JOB"
      additional-classpath: "*.jar"
github-notifier

Set pending build status on Github commit. Requires the Jenkins Github Plugin.

Example:

builders:
  - github-notifier
gradle

Execute gradle tasks. Requires the Jenkins Gradle Plugin.

Parameters:
  • tasks (str) – List of tasks to execute
  • gradle-name (str) – Use a custom gradle name (optional)
  • wrapper (bool) – use gradle wrapper (default false)
  • executable (bool) – make gradlew executable (default false)
  • switches (list) – Switches for gradle, can have multiples
  • use-root-dir (bool) – Whether to run the gradle script from the top level directory or from a different location (default false)
  • root-build-script-dir (str) – If your workspace has the top-level build.gradle in somewhere other than the module root directory, specify the path (relative to the module root) here, such as ${workspace}/parent/ instead of just ${workspace}.

Example:

builders:
  - gradle:
      gradle-name: "gradle-1.2"
      wrapper: true
      executable: true
      use-root-dir: true
      root-build-script-dir: ${workspace}/tests
      switches:
        - "-g /foo/bar/.gradle"
        - "-PmavenUserName=foobar"
      tasks: |
             init
             build
             tests
grails

Execute a grails build step. Requires the Jenkins Grails Plugin.

Parameters:
  • use-wrapper (bool) – Use a grails wrapper (default false)
  • name (str) – Select a grails installation to use (optional)
  • force-upgrade (bool) – Run ‘grails upgrade –non-interactive’ first (default false)
  • non-interactive (bool) – append –non-interactive to all build targets (default false)
  • targets (str) – Specify target(s) to run separated by spaces
  • server-port (str) – Specify a value for the server.port system property (optional)
  • work-dir (str) – Specify a value for the grails.work.dir system property (optional)
  • project-dir (str) – Specify a value for the grails.project.work.dir system property (optional)
  • base-dir (str) – Specify a path to the root of the Grails project (optional)
  • properties (str) – Additional system properties to set (optional)
  • plain-output (bool) – append –plain-output to all build targets (default false)
  • stack-trace (bool) – append –stack-trace to all build targets (default false)
  • verbose (bool) – append –verbose to all build targets (default false)
  • refresh-dependencies (bool) – append –refresh-dependencies to all build targets (default false)

Example:

builders:
  - grails:
      use-wrapper: "true"
      name: "grails-2.2.2"
      force-upgrade: "true"
      non-interactive: "true"
      targets: "war ear"
      server-port: "8003"
      work-dir: "./grails-work"
      project-dir: "./project-work"
      base-dir: "./grails/project"
      properties: "program.name=foo"
      plain-output: "true"
      stack-trace: "true"
      verbose: "true"
      refresh-dependencies: "true"
groovy

Execute a groovy script or command. Requires the Jenkins Groovy Plugin.

Parameters:
  • file (str) – Groovy file to run. (Alternative: you can chose a command instead)
  • command (str) – Groovy command to run. (Alternative: you can chose a script file instead)
  • version (str) – Groovy version to use. (default ‘(Default)’)
  • parameters (str) – Parameters for the Groovy executable. (optional)
  • script-parameters (str) – These parameters will be passed to the script. (optional)
  • properties (str) – Instead of passing properties using the -D parameter you can define them here. (optional)
  • java-opts (str) – Direct access to JAVA_OPTS. Properties allows only -D properties, while sometimes also other properties like -XX need to be setup. It can be done here. This line is appended at the end of JAVA_OPTS string. (optional)
  • class-path (str) – Specify script classpath here. Each line is one class path item. (optional)

Examples:

builders:
  - groovy:
      file: "test.groovy"

builders:
  - groovy:
      command: "Some command"
      version: "Groovy 1.2"
      parameters: "parameters"
      script-parameters: "script parameters"
      properties: "properties"
      java-opts: "java opts"
http-request

This plugin sends a http request to an url with some parameters. Requires the Jenkins HTTP Request Plugin.

Parameters:
  • url (str) – Specify an URL to be requested (required)
  • mode (str) –

    The http mode of the request (default GET)

    mode values:
    • GET
    • POST
    • PUT
    • DELETE
    • HEAD
  • content-type (str) – Add ‘Content-type: foo’ HTTP request headers where foo is the http content-type the request is using. (default: NOT_SET)
  • accept-type (str) –

    Add ‘Accept: foo’ HTTP request headers where foo is the http content-type to accept (default: NOT_SET)

    content-type and accept-type values:
     
    • NOT_SET
    • TEXT_HTML
    • APPLICATION_JSON
    • APPLICATION_TAR
    • APPLICATION_ZIP
    • APPLICATION_OCTETSTREAM
  • output-file (str) – Name of the file in which to write response data (default: ‘’)
  • time-out (int) – Specify a timeout value in seconds (default: 0)
  • console-log (bool) – This allows you to turn off writing the response body to the log (default: False)
  • pass-build (bool) – Should build parameters be passed to the URL being called (default: False)
  • valid-response-codes (str) – Configure response code to mark an execution as success. You can configure simple code such as “200” or multiple codes separeted by comma(‘,’) e.g. “200,404,500” Interval of codes should be in format From:To e.g. “100:399”. The default (as if empty) is to fail to 4xx and 5xx. That means success from 100 to 399 “100:399” To ignore any response code use “100:599”. (default: ‘’)
  • valid-response-content (str) – If set response must contain this string to mark an execution as success (default: ‘’)
  • authentication-key (str) – Authentication that will be used before this request. Authentications are created in global configuration under a key name that is selected here.
  • custom-headers (list) –

    list of header parameters

    custom-header:
    • name (str) – Name of the header
    • value (str) – Value of the header

Example:

builders:
  - http-request:
      url: http://example.com/jenkinsTest

builders:
  - http-request:
      url: http://example.com/jenkinsTest
      mode: POST
      pass-build: true
      content-type: TEXT_HTML
      accept-type: TEXT_HTML
      output-file: response_file.txt
      authentication-key: authenticationkey
      console-log: true
      time-out: 10
      valid-response-codes: 100:399
      valid-response-content: foo
      custom-headers:
        - name: header
          value: value
        - name: header2
          value: value2
inject

Inject an environment for the job. Requires the Jenkins EnvInject Plugin.

Parameters:
  • properties-file (str) – the name of the property file (optional)
  • properties-content (str) – the properties content (optional)
  • script-file (str) – the name of a script file to run (optional)
  • script-content (str) – the script content (optional)

Example:

builders:
  - inject:
      properties-file: example.prop
      properties-content: EXAMPLE=foo-bar
      script-file: script.sh
      script-content: script content
managed-script

This step allows to reference and execute a centrally managed script within your build. Requires the Jenkins Managed Script Plugin.

Parameters:
  • script-id (str) – Id of script to execute (required)
  • type (str) –

    Type of managed file (default script)

    type values:
    • batch: Execute managed windows batch
    • script: Execute managed script
  • args (list) – Arguments to be passed to referenced script

Example:

builders:
  - managed-script:
      script-id: org.jenkinsci.plugins.managedscripts.ScriptConfig1401886156431
      type: script
      args:
        - arg1
        - arg2

builders:
  - managed-script:
      script-id: org.jenkinsci.plugins.managedscripts.WinBatchConfig1402391729132
      type: batch
      args:
        - arg1
        - arg2
maven-builder

Execute Maven3 builder

Allows your build jobs to deploy artifacts automatically to Artifactory.

Requires the Jenkins Artifactory Plugin.

Parameters:
  • name (str) – Name of maven installation from the configuration
  • pom (str) – Location of pom.xml (default ‘pom.xml’)
  • goals (str) – Goals to execute
  • maven-opts (str) – Additional options for maven (optional)

Example:

builders:
      - maven-builder:
          name: mvn3
          pom: modules/pom.xml
          goals: clean install
maven-target

Execute top-level Maven targets.

Requires the Jenkins Config File Provider Plugin for the Config File Provider “settings” and “global-settings” config.

Parameters:
  • goals (str) – Goals to execute
  • properties (str) – Properties for maven, can have multiples
  • pom (str) – Location of pom.xml (default ‘pom.xml’)
  • private-repository (bool) – Use private maven repository for this job (default false)
  • maven-version (str) – Installation of maven which should be used (optional)
  • java-opts (str) – java options for maven, can have multiples, must be in quotes (optional)
  • settings (str) – Path to use as user settings.xml It is possible to provide a ConfigFileProvider settings file, such as see CFP Example below. (optional)
  • global-settings (str) – Path to use as global settings.xml It is possible to provide a ConfigFileProvider settings file, such as see CFP Example below. (optional)

Example:

builders:
        - maven-target:
            maven-version: Maven3
            pom: parent/pom.xml
            goals: clean
            private-repository: true
            properties:
              - foo=bar
              - bar=foo
            java-opts:
              - "-Xms512m -Xmx1024m"
              - "-XX:PermSize=128m -XX:MaxPermSize=256m"
            settings: mvn/settings.xml              
            global-settings: mvn/globalsettings.xml

CFP Example:

postbuilders:
      - maven-target:
          maven-version: mvn30
          goals: clean verify
          settings: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012
          global-settings: org.jenkinsci.plugins.configfiles.maven.GlobalMavenSettingsConfig0123456789012
msbuild

Build .NET project using msbuild. Requires the Jenkins MSBuild Plugin.

Parameters:
  • msbuild-version (str) – which msbuild configured in Jenkins to use (optional)
  • solution-file (str) – location of the solution file to build
  • extra-parameters (str) – extra parameters to pass to msbuild (optional)
  • pass-build-variables (bool) – should build variables be passed to msbuild (default true)
  • continue-on-build-failure (bool) – should the build continue if msbuild returns an error (default false)

Example:

builders:
  - msbuild:
      solution-file: "MySolution.sln"
      msbuild-version: "msbuild-4.0"
      extra-parameters: "/maxcpucount:4"
      pass-build-variables: False
      continue-on-build-failure: True
multijob

Define a multijob phase. Requires the Jenkins Multijob Plugin.

This builder may only be used in jenkins_jobs.modules.project_multijob.MultiJob projects.

Parameters:
  • name (str) – MultiJob phase name
  • condition (str) – when to trigger the other job. Can be: ‘SUCCESSFUL’, ‘UNSTABLE’, ‘COMPLETED’, ‘FAILURE’, ‘ALWAYS’. (default ‘SUCCESSFUL’)
  • projects (list) –

    list of projects to include in the MultiJob phase

    Project:
    • name (str) – Project name
    • current-parameters (bool) – Pass current build parameters to the other job (default false)
    • node-label-name (str) – Define a list of nodes on which the job should be allowed to be executed on. Requires NodeLabel Parameter Plugin (optional)
    • node-label (str) – Define a label of ‘Restrict where this project can be run’ on the fly. Requires NodeLabel Parameter Plugin (optional)
    • node-parameters (bool) – Use the same Node for the triggered builds that was used for this build. (optional)
    • git-revision (bool) – Pass current git-revision to the other job (default false)
    • property-file (str) – Pass properties from file to the other job (optional)
    • predefined-parameters (str) – Pass predefined parameters to the other job (optional)
    • abort-all-job (bool) – Kill allsubs job and the phase job, if this subjob is killed (default false)
    • enable-condition (str) – Condition to run the job in groovy script format (optional)
    • kill-phase-on (str) – Stop the phase execution on specific job status. Can be ‘FAILURE’, ‘UNSTABLE’, ‘NEVER’. (optional)
    • restrict-matrix-project (str) – Filter that restricts the subset of the combinations that the downstream project will run (optional)

Example:

builders:
  - multijob:
      name: PhaseOne
      condition: SUCCESSFUL
      projects:
        - name: PhaseOneJobA
          current-parameters: true
          node-label-name: "vm_name"
          node-label: "agent-${BUILD_NUMBER}"
          git-revision: true
          abort-all-job: true
        - name: PhaseOneJobB
          current-parameters: true
          property-file: build.props
  - multijob:
      name: PhaseTwo
      condition: UNSTABLE
      projects:
        - name: PhaseTwoJobA
          current-parameters: true
          predefined-parameters: foo=bar
          node-parameters: true
        - name: PhaseTwoJobB
          current-parameters: false
          kill-phase-on: UNSTABLE
          enable-condition: "${BUILDNUMBER} % 2 == 1"
          restrict-matrix-project: 'JVM_VARIANT == "server"'
  - multijob:
      name: PhaseThree
      condition: ALWAYS
      projects:
        - name: PhaseThreeJobA
          current-parameters: true
          kill-phase-on: FAILURE
openshift-build-verify

Performs the equivalent of an ‘oc get builds` command invocation for the provided buildConfig key provided; once the list of builds are obtained, the state of the latest build is inspected for up to a minute to see if it has completed successfully. Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • bld-cfg (str) – The value here should be whatever was the output form oc project when you created the BuildConfig you want to run a Build on (default ‘frontend’)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-build-verify:
      api-url: https://openshift.example.local.url/
      bld-cfg: front
      namespace: test-build
      auth-token: ose-key-buildv1
      verbose: true

Minimal Example:

builders:
  - openshift-build-verify
openshift-builder

Perform builds in OpenShift for the job. Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • bld-cfg (str) – The value here should be whatever was the output form oc project when you created the BuildConfig you want to run a Build on (default ‘frontend’)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • commit-ID (str) – The value here is what you supply with the –commit option when invoking the OpenShift oc start-build command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)
  • build-name (str) – TThe value here is what you supply with the –from-build option when invoking the OpenShift oc start-build command. (optional)
  • show-build-logs (str) – Indicates whether the build logs get dumped to the console of the Jenkins build. (default ‘false’)

Full Example:

builders:
  - openshift-builder:
      api-url: https://openshift.example.local.url/
      bld-cfg: front
      namespace: test9
      auth-token: ose-builder1
      commit-ID: ae489f7d
      verbose: true
      build-name: ose-test-build
      show-build-logs: true

Minimal Example:

builders:
  - openshift-builder
openshift-creator

Performs the equivalent of an oc create command invocation; this build step takes in the provided JSON or YAML text, and if it conforms to OpenShift schema, creates whichever OpenShift resources are specified. Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • jsonyaml (str) – The JSON or YAML formatted text that conforms to the schema for defining the various OpenShift resources. (optional)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-creator:
      api-url: https://openshift.example.local.url/
      jsonyaml: 'front: back'
      namespace: test6
      auth-token: ose-key-creator1
      verbose: true

Minimal Example:

builders:
  - openshift-creator
openshift-dep-verify

Determines whether the expected set of DeploymentConfig’s, ReplicationController’s, and active replicas are present based on prior use of the scaler (2) and deployer (3) steps Requires the Jenkins OpenShift Pipeline Plugin._

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default https://openshift.default.svc.cluster.local)
  • dep-cfg (str) – The value here should be whatever was the output form oc project when you created the BuildConfig you want to run a Build on (default frontend)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default test)
  • replica-count (str) – The value here should be whatever the number of pods you want started for the deployment. (default 0)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-dep-verify:
      api-url: https://openshift.example.local.url/
      dep-cfg: front
      namespace: test6
      replica-count: 4
      auth-token: ose-key-dep-verify1
      verbose: true

Minimal Example:

builders:
  - openshift-dep-verify
openshift-deployer

Start a deployment in OpenShift for the job. Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • dep-cfg (str) – The value here should be whatever was the output form oc project when you created the BuildConfig you want to run a Build on (default ‘frontend’)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-deployer:
      api-url: https://openshift.example.local.url/
      dep-cfg: front
      namespace: test3
      auth-token: ose-key-deployer1
      verbose: true

Minimal Example:

builders:
  - openshift-deployer
openshift-img-tagger

Performs the equivalent of an oc tag command invocation in order to manipulate tags for images in OpenShift ImageStream’s Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • test-tag (str) – The equivalent to the name supplied to a oc get service command line invocation. (default ‘origin-nodejs-sample:latest’)
  • prod-tag (str) – The equivalent to the name supplied to a oc get service command line invocation. (default ‘origin-nodejs-sample:prod’)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-img-tagger:
      api-url: https://openshift.example.local.url/
      test-tag: origin-nodejs-sample:test
      prod-tag: origin-nodejs-sample:production
      namespace: test5
      auth-token: ose-key-img1
      verbose: true

Minimal Example:

builders:
  - openshift-img-tagger
openshift-scaler

Scale deployments in OpenShift for the job. Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • dep-cfg (str) – The value here should be whatever was the output form oc project when you created the BuildConfig you want to run a Build on (default ‘frontend’)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • replica-count (int) – The value here should be whatever the number of pods you want started for the deployment. (default 0)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-scaler:
      api-url: https://openshift.example.local.url/
      dep-cfg: front
      namespace: test2
      replica-count: 4
      auth-token: ose-key-scaler1
      verbose: true

Minimal Example:

builders:
  - openshift-scaler
openshift-svc-verify

Verify a service is up in OpenShift for the job. Requires the Jenkins OpenShift Pipeline Plugin.

Parameters:
  • api-url (str) – this would be the value you specify if you leverage the –server option on the OpenShift oc command. (default ‘https://openshift.default.svc.cluster.local’)
  • svc-name (str) – The equivalent to the name supplied to a oc get service command line invocation. (default ‘frontend’)
  • namespace (str) – If you run oc get bc for the project listed in “namespace”, that is the value you want to put here. (default ‘test’)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (optional)
  • verbose (str) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default ‘false’)

Full Example:

builders:
  - openshift-svc-verify:
      api-url: https://openshift.example.local.url/
      svc-name: front
      namespace: test4
      auth-token: ose-key-svc-verify1
      verbose: true

Minimal Example:

builders:
  - openshift-svc-verify
powershell

Execute a powershell command. Requires the Powershell Plugin.

Parameter:the powershell command to execute

Example:

builders:
  - powershell: "foo/foo.ps1"
publish-over-ssh

Send files or execute commands over SSH. Requires the Jenkins Publish over SSH Plugin.

Parameters:
  • site (str) – name of the ssh site
  • target (str) – destination directory
  • target-is-date-format (bool) – whether target is a date format. If true, raw text should be quoted (default false)
  • clean-remote (bool) – should the remote directory be deleted before transferring files (default false)
  • source (str) – source path specifier
  • command (str) – a command to execute on the remote server (optional)
  • timeout (int) – timeout in milliseconds for the Exec command (optional)
  • use-pty (bool) – run the exec command in pseudo TTY (default false)
  • excludes (str) – excluded file pattern (optional)
  • remove-prefix (str) – prefix to remove from uploaded file paths (optional)
  • fail-on-error (bool) – fail the build if an error occurs (default false)

Example:

builders:
    - publish-over-ssh:
        site: 'server.example.com'
        target: 'dest/dir'
        source: 'base/source/dir/**'
        timeout: 1800000
python

Execute a python command. Requires the Jenkins Python plugin.

Parameters:parameter (str) – the python command to execute

Example:

builders:
  - python: 'import foobar'
runscope

Execute a Runscope test. Requires the Jenkins Runscope Plugin.

Parameters:
  • test-trigger-url (str) – Trigger URL for test. (required)
  • access-token (str) – OAuth Personal Access token. (required)
  • timeout (int) – Timeout for test duration in seconds. (default 60)

Example:

builders:
  - runscope:
      test-trigger-url: "https://api.runscope.com/radar/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/trigger"
      access-token: "123456"
      timeout: 60
sbt

Execute a sbt build step. Requires the Jenkins Sbt Plugin.

Parameters:
  • name (str) – Select a sbt installation to use. If no name is provided, the first in the list of defined SBT builders will be used. (default to first in list)
  • jvm-flags (str) – Parameters to pass to the JVM (default ‘’)
  • actions (str) – Select the sbt tasks to execute (default ‘’)
  • sbt-flags (str) – Add flags to SBT launcher (default ‘-Dsbt.log.noformat=true’)
  • subdir-path (str) – Path relative to workspace to run sbt in (default ‘’)

Example:

builders:
  - sbt:
      name: "default"
      actions: "clean package"
      jvm-flags: "-Xmx8G"
shell

Execute a shell command.

Parameters:parameter (str) – the shell command to execute

Example:

builders:
  - shell: "make test"
shining-panda

Execute a command inside various python environments. Requires the Jenkins ShiningPanda plugin.

Parameters:build-environment (str) –

Building environment to set up (required).

build-environment values:
 
  • python: Use a python installation configured in Jenkins.
  • custom: Use a manually installed python.
  • virtualenv: Create a virtualenv

For the python environment

Parameters:python-version (str) – Name of the python installation to use. Must match one of the configured installations on server configuration (default ‘System-CPython-2.7’)

For the custom environment:

Parameters:home (str) – path to the home folder of the custom installation (required)

For the virtualenv environment:

Parameters:
  • python-version (str) – Name of the python installation to use. Must match one of the configured installations on server configuration (default ‘System-CPython-2.7’)
  • name (str) – Name of this virtualenv. Two virtualenv builders with the same name will use the same virtualenv installation (optional)
  • clear (bool) – If true, delete and recreate virtualenv on each build. (default false)
  • use-distribute (bool) – if true use distribute, if false use setuptools. (default true)
  • system-site-packages (bool) – if true, give access to the global site-packages directory to the virtualenv. (default false)

Common to all environments:

Parameters:
  • nature (str) –

    Nature of the command field. (default shell)

    nature values:
    • shell: execute the Command contents with default shell
    • xshell: like shell but performs platform conversion first
    • python: execute the Command contents with the Python executable
  • command (str) – The command to execute
  • ignore-exit-code (bool) – mark the build as failure if any of the commands exits with a non-zero exit code. (default false)

Examples:

builders:
    - shining-panda:
        build-environment: python
        python-version: System-CPython-2.7
        nature: python
        command: setup.py build
        ignore-exit-code: false

builders:
    - shining-panda:
        build-environment: custom
        home: /usr/local/lib/custom-python-27
        nature: xshell
        command: |
            cd $HOME/build
            python setup.py build
        ignore-exit-code: true

builders:
    - shining-panda:
        build-environment: virtualenv
        python-version: System-CPython-2.7
        nature: shell
        command: python setup.py build
        name: virtvenv1
        clear: true
        use-distribute: true
        system-site-packages: true
        ignore-exit-code: true
sonar

Invoke standalone Sonar analysis. Requires the Jenkins Sonar Plugin.

Parameters:
  • sonar-name (str) – Name of the Sonar installation.
  • task (str) – Task to run. (optional)
  • project (str) – Path to Sonar project properties file. (optional)
  • properties (str) – Sonar configuration properties. (optional)
  • java-opts (str) – Java options for Sonnar Runner. (optional)
  • jdk (str) – JDK to use (inherited from the job if omitted). (optional)

Example:

builders:
  - sonar:
      sonar-name: Sonar
      task: views
      project: sonar-project.properties
      properties: sonar.views.list=myview1,myview2
      java-opts: -Xmx512m
sonatype-clm

Requires the Jenkins Sonatype CLM Plugin.

Parameters:
  • value (str) – Select CLM application from a list of available CLM applications or specify CLM Application ID (default: list)
  • application-name (str) – Determines the policy elements to associate with this build. (required)
  • username (str) – Username on the Sonatype CLM server. Leave empty to use the username configured at global level. (default: ‘’)
  • password (str) – Password on the Sonatype CLM server. Leave empty to use the password configured at global level. (default: ‘’)
  • fail-on-clm-server-failure (bool) – Controls the build outcome if there is a failure in communicating with the CLM server. (default: False)
  • stage (str) – Controls the stage the policy evaluation will be run against on the CLM server. Valid stages: build, stage-release, release, operate. (default: ‘build’)
  • scan-targets (str) – Pattern of files to include for scanning. (default: ‘’)
  • module-excludes (str) – Pattern of files to exclude. (default: ‘’)
  • advanced-options (str) – Options to be set on a case-by-case basis as advised by Sonatype Support. (default: ‘’)

Minimal Example:

builders:
    - sonatype-clm:
        application-name: jenkins-job-builder

Full Example:

builders:
    - sonatype-clm:
        value: manual
        application-name: jenkins-job-builder
        fail-on-clm-server-failure: true
        stage: build
        scan-targets: '**/*.jar'
        module-excludes: '**/my-module/target/**'
        advanced-options: 'test'
        username: bar
        password: 06XQY39LHGACt3r3kzSULg==
ssh-builder

Executes command on remote host Requires the Jenkins SSH plugin.

Parameters:
  • ssh-user-ip (str) – user@ip:ssh_port of machine that was defined in jenkins according to SSH plugin instructions
  • command (str) – command to run on remote server

Example:

builders:
  - ssh-builder:
      ssh-user-ip: foo@bar:22
      command: echo foo
system-groovy

Execute a system groovy script or command. Requires the Jenkins Groovy Plugin.

Parameters:
  • file (str) – Groovy file to run. (Alternative: you can chose a command instead)
  • command (str) – Groovy command to run. (Alternative: you can chose a script file instead)
  • bindings (str) – Define variable bindings (in the properties file format). Specified variables can be addressed from the script. (optional)
  • class-path (str) – Specify script classpath here. Each line is one class path item. (optional)

Examples:

builders:
  - system-groovy:
      file: "test.groovy"

builders:
  - system-groovy:
      command: "Some command"
      bindings: "Some bindings"
      class-path: "Some classpath"
tox

Use tox to build a multi-configuration project. Requires the Jenkins ShiningPanda plugin.

Parameters:
  • ini (str) – The TOX configuration file path (default: tox.ini)
  • recreate (bool) – If true, create a new environment each time (default: false)
  • toxenv-pattern (str) – The pattern used to build the TOXENV environment variable. (optional)

Example:

builders:
  - tox:
      recreate: True
trigger-builds

Trigger builds of other jobs. Requires the Jenkins Parameterized Trigger Plugin.

Parameters:
  • project (list) – the Jenkins project to trigger
  • predefined-parameters (str) – key/value pairs to be passed to the job (optional)
  • bool-parameters (list) –
    Bool:
    • name (str) – Parameter name
    • value (bool) – Value to set (default false)
  • property-file (str) – Pass properties from file to the other job (optional)
  • property-file-fail-on-missing (bool) – Don’t trigger if any files are missing (default true)
  • current-parameters (bool) – Whether to include the parameters passed to the current build to the triggered job.
  • node-label-name (str) – Define a name for the NodeLabel parameter to be set. Used in conjunction with node-label. Requires NodeLabel Parameter Plugin (optional)
  • node-label (str) – Label of the nodes where build should be triggered. Used in conjunction with node-label-name. Requires NodeLabel Parameter Plugin (optional)
  • svn-revision (bool) – Whether to pass the svn revision to the triggered job (optional)
  • git-revision (dict) –

    Passes git revision to the triggered job (optional).

    • combine-queued-commits (bool): Whether to combine queued git hashes or not (default false)
  • block (bool) – whether to wait for the triggered jobs to finish or not (default false)
  • block-thresholds (dict) –

    Fail builds and/or mark as failed or unstable based on thresholds. Only apply if block parameter is true (optional)

    block-thresholds:
     
    • build-step-failure-threshold (str) - build step failure threshold, valid values are ‘never’, ‘SUCCESS’, ‘UNSTABLE’, or ‘FAILURE’. (default ‘FAILURE’)
    • unstable-threshold (str) - unstable threshold, valid values are ‘never’, ‘SUCCESS’, ‘UNSTABLE’, or ‘FAILURE’. (default ‘UNSTABLE’)
    • failure-threshold (str) - overall failure threshold, valid values are ‘never’, ‘SUCCESS’, ‘UNSTABLE’, or ‘FAILURE’. (default ‘FAILURE’)
  • same-node (bool) – Use the same node for the triggered builds that was used for this build (optional)
  • parameter-factories (list) –

    list of parameter factories

    Factory:
    • factory (str) filebuild – For every property file, invoke one build
    • file-pattern (str) – File wildcard pattern
    • no-files-found-action (str) – Action to perform when no files found. Valid values ‘FAIL’, ‘SKIP’, or ‘NOPARMS’. (default ‘SKIP’)
    Factory:
    • factory (str) binaryfile – For every matching file, invoke one build
    • file-pattern (str) – Artifact ID of the artifact
    • no-files-found-action (str) – Action to perform when no files found. Valid values ‘FAIL’, ‘SKIP’, or ‘NOPARMS’. (default ‘SKIP’)
    Factory:
    • factory (str) counterbuild – Invoke i=0...N builds
    • from (int) – Artifact ID of the artifact
    • to (int) – Version of the artifact
    • step (int) – Classifier of the artifact
    • parameters (str) – KEY=value pairs, one per line (default ‘’)
    • validation-fail (str) – Action to perform when stepping validation fails. Valid values ‘FAIL’, ‘SKIP’, or ‘NOPARMS’. (default ‘FAIL’)
    Factory:
    • factory (str) allnodesforlabel – Trigger a build on all nodes having specific label. Requires NodeLabel Parameter Plugin (optional)
    • name (str) – Name of the parameter to set (optional)
    • node-label (str) – Label of the nodes where build should be triggered
    • ignore-offline-nodes (bool) – Don’t trigger build on offline nodes (default true)

Examples:

Basic usage with yaml list of projects.

builders:
  - trigger-builds:
    - project:
        - "foo"
        - "bar"
        - "baz"
      current-parameters: true

Basic usage with passing svn revision through.

builders:
  - trigger-builds:
    - project: "build_started"
      predefined-parameters:
        FOO="bar"
      current-parameters: true
      svn-revision: true
      block: true

Basic usage with passing git revision through.

builders:
  - trigger-builds:
    - project: "build_started"
      predefined-parameters:
        FOO="bar"
      current-parameters: true
      node-label-name: NODE
      node-label: testnodes
      git-revision: true
      block: true

Example with all supported parameter factories.

builders:
  - trigger-builds:
    - project: "build_started"
      predefined-parameters:
        FOO="bar"
      current-parameters: true
      svn-revision: true
      parameter-factories:
        - factory: filebuild
          file-pattern: propfile*.txt
        - factory: binaryfile
          parameter-name: filename
          file-pattern: otherpropfile*.txt
        - factory: counterbuild
          from: 0
          to: 5
          step: 1
        - factory: allnodesforlabel
          name: parametername
          node-label: labelname
          ignore-offline-nodes: false
      block: true
trigger-remote

Trigger build of job on remote Jenkins instance.

Parameterized Remote Trigger Plugin

Please note that this plugin requires system configuration on the Jenkins Master that is unavailable from individual job views; specifically, one must add remote jenkins servers whose ‘Display Name’ field are what make up valid fields on the remote-jenkins-name attribute below.

Parameters:
  • remote-jenkins-name (str) – the remote Jenkins server (required)
  • job (str) – the Jenkins project to trigger on the remote Jenkins server (required)
  • should-not-fail-build (bool) – if true, remote job failure will not lead current job to fail (default false)
  • prevent-remote-build-queue (bool) – if true, wait to trigger remote builds until no other builds (default false)
  • block (bool) – whether to wait for the trigger jobs to finish or not (default true)
  • poll-interval (str) – polling interval in seconds for checking statues of triggered remote job, only necessary if current job is configured to block (default 10)
  • connection-retry-limit (str) – number of connection attempts to remote Jenkins server before giving up. (default 5)
  • predefined-parameters (str) – predefined parameters to send to the remote job when triggering it (optional)
  • property-file (str) – file in workspace of current job containing additional parameters to be set on remote job (optional)

Example:

builders:
  - trigger-remote:
      remote-jenkins-name: "http://example.jenkinsmaster.lan"
      token: "BLAH"
      job: "build-things"
      should-fail-build: True
      prevent-remote-build-queue: True
      poll-interval: 5
      connection-retry-limit: 5
      block: true
      property-file: '.props'
      predefined-parameters: |
        FOO="bar"
        herp="derp"