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.
Macro: | builder |
---|---|
Entry Point: | jenkins_jobs.builders |
Example:
job:
name: test_job
builders:
- shell: "make test"
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: |
|
---|
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"
Allows one to resolve artifacts from a maven repository like nexus (without having maven installed) Requires the Jenkins Repository Connector Plugin.
Parameters: |
|
---|
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"
Execute a batch command.
Parameter: | the batch command to execute |
---|
Example:
builders:
- batch: "foo/foo.bat"
Execute a beaker build step. Requires the Jenkins Beaker Builder Plugin.
Parameters: |
|
---|
Example:
builders:
- beaker:
path: 'test.xml'
download-logs: true
builders:
- beaker:
content: |
<job group='product-QA'>
<whiteboard>
Apache 2.2 test
</whiteboard>
</job>
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 the assembly version. Requires the Jenkins Change Assembly Version.
Parameters: |
|
---|
Example:
builders:
- change-assembly-version:
version: "1.2.3"
assembly-file: "AFile"
Create cloudformation stacks before running a build and optionally delete them at the end. Requires the Jenkins AWS Cloudformation Plugin.
Parameters: |
|
---|
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
Execute a CMake target. Requires the Hudson cmakebuilder Plugin.
Parameters: |
|
---|
Example:
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
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 | 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
|
||||||||||||||||||||||||||||||
build-cause | Run if the current build has a specific cause
|
||||||||||||||||||||||||||||||
day-of-week | Only run on specific days of the week.
|
||||||||||||||||||||||||||||||
execution-node | Run only on selected nodes.
|
||||||||||||||||||||||||||||||
strings-match | Run the step if two strings match
|
||||||||||||||||||||||||||||||
current-status | Run the build step if the current build status is within the configured range
|
||||||||||||||||||||||||||||||
shell | Run the step if the shell command succeed
|
||||||||||||||||||||||||||||||
windows-shell | Similar to shell, except that commands will be executed by cmd, under Windows
|
||||||||||||||||||||||||||||||
file-exists | Run the step if a file exists
|
||||||||||||||||||||||||||||||
files-match | Run if one or more files match the selectors.
|
||||||||||||||||||||||||||||||
num-comp | Run if the numerical comparison is true.
|
||||||||||||||||||||||||||||||
regex-match | Run if the Expression matches the Label.
|
||||||||||||||||||||||||||||||
time | Only run during a certain period of the day.
|
||||||||||||||||||||||||||||||
not | Run the step if the inverse of the condition-operand is true
|
||||||||||||||||||||||||||||||
and | Run the step if logical and of all conditional-operands is true
|
||||||||||||||||||||||||||||||
or | Run the step if logical or of all conditional-operands is true
|
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"
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
|
---|
Example:
builders:
- config-file-provider:
files:
- file-id: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012
target: target
variable: variable
Copy artifact from another project. Requires the Copy Artifact plugin.
Parameters: |
|
---|
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
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
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
Process Job DSL
Requires the Jenkins Job DSL plugin.
Parameters: |
|
---|
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"
Set pending build status on Github commit. Requires the Jenkins Github Plugin.
Example:
builders:
- github-notifier
Execute gradle tasks. Requires the Jenkins Gradle Plugin.
Parameters: |
|
---|
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
Execute a grails build step. Requires the Jenkins Grails Plugin.
Parameters: |
|
---|
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"
Execute a groovy script or command. Requires the Jenkins Groovy Plugin.
Parameters: |
|
---|
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"
Inject an environment for the job. Requires the Jenkins EnvInject Plugin.
Parameters: |
|
---|
Example:
builders:
- inject:
properties-file: example.prop
properties-content: EXAMPLE=foo-bar
script-file: script.sh
script-content: script content
This step allows to reference and execute a centrally managed script within your build. Requires the Jenkins Managed Script Plugin.
Parameters: |
|
---|
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
Execute Maven3 builder
Parameters: |
|
---|
Requires the Jenkins Artifactory Plugin allows your build jobs to deploy artifacts automatically to Artifactory.
Example:
builders:
- maven-builder:
name: mvn3
pom: modules/pom.xml
goals: clean install
Execute top-level Maven targets
Parameters: |
|
---|
Requires the Jenkins Config File Provider Plugin for the Config File Provider “settings” and “global-settings” config.
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
Build .NET project using msbuild. Requires the Jenkins MSBuild Plugin.
Parameters: |
|
---|
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
Define a multijob phase. Requires the Jenkins Multijob Plugin.
This builder may only be used in jenkins_jobs.modules.project_multijob.MultiJob projects.
Parameters: |
|
---|
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
- name: PhaseOneJobB
current-parameters: true
property-file: build.props
- multijob:
name: PhaseTwo
condition: UNSTABLE
projects:
- name: PhaseTwoJobA
current-parameters: true
predefined-parameters: foo=bar
- name: PhaseTwoJobB
current-parameters: false
kill-phase-on: UNSTABLE
enable-condition: "${BUILDNUMBER} % 2 == 1"
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 OpenShift3 Plugin
Parameters: |
|
---|
Full Example:
builders:
- openshift-build-verify:
api-url: https://openshift.example.local.url/
bld-cfg: front
namespace: test-build
auth-token: ose-key-buildv1
Minimal Example:
builders:
- openshift-build-verify
Perform builds in OpenShift for the job. Requires the Jenkins OpenShift3 Plugin
Parameters: |
|
---|
Full Example:
builders:
- openshift-builder:
api-url: https://openshift.example.local.url/
bld-cfg: front
namespace: test9
auth-token: ose-builder1
follow-log: false
Minimal Example:
builders:
- openshift-builder
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 OpenShift3 Plugin
Parameters: |
|
---|
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
Minimal Example:
builders:
- openshift-dep-verify
Start a deployment in OpenShift for the job. Requires the Jenkins OpenShift3 Plugin
Parameters: |
|
---|
Full Example:
builders:
- openshift-deployer:
api-url: https://openshift.example.local.url/
dep-cfg: front
namespace: test3
auth-token: ose-key-deployer1
Minimal Example:
builders:
- openshift-deployer
Performs the equivalent of an oc tag command invocation in order to manipulate tags for images in OpenShift ImageStream’s Requires the Jenkins OpenShift3 Plugin
Parameters: |
|
---|
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
Minimal Example:
builders:
- openshift-img-tagger
Scale deployments in OpenShift for the job. Requires the Jenkins OpenShift3 Plugin
Parameters: |
|
---|
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
Minimal Example:
builders:
- openshift-scaler
Verify a service is up in OpenShift for the job. Requires the Jenkins OpenShift3 Plugin
Parameters: |
|
---|
Full Example:
builders:
- openshift-svc-verify:
api-url: https://openshift.example.local.url/
svc-name: front
namespace: test4
auth-token: ose-key-svc-verify1
Minimal Example:
builders:
- openshift-svc-verify
Execute a powershell command. Requires the Powershell Plugin.
Parameter: | the powershell command to execute |
---|
Example:
builders:
- powershell: "foo/foo.ps1"
Execute a python command. Requires the Jenkins Python plugin.
Parameters: | parameter (str) – the python command to execute |
---|
Example:
builders:
- python: 'import foobar'
Execute a Runscope test. Requires the Jenkins Runscope Plugin.
Parameters: |
|
---|
Example:
builders:
- runscope:
test-trigger-url: "https://api.runscope.com/radar/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/trigger"
access-token: "123456"
timeout: 60
Execute a sbt build step. Requires the Jenkins Sbt Plugin.
Parameters: |
|
---|
Example:
builders:
- sbt:
name: "default"
actions: "clean package"
jvm-flags: "-Xmx8G"
Execute a shell command.
Parameters: | parameter (str) – the shell command to execute |
---|
Example:
builders:
- shell: "make test"
Execute a command inside various python environments. Requires the Jenkins ShiningPanda plugin.
Parameters: | build-environment (str) – Building environment to set up (required).
|
---|
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: |
|
---|
Common to all environments:
Parameters: |
|
---|
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
Invoke standalone Sonar analysis. Requires the Jenkins Sonar Plugin.
Parameters: |
|
---|
Example:
builders:
- sonar:
sonar-name: Sonar
task: views
project: sonar-project.properties
properties: sonar.views.list=myview1,myview2
java-opts: -Xmx512m
Requires the Jenkins Sonatype CLM Plugin.
Parameters: |
|
---|
Example:
builders:
- sonatype-clm:
application-name: jenkins-job-builder
fail-on-clm-server-failure: true
stage: release
scan-targets: '**/*.jar'
module-excludes: '**/my-module/target/**'
advanced-options: 'test'
Executes command on remote host Requires the Jenkins SSH plugin.
Parameters: |
|
---|
Example:
builders:
- ssh-builder:
ssh-user-ip: foo@bar:22
command: echo foo
Execute a system groovy script or command. Requires the Jenkins Groovy Plugin.
Parameters: |
|
---|
Examples:
builders:
- system-groovy:
file: "test.groovy"
builders:
- system-groovy:
command: "Some command"
bindings: "Some bindings"
class-path: "Some classpath"
Trigger builds of other jobs. Requires the Jenkins Parameterized Trigger Plugin.
Parameters: |
|
---|
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 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: |
|
---|
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"