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"
-
class
builders.Builders(registry)¶ -
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.
- Parameters
parser (YAMLParser) – the global YAML Parser
xml_parent (Element) – the parent XML element
data (dict) – the YAML data structure
-
-
ansible-playbook¶ This plugin allows you to execute Ansible tasks as a job build step.
Requires the Jenkins Ansible Plugin.
- Parameters
playbook (str) – Path to the ansible playbook file. The path can be absolute or relative to the job workspace. (required)
inventory-type (str) –
The inventory file form (default path)
- inventory-type values
path
content
do-not-specify
inventory (dict) –
Inventory data, depends on inventory-type
- inventory-type == path
path (str) – Path to inventory file.
- inventory-type == content
content (str) – Content of inventory file.
dynamic (bool) – Dynamic inventory is used (default false)
hosts (str) – Further limit selected hosts to an additional pattern (default ‘’)
tags-to-run (str) – Only run plays and tasks tagged with these values (default ‘’)
tags-to-skip (str) – Only run plays and tasks whose tags do not match these values (default ‘’)
task-to-start-at (str) – Start the playbook at the task matching this name (default ‘’)
workers (int) – Specify number of parallel processes to use (default 5)
credentials-id (str) – The ID of credentials for the SSH connections. Only private key authentication is supported (default ‘’)
vault-credentials-id (str) – The ID of credentials for the vault decryption (default ‘’)
sudo (bool) – Run operations with sudo. It works only when the remote user is sudoer with nopasswd option (default false)
sudo-user (str) – Desired sudo user. “root” is used when this field is empty. (default ‘’)
unbuffered-output (bool) – Skip standard output buffering for the ansible process. The ansible output is directly rendered into the Jenkins console. This option can be useful for long running operations. (default true)
colorized-output (bool) – Check this box to allow ansible to render ANSI color codes in the Jenkins console. (default false)
disable-host-key-checking (bool) – Check this box to disable the validation of the hosts SSH server keys. (>= 1.0) (default false)
additional-parameters (str) – Any additional parameters to pass to the ansible command. (default ‘’)
variables (list) –
List of extra variables to be passed to ansible. (optional)
- variable item
name (str) – Name of variable (required)
value (str) – Desired value (default ‘’)
hidden (bool) – Hide variable in build log (default false)
Outdated Options for versions >= 1.0 of plugin:
- Parameters
host-key-checking (bool) – Outdated, replaced with disable-host-key-checking. Check this box to enforce the validation of the hosts SSH server keys. (< 1.0) (default true)
Example:
--- builders: - ansible-playbook: playbook: "path/to/playbook.yml" inventory-type: "path" inventory: path: "path/to/inventory-file" variables: - name: "my_variable" value: "my_value"
OR
--- builders: - ansible-playbook: playbook: "path/to/playbook.yml" inventory-type: "content" inventory: content: | [all] machine01.example.com machine02.example.com hosts: "masters" tags-to-run: "ose" tags-to-skip: "ovirt" task-to-start-at: "Deploy application" workers: 2 credentials-id: "0891c950-487b-4749-aa69-d87425e14459" vault-credentials-id: "0421b950-487b-4749-aa69-d87425e14459" sudo: true sudo-user: "cloud-user" unbuffered-output: false colorized-output: true additional-parameters: "-vvv" variables: - name: "complete_var" value: "complete value" hidden: false - name: "empty_var" - name: "hidden_var" value: "Do not appear in console" hidden: true
Example(s) versions < 1.0:
--- builders: - ansible-playbook: playbook: "path/to/playbook.yml" inventory-type: "do-not-specify" become: "yes" become-user: "cloud-user" host-key-checking: false
-
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 (required)
artifacts (list) –
list of artifacts to resolve
- Artifact
group-id (str) – Group ID of the artifact (required)
artifact-id (str) – Artifact ID of the artifact (required)
version (str) – Version of the artifact (required)
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 ‘’)
Minimal Example:
builders: - artifact-resolver: target-directory: foo artifacts: - group-id: commons-logging artifact-id: commons-logging version: "1.1"
Full 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
-
build-publish-docker-image¶ Provides the ability to build projects with a Dockerfile and publish the resultant tagged image (repo) to the docker registry.
Requires the Jenkins CloudBees Docker Build and Publish plugin.
- Parameters
docker-registry-url (str) – URL to the Docker registry you are using (default ‘’)
image (str) – Repository name to be applied to the resulting image in case of success (default ‘’)
docker-file-directory (str) – Build step that sends a Dockerfile for building to docker host that used for this build run (default ‘’)
push-on-success (bool) – Resulting docker image will be pushed to the registry (or registries) specified within the “Image” field (default false)
push-credentials-id (str) – Credentials to push to a private registry (default ‘’)
clean-images (bool) – Option to clean local images (default false)
jenkins-job-delete (bool) – Attempt to remove images when jenkins deletes the run (default false)
cloud (str) – Cloud to use to build image (default ‘’)
Minimal example:
builders: - build-publish-docker-image
Full example:
builders: - build-publish-docker-image: docker-registry-url: Docker registry URL image: Image string docker-file-directory: Directory for Dockerfile push-on-success: true push-credentials-id: 71e4f29c-162b-40d0-85d9-3ddfba2911a0 clean-images: true jenkins-job-delete: true cloud: cloud
-
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)
Minimal Example:
builders: - change-assembly-version
Full 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 (str) –
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 invokingcmake --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/dirKEY=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 another job (BuildResultTrigger Plugin)
- exclusive-cause
(bool) There might by multiple causes 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)
Examples:
builders: - conditional-step: condition-kind: always steps: - shell: 'first command' - shell: 'second command'
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 (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:
builders: - config-file-provider: files: - file-id: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012 target: target variable: variable replace-tokens: true
Minimal Example:
builders: - config-file-provider: files: - file-id: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012
-
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 (str) – 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 (str) – Filter matching jobs based on these parameters (optional)
exclude (str) – Specify paths or patterns of artifacts to exclude, even if specified in “Artifacts to copy”. (default ‘’)
result-var-suffix (str) – The build number of the selected build will be recorded into the variable named COPYARTIFACT_BUILD_NUMBER_(SUFFIX) for later build steps to reference. (default ‘’)
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 exclude: "*.txt" result-var-suffix: "PROJECT_ABC"
-
critical-block-end¶ Designate the end of a critical block. Must be used in conjunction 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 the 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 conjunction 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 the 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¶ Provides the ability to build projects with a Dockerfile, and publish the resultant tagged image (repo) to the docker registry.
Requires the Jenkins Docker build publish Plugin.
- Parameters
repo-name (str) – Name of repository to push to.
repo-tag (str) – Tag for image. (default ‘’)
server (dict) –
The docker daemon (optional)
uri (str): Define the docker server to use. (optional)
credentials-id (str): ID of credentials to use to connect (optional)
registry (dict) –
Registry to push to
url (str) repository url to use (optional)
credentials-id (str): ID of credentials to use to connect (optional)
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) – Path of the Dockerfile. (default ‘’)
build-context (str) – Project root path for the build, defaults to the workspace if not specified. (default ‘’)
create-fingerprint (bool) – If enabled, the plugin will create fingerprints after the build of each image. (default false)
build-args (str) – Additional build arguments passed to docker build (default ‘’)
force-tag (bool) – Force tag replacement when tag already exists (default false)
Minimal 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/' build-context: '/tmp/' create-fingerprint: true build-args: --build-arg https_proxy="http://some.proxy:port" force-tag: true
Full 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/' build-context: '/tmp/' create-fingerprint: true build-args: --build-arg https_proxy="http://some.proxy:port" force-tag: true registry: url: 'https://registry.example.org' credentials-id: 'registry-docker' server: uri: 'unix:///var/run/docker.sock' credentials-id: 'docker-server'
-
docker-pull-image¶ Provides integration between Jenkins and Docker Hub, utilizing a Docker Hub hook to trigger one (or more) Jenkins job(s).
Requires the Jenkins CloudBees Docker Hub Notification.
- Parameters
image (str) – Image ID on DockerHub (default ‘’)
docker-registry-url (str) – URL to the Docker registry you are using (default ‘’)
credentials-id (str) – Registry credentials (default ‘’)
Minimal example:
builders: - docker-pull-image
Full example:
builders: - docker-pull-image: image: test-image-id docker-registry-url: https://index.docker.io/v1/ credentials-id: 71e4f29c-162b-40d0-85d9-3ddfba2911a0
-
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"
-
fingerprint¶ Adds the ability to generate fingerprints as build steps instead of waiting for a build to complete.
Requires the Jenkins Fingerprint Plugin.
- Parameters
targets (str) – Files to fingerprint (default ‘’)
Full Example:
builders: - fingerprint: targets: module/dist/**/*.zip
Minimal Example:
builders: - fingerprint
-
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 (default ‘’)
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}.
build-file (str) – name of gradle build script (default ‘build.gradle’)
pass-system-properties (bool) – Pass all parameters as System properties (default false)
pass-project-properties (bool) – Pass all parameters as Project properties (default false)
Example:
builders: - gradle: build-file: "build.gradle" gradle-name: "gradle-1.2" wrapper: true executable: true use-root-dir: true root-build-script-dir: ${workspace}/tests pass-system-properties: true pass-project-properties: true 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 (default ‘(Default)’)
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 (required)
server-port (str) – Specify a value for the server.port system property (default ‘’)
work-dir (str) – Specify a value for the grails.work.dir system property (default ‘’)
project-dir (str) – Specify a value for the grails.project.work.dir system property (default ‘’)
base-dir (str) – Specify a path to the root of the Grails project (default ‘’)
properties (str) – Additional system properties to set (default ‘’)
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)
Full 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
Minimal Example:
builders: - grails: targets: foo
-
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. (default ‘’)
script-parameters (str) – These parameters will be passed to the script. (default ‘’)
properties (str) – Instead of passing properties using the -D parameter you can define them here. (default ‘’)
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. (default ‘’)
class-path (str) – Specify script classpath here. Each line is one class path item. (default ‘’)
Minimal Example:
builders: - groovy: command: "println Hello"
Full Example:
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 separated 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
-
jenkins-jira-issue-updater¶ Updates issues in Atlassian JIRA as part of a Jenkins job.
Requires the Jenkins Jira Issue Updater Plugin.
- Parameters
base-url (str) – The base url of the rest API. (default ‘’)
username (str) – The Jira username (required)
password (str) – The Jira password (required)
jql (str) – The JQL used to select the issues to update. (required)
workflow (str) – The Name of the workflow action to be executed. (default ‘’)
comment (str) – The Jira comment to be added. (default ‘’)
custom-Id (str) – The Jira custom field to be edited. (default ‘’)
custom-value (str) – Jira custom field value. (default ‘’)
fail-if-error (bool) – Fail this build if JQL returns error. ((default false)
fail-if-no-match (bool) – Fail this build if no issues are matched. (default false)
fail-if-no-connection (bool) – Fail this build if can’t connect to Jira. (default false)
Minimal Example:
builders: - jenkins-jira-issue-updater: username: 'Username' password: 'Password' jql: 'jql'
Full Example:
builders: - jenkins-jira-issue-updater: base-url: url username: your-username password: your-password jql: project-key workflow: workflow-name comment: comment custom-Id: ID custom-value: value fail-if-error: true fail-if-no-match: true fail-if-no-connection: true
-
jms-messaging¶ - The JMS Messaging Plugin provides the following functionality:
A build trigger to submit jenkins jobs upon receipt of a matching message.
A builder that may be used to submit a message to the topic upon the completion of a job
A post-build action that may be used to submit a message to the topic upon the completion of a job
- JMS Messaging provider types supported:
ActiveMQ
FedMsg
Requires the Jenkins JMS Messaging Plugin Pipeline Plugin.
- Parameters
override-topic (str) – If you need to override the default topic. (default ‘’)
provider-name (str) – Name of message provider setup in the global config. (default ‘’)
msg-type (str) – A message type (default ‘CodeQualityChecksDone’)
msg-props (str) – Message header to publish. (default ‘’)
msg-content (str) – Message body to publish. (default ‘’)
Full Example:
builders: - jms-messaging: override-topic: org.centos.stage.ci.pipeline.compose.complete provider-name: fedmsg msg-type: Custom msg-props: | topic=org.centos.prod.ci.pipeline.compose.complete username=fedora-atomic msg-content: | { "build_url": "${BUILD_URL}", "compose_url": "<full-url-to-compose>", "build_id": "${BUILD_ID}", "ref": "fedora/rawhide/${basearch}/atomic-host", "rev": "<sha of the commit from dist-git>", "namespace": "rpms", "repo": "php-simplepie", "status": "<success/failure/aborted>", "test_guidance": "<comma-separated-list-of-test-suites-to-run>" }
Minimal Example:
builders: - jms-messaging: provider-name: fedmsg msg-type: CodeQualityChecksDone msg-props: test msg-content: test
-
kmap¶ Publish mobile applications to your Keivox KMAP Private Mobile App Store.
Requires the Jenkins Keivox KMAP Private Mobile App Store Plugin.
- Parameters
username (str) – KMAP’s user email with permissions to upload/publish applications to KMAP (required)
password (str) – Password for the KMAP user uploading/publishing applications (required)
url (str) – KMAP’s url. This url must always end with “/kmap-client/”. For example: http://testing.example.org/kmap-client/ (required)
categories (str) – Categories’ names. If you want to add the application to more than one category, write the categories between commas. (required)
file-path (str) – Path to the application’s file (required)
app-name (str) – KMAP’s application name (required)
bundle (str) – Bundle indentifier (default ‘’)
version (str) – Application’s version (required)
description (str) – Application’s description (default ‘’)
icon-path (str) – Path to the application’s icon (default ‘’)
publish-optional (bool) –
Publish application after it has been uploaded to KMAP (default false)
- publish-optional
- groups (‘str’) – groups’ names to publish the application
(default ‘’)
- users (‘str’) – users’ names to publish the application
(default ‘’)
- notify-users (‘bool’) – Send notifications to the users and
groups when publishing the application (default false)
Minimal Example:
builders: - kmap: username: user@user.com password: password url: http://foo.com/kmap-client/ categories: Productivity file-path: ${WORKSPACE}/path/to/file.extension app-name: AppName version: b${BUILD_NUMBER}_r${SVN_REVISION}
Full Example:
builders: - kmap: username: user@user.com password: password url: http://foo.com/kmap-client/ categories: Productivity file-path: ${WORKSPACE}/path/to/file.extension app-name: AppName bundle: foo.apk version: b${BUILD_NUMBER}_r${SVN_REVISION} description: description icon-path: ${WORKSPACE}/target/application.png publish-optional: true groups: MobileUsers users: user@user.com notify-users: true
-
managed-script¶ This step allows you to reference and execute a centrally managed script within your build.
Requires the Jenkins Managed Scripts 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 (required)
pom (str) – Location of pom.xml (default ‘pom.xml’)
goals (str) – Goals to execute (required)
maven-opts (str) – Additional options for maven (default ‘’)
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)
settings-type (str) – Type of settings file file|cfp. (default file)
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)
global-settings-type (str) – Type of settings file file|cfp. (default file)
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 :jenkins-plugins:’MSBuild Plugin <msbuild>`.
- Parameters
msbuild-version (str) – which msbuild configured in Jenkins to use (default ‘(Default)’)
solution-file (str) – location of the solution file to build (required)
extra-parameters (str) – extra parameters to pass to msbuild (default ‘’)
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)
unstable-if-warnings (bool) – If set to true and warnings on compilation, the build will be unstable (>=1.20) (default false)
Full 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 unstable-if-warnings: True
Minimal Example:
builders: - msbuild: solution-file: MySolution.sln
-
multijob¶ Define a multijob phase.
Requires the Jenkins Multijob Plugin.
This builder may only be used in
jenkins_jobs.modules.project_multijob.MultiJobprojects.- Parameters
name (str) – MultiJob phase name
condition (str) – when to trigger the other job. Can be: ‘SUCCESSFUL’, ‘UNSTABLE’, ‘COMPLETED’, ‘FAILURE’, ‘ALWAYS’. (default ‘SUCCESSFUL’)
execution-type (str) – Define how to run jobs in a phase: sequentially or parallel. Can be: ‘PARALLEL’, ‘SEQUENTIALLY’ (default ‘PARALLEL’)
projects (list) –
list of projects to include in the MultiJob phase
- Project
name (str) – Project name
alias (str) – Project alias, which will be shown in MultiJob Overview. Helpful when working with the same project multiple times with different configurations
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)
aggregate-results (bool) – Aggregate test results. (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)
- retry (dict): Enable retry strategy (optional)
- retry
max-retry (int) – Max number of retries (default 0)
strategy-path (str) – Parsing rules path (required)
Example:
builders: - multijob: name: PhaseOne condition: SUCCESSFUL execution-type: PARALLEL 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 execution-type: SEQUENTIALLY projects: - name: PhaseTwoJobA current-parameters: true predefined-parameters: foo=bar node-parameters: true aggregate-results: 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 - multijob: name: PhaseFour execution-type: PARALLEL projects: - name: PhaseFourJobA retry: max-retry: 3 strategy-path: "/PhaseFour/PhaseFourRetry.prop" - multijob: name: PhaseFive projects: - name: PhaseFiveJobA alias: PhaseFiveJobRunA - name: PhaseFiveJobA alias: PhaseFiveJobRunB
-
nexus-artifact-uploader¶ To upload result of a build as an artifact in Nexus without the need of Maven.
Requires the Jenkins Nexus Artifact Uploader Plugin.
- Parameters
protocol (str) – Protocol to use to connect to Nexus (default https)
nexus_url (str) – Nexus url (without protocol) (default ‘’)
nexus_user (str) – Username to upload artifact to Nexus (default ‘’)
nexus_password (str) – Password to upload artifact to Nexus (default ‘’)
group_id (str) – GroupId to set for the artifact to upload (default ‘’)
artifact_id (str) – ArtifactId to set for the artifact to upload (default ‘’)
version (str) – Version to set for the artifact to upload (default ‘’)
packaging (str) – Packaging to set for the artifact to upload (default ‘’)
type (str) – Type to set for the artifact to upload (default ‘’)
classifier (str) – Classifier to set for the artifact to upload (default ‘’)
repository (str) – In which repository to upload the artifact (default ‘’)
file (str) – File which will be the uploaded artifact (default ‘’)
credentials_id (str) – Credentials to use (instead of password) (default ‘’)
File Example:
builders: - nexus-artifact-uploader: nexus_url: 'nexus.org' group_id: 'com.example' artifact_id: 'artifact' version: '1.0' packaging: 'pom' type: 'zip' repository: 'my-hosted-repo' file: '/var/lib/jenkins/workspace/my_job/result.zip'
-
nexus-iq-policy-evaluator¶ Integrates the Nexus Lifecycle into a Jenkins job. This function triggers ‘Invokes Nexus Policy Evaluation’.
Requires the Jenkins Nexus Platform Plugin.
- Parameters
stage (str) –
Controls the stage the policy evaluation will be run against on the Nexus IQ Server (required)
- stage values
build
stage-release
release
operate
application-type (dict) –
Specifies an IQ Application (default manual)
- application-type values
manual
selected
application-id (str) – Specify the IQ Application ID (required)
scan-patterns (list) – List of Ant-style patterns relative to the workspace root that denote files/archives to be scanned (default [])
fail-build-network-error (bool) – Controls the build outcome if there is a failure in communicating with the Nexus IQ Server (default false)
Minimal Example:
builders: - nexus-iq-policy-evaluator: stage: 'build' application-id: 'nexus-iq-application-id001'
Full Example:
builders: - nexus-iq-policy-evaluator: stage: 'stage-release' application-type: 'selected' application-id: 'nexus-iq-application-id002' scan-patterns: - '**/target/*.war' - '**/target/*.ear' fail-build-network-error: true
-
nexus-repo-manager¶ Allows for artifacts selected in Jenkins packages to be available in Nexus Repository Manager.
Requires the Jenkins Nexus Platform Plugin.
- Parameters
instance-id (str) – The ID of the Nexus Instance (required)
repo-id (str) – The ID of the Nexus Repository (required)
Minimal Example:
builders: - nexus-repo-manager: instance-id: Nexus-Repo-Instance repo-id: Releases
-
nodejs¶ This plugin allows you to execute NodeJS scripts as a job build step.
Requires the Jenkins NodeJS Plugin.
- Parameters
name (str) – NodeJS installation name
script (str) – NodeJS script (required)
config-id (str) – ID of npmrc config file, which is the last field (a 32-digit hexadecimal code) of the path of URL visible after you clicked the file under Jenkins Managed Files.
Minimal Example:
builders: - nodejs: script: "console.log('Some output');"
Full Example:
builders: - nodejs: name: "NodeJS_8.1" script: "console.log('Some output');" config-id: "e3757442-7c21-4a65-a1ff-6c70f5c6df34"
-
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. (default ‘’)
verbose (bool) – 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. (default ‘’)
commit-ID (str) – The value here is what you supply with the –commit option when invoking the OpenShift oc start-build command. (default ‘’)
verbose (bool) – 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. (default ‘’)
show-build-logs (bool) – 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. (default ‘’)
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. (default ‘’)
verbose (bool) – 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 (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. (default ‘’)
verbose (bool) – 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. (default ‘’)
verbose (bool) – 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. (default ‘’)
verbose (bool) – 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. (default ‘’)
verbose (bool) – 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. (default ‘’)
verbose (bool) – 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-cifs¶ Upload files via CIFS.
Requires the Jenkins Publish over CIFS 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
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)
flatten (bool) – only create files on the server, don’t create directories (default false)
Example:
builders: - publish-over-cifs: site: 'cifs.share' target: 'dest/dir' source: 'base/source/dir/**' remove-prefix: 'base/source/dir' excludes: '**/*.excludedfiletype' flatten: true
-
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)
Minimal Example:
builders: - runscope: test-trigger-url: "https://api.runscope.com/radar/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/trigger" access-token: "123456"
Full Example:
builders: - runscope: test-trigger-url: "https://api.runscope.com/radar/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/trigger" access-token: "123456" timeout: 123
-
saltstack¶ Send a message to Salt API.
Requires the Jenkins saltstack plugin.
- Parameters
servername (str) – Salt master server name (required)
authtype (str) – Authentication type (‘pam’ or ‘ldap’, default ‘pam’)
credentials (str) – Credentials ID for which to authenticate to Salt master (required)
target (str) – Target minions (default ‘’)
targettype (str) – Target type (‘glob’, ‘pcre’, ‘list’, ‘grain’, ‘pillar’, ‘nodegroup’, ‘range’, or ‘compound’, default ‘glob’)
function (str) – Function to execute (default ‘’)
arguments (str) – Salt function arguments (default ‘’)
kwarguments (str) – Salt keyword arguments (default ‘’)
saveoutput (bool) – Save Salt return data into environment variable (default false)
clientinterface (str) – Client interface type (‘local’, ‘local-batch’, or ‘runner’, default ‘local’)
wait (bool) – Wait for completion of command (default false)
polltime (str) – Number of seconds to wait before polling job completion status (default ‘’)
batchsize (str) – Salt batch size, absolute value or %-age (default 100%)
mods (str) – Mods to runner (default ‘’)
setpillardata (bool) – Set Pillar data (default false)
pillarkey (str) – Pillar key (default ‘’)
pillarvalue (str) – Pillar value (default ‘’)
Minimal Example:
builders: - saltstack: servername: '{{SALT_MASTER}}' credentials: 'credentials ID'
Full Example:
builders: - saltstack: servername: '{{SALT_MASTER}}' credentials: 'credentials ID' clientinterface: runner mods: runner_mods setpillardata: true pillarkey: pkey pillarvalue: pvalue wait: true polltime: 10 target: '{{HOSTS}}' targettype: list function: pkg.update saveoutput: true
-
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"
-
scan-build¶ This plugin allows you configure a build step that will execute the Clang scan-build static analysis tool against an XCode project.
The scan-build report has to be generated in the directory
${WORKSPACE}/clangScanBuildReportsfor the publisher to find it.Requires the Jenkins Clang Scan-Build Plugin.
- Parameters
target (str) – Provide the exact name of the XCode target you wish to have compiled and analyzed (required)
target-sdk (str) – Set the simulator version of a currently installed SDK (default iphonesimulator)
config (str) – Provide the XCode config you wish to execute scan-build against (default Debug)
clang-install-name (str) – Name of clang static analyzer to use (default ‘’)
xcode-sub-path (str) – Path of XCode project relative to the workspace (default ‘’)
workspace (str) – Name of workspace (default ‘’)
scheme (str) – Name of scheme (default ‘’)
scan-build-args (str) – Additional arguments to clang scan-build (default –use-analyzer Xcode)
xcode-build-args (str) – Additional arguments to XCode (default -derivedDataPath $WORKSPACE/build)
report-folder (str) – Folder where generated reports are located (>=1.7) (default clangScanBuildReports)
Full Example:
builders: - scan-build: target: path/to/target target-sdk: iphonesimulator config: Debug clang-install-name: Analyzer xcode-sub-path: myProj/subfolder workspace: workspace scheme: SchemeName scan-build-args: --use-analyzer Xcode xcode-build-args: -derivedDataPath $WORKSPACE/build report-folder: clangScanBuildReports
Minimal Example:
builders: - scan-build: target: path/to/target
-
shell¶ Execute a shell command.
There are two ways of configuring the builder, with a plain string to execute:
- Parameters
parameter (str) – the shell command to execute
Or with a mapping that allows other parameters to be passed:
- Parameters
command (str) – the shell command to execute
unstable-return (int) – the shell exit code to interpret as an unstable build result
Example:
builders: - shell: "make test"
builders: - shell: command: "make test" unstable-return: 3
-
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.
sonar-scanner (str) – Name of the Sonar Scanner.
task (str) – Task to run. (default ‘’)
project (str) – Path to Sonar project properties file. (default ‘’)
properties (str) – Sonar configuration properties. (default ‘’)
java-opts (str) – Java options for Sonnar Runner. (default ‘’)
additional-arguments (str) – additional command line arguments (default ‘’)
jdk (str) – JDK to use (inherited from the job if omitted). (optional)
Example:
builders: - sonar: sonar-name: Sonar scanner-name: scanner-3.x task: views project: sonar-project.properties properties: sonar.views.list=myview1,myview2 java-opts: -Xmx512m additional-arguments: -X
-
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: release 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 choose a script file instead)
sandbox (bool) – Execute script inside of groovy sandbox (>=2.0) (default false)
bindings (str) – Define variable bindings (in the properties file format). Specified variables can be addressed from the script. (optional)
str) class-path ((list) – List of script class paths. (optional)
Examples:
builders: - system-groovy: file: "test.groovy"
builders: - system-groovy: command: "println 'Hello'" bindings: "EXAMPLE=foo-bar" class-path: "file:/home/user/example.jar" sandbox: true
-
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)
restrict-matrix-project (str) – Filter that restricts the subset of the combinations that the triggered job will run (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)
- Factory
factory (str) allonlinenodes – Trigger a build on every online node. Requires NodeLabel Parameter Plugin (optional)
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 - factory: allonlinenodes block: true
-
trigger-remote¶ Trigger build of job on remote Jenkins instance.
Requires the Jenkins 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)
enhanced-logging (bool) – if this option is enabled, the console output of the remote job is also logged. (default false)
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 enhanced-logging: True property-file: '.props' predefined-parameters: | FOO="bar" herp="derp"
-
xcode¶ This step allows you to execute an xcode build step.
Requires the Jenkins Xcode Plugin.
- Parameters
developer-profile (str) – the jenkins credential id for a ios developer profile. (optional)
clean-build (bool) – if true will delete the build directories before invoking the build. (default false)
clean-test-reports (bool) – UNKNOWN. (default false)
archive (bool) – if true will generate an xcarchive of the specified scheme. A workspace and scheme are are also needed for archives. (default false)
configuration (str) – This is the name of the configuration as defined in the Xcode project. (default ‘Release’)
configuration-directory (str) – The value to use for CONFIGURATION_BUILD_DIR setting. (default ‘’)
target (str) – Leave empty for all targets. (default ‘’)
sdk (str) – Leave empty for default SDK. (default ‘’)
symroot (str) – Leave empty for default SYMROOT. (default ‘’)
project-path (str) – Relative path within the workspace that contains the xcode project file(s). (default ‘’)
project-file (str) – Only needed if there is more than one project file in the Xcode Project Directory. (default ‘’)
build-arguments (str) – Extra commandline arguments provided to the xcode builder. (default ‘’)
schema (str) – Only needed if you want to compile for a specific schema instead of a target. (default ‘’)
workspace (str) – Only needed if you want to compile a workspace instead of a project. (default ‘’)
profile (str) – The relative path to the mobileprovision to embed, leave blank for no embedded profile. (default ‘’)
codesign-id (str) – Override the code signing identity specified in the project. (default ‘’)
allow-failing (bool) – if true will prevent this build step from failing if xcodebuild exits with a non-zero return code. (default false)
version-technical (str) – The value to use for CFBundleVersion. Leave blank to use project’s technical number. (default ‘’)
version-marketing (str) – The value to use for CFBundleShortVersionString. Leave blank to use project’s marketing number. (default ‘’)
ipa-export-method (str) – The export method of the .app to generate the .ipa file. Should be one in ‘development’, ‘ad-hoc’, ‘enterprise’, or ‘app-store’. (default ‘’)
ipa-version (str) – A pattern for the ipa file name. You may use ${VERSION} and ${BUILD_DATE} (yyyy.MM.dd) in this string. (default ‘’)
ipa-output (str) – The output directory for the .ipa file, relative to the build directory. (default ‘’)
compile-bitcode (bool) – recompile from Bitcode when exporting the application to IPA. (default true)
upload-bitcode (bool) – include Bitcode when exporting applications to IPA. (default true)
upload-symbols (bool) – include symbols when exporting applications to IPA. (default true)
development-team-id – The ID of the Apple development team to use to sign the IPA (default ‘’)
keychain-name (str) – The globally configured keychain to unlock for this build. (default ‘’)
keychain-path (str) – The path of the keychain to use to sign the IPA. (default ‘’)
keychain-password (str) – The password to use to unlock the keychain. (default ‘’)
keychain-unlock (str) – Unlocks the keychain during use. (default false)
bundle-id (str) – The bundle identifier (App ID) for this provisioning profile (default ‘’)
provisioning-profile-uuid (str) – The UUID of the provisioning profile associated to this bundle identifier. (default ‘’)
Example:
builders: - xcode - xcode: developer-profile: "849b07cd-ac61-4588-89c8-b6606ee84946" clean-build: true clean-test-reports: true configuration: Distribution target: TARGET sdk: iphonesimulator build-arguments: "test ONLY_ACTIVE_ARCH=NO -destination 'platform=iOS Simulator,name=iPhone 6' -derivedDataPath ." schema: "UASDKInternal" workspace: "UA" profile: "PROFILE" codesign-id: "iPhone Distribution: MapMyFitness Inc." allow-failing: true version-technical: "TECHNICAL" version-marketing: "MARKETING" ipa-export-method: ad-hoc ipa-version: "${VERSION}" ipa-output: "/output" compile-bitcode: false upload-bitcode: false upload-symbols: false development-team-id: foo keychain-path: "/Users/jenkins/Library/Keychains/jenkins-uasdk-ios-pre_review" keychain-password: "testpass" keychain-unlock: true provisioning-profiles: - bundle-id: foo provisioning-profile-uuid: bar - bundle-id: foo2 provisioning-profile-uuid: bar2
-
xunit¶ Process tests results.
Requires the Jenkins xUnit Plugin.
- Parameters
thresholdmode (str) – Whether thresholds represents an absolute number of tests or a percentage. Either ‘number’ or ‘percent’. (default ‘number’)
thresholds (list) –
Thresholds for both ‘failed’ and ‘skipped’ tests.
- threshold (dict)
Threshold values to set, where missing, xUnit should default to an internal value of 0. Each test threshold should contain the following:
unstable (int)
unstablenew (int)
failure (int)
failurenew (int)
test-time-margin (int) – Give the report time margin value in ms, before to fail if not new unless the option requireupdate is set for the configured framework. (default 3000)
types (list) –
Frameworks to configure, and options. Supports the following:
aunit,boosttest,checktype,cpptest,cppunit,ctest,dotnettest,embunit,fpcunit,gtest,junit,mstest,nunit,phpunit,tusar,unittest, andvalgrind.The ‘custom’ type is not supported.
- type (dict)
each type can be configured using the following:
pattern (str): An Ant pattern to look for Junit result files, relative to the workspace root (default ‘’)
requireupdate (bool): fail the build whenever fresh tests results have not been found (default true).
deleteoutput (bool): delete temporary JUnit files (default true).
skip-if-no-test-files (bool): Skip parsing this xUnit type report if there are no test reports files (default false).
stoponerror (bool): Fail the build whenever an error occur during a result file processing (default true).
Minimal Example:
builders: - xunit: types: - junit: pattern: "junit.xml"
Full Example:
builders: - xunit: thresholdmode: 'percent' thresholds: - failed: unstable: 0 unstablenew: 0 failure: 0 failurenew: 0 - skipped: unstable: 0 unstablenew: 0 failure: 0 failurenew: 0 test-time-margin: 5000 types: - phpunit: pattern: "phpunit.log" requireupdate: true deleteoutput: true skip-if-no-test-files: false stoponerror: true - cppunit: pattern: "cppunit.log" requireupdate: false deleteoutput: false skip-if-no-test-files: true stoponerror: false - gtest: pattern: "gtest.log"