Provided by: jenkins-job-builder_0.5.0-2_all 
NAME
jenkins-jobs - Jenkins Job Builder Documentation
Jenkins Job Builder takes simple descriptions of Jenkins jobs in YAML format, and uses
them to configure Jenkins. You can keep your job descriptions in human readable text
format in a version control system to make changes and auditing easier. It also has a
flexible template system, so creating many similarly configured jobs is easy.
Contents:
INSTALLATION
To install Jenkins Job Builder, run:
sudo python setup.py install
The OpenStack project uses puppet to manage its infrastructure systems, including Jenkins.
If you use Puppet, you can use the OpenStack Jenkins module to install Jenkins Job
Builder.
Configuration File
After installation, you will need to create a configuration file. By default,
jenkins-jobs looks in /etc/jenkins_jobs/jenkins_jobs.ini but you may specify an alternate
location when running jenkins-jobs. The file should have the following format:
[jenkins]
user=USERNAME
password=PASSWORD
url=JENKINS_URL
user This should be the name of a user previously defined in Jenkins. Appropriate user
permissions must be set under the Jenkins security matrix: under the Global group
of permissions, check Read, then under the Job group of permissions, check Create,
Delete, Configure and finally Read.
password
The API token for the user specified. You can get this through the Jenkins
management interface under People -> username -> Configure and then click the Show
API Token button.
url The base URL for your Jenkins installation.
Running
After it's installed and configured, you can invoke Jenkins Job Builder by running
jenkins-jobs. You won't be able to do anything useful just yet without a configuration
which is discussed in the next section). But you should be able to get help on the
various commands by running:
jenkins-jobs --help
jenkins-jobs update --help
jenkins-jobs test --help
(etc.)
Once you have a configuration defined, you can test it with:
jenkins-jobs test /path/to/config -o /path/to/output
That will write XML files to the output directory for all of the jobs defined in the
configuration directory. When you're satisfied, you can run:
jenkins-jobs update /path/to/config
Which will upload the configurations to Jenkins if needed. Jenkins Job Builder maintains,
for each host, a cache of previously configured jobs, so that you can run that command as
often as you like, and it will only update the configuration in Jenkins if the defined
configuration has changed since the last time it was run. Note: if you modify a job
directly in Jenkins, jenkins-jobs will not know about it and will not update it.
To update a specific list of jobs, simply pass them as additional arguments after the
configuration path. To update Foo1 and Foo2 run:
jenkins-jobs update /path/to/config Foo1 Foo2
CONFIGURATION
The job definitions for Jenkins Job Builder are kept in any number of YAML files, in
whatever way you would like to organize them. When you invoke jenkins-jobs you may
specify either the path of a single YAML file, or a directory. If you choose a directory,
all of the .yaml (or .yml) files in that directory will be read, and all the jobs they
define will be created or updated.
Definitions
Jenkins Job Builder understands a few basic object types which are described in the next
sections.
Job
The most straightforward way to create a job is simply to define a Job in YAML. It looks
like this:
- job:
name: job-name
That's not very useful, so you'll want to add some actions such as builders, and perhaps
publishers. Those are described later. There are a few basic optional fields for a Job
definition:
- job:
name: job-name
project-type: freestyle
defaults: global
disabled: false
concurrent: true
quiet-period: 5
workspace: /srv/build-area/job-name
block-downstream: false
block-upstream: false
project-type
Defaults to "freestyle", but "maven" can also be specified.
defaults
Specifies a set of Defaults to use for this job, defaults to ''global''. If you
have values that are common to all of your jobs, create a global Defaults object to
hold them, and no further configuration of individual jobs is necessary. If some
jobs should not use the global defaults, use this field to specify a different set
of defaults.
disabled
Boolean value to set whether or not this job should be disabled in Jenkins.
Defaults to false (job will be enabled).
concurrent
Boolean value to set whether or not Jenkins can run this job concurrently. Defaults
to false.
quiet-period
Number of seconds to wait between consecutive runs of this job. Defaults to 0.
workspace
Path for a custom workspace. Defaults to Jenkins default configuration.
block-downstream
Boolean value to set whether or not this job must block while downstream jobs are
running. Downstream jobs are determined transitively. Defaults to false.
block-upstream
Boolean value to set whether or not this job must block while upstream jobs are
running. Upstream jobs are determined transitively. Defaults to false.
auth-token
Specifies an authentication token that allows new builds to be triggered by
accessing a special predefined URL. Only those who know the token will be able to
trigger builds remotely.
Job Template
If you need several jobs defined that are nearly identical, except perhaps in their names,
SCP targets, etc., then you may use a Job Template to specify the particulars of the job,
and then use a Project to realize the job with appropriate variable substitution.
A Job Template has the same syntax as a Job, but you may add variables anywhere in the
definition. Variables are indicated by enclosing them in braces, e.g., {name} will
substitute the variable name. When using a variable in a string field, it is good
practice to wrap the entire string in quotes, even if the rules of YAML syntax don't
require it because the value of the variable may require quotes after substitution.
You must include a variable in the name field of a Job Template (otherwise, every instance
would have the same name). For example:
- job-template:
name: '{name}-unit-tests'
Will not cause any job to be created in Jenkins, however, it will define a template that
you can use to create jobs with a Project definition. It's name will depend on what is
supplied to the Project.
Project
The purpose of a project is to collect related jobs together, and provide values for the
variables in a Job Template. It looks like this:
- project:
name: project-name
jobs:
- '{name}-unit-tests'
Any number of arbitrarily named additional fields may be specified, and they will be
available for variable substitution in the job template. Any job templates listed under
jobs: will be realized with those values. The example above would create the job called
'project-name-unit-tests' in Jenkins.
The jobs: list can also allow for specifying job-specific substitutions as follows:
- project:
name: project-name
jobs:
- '{name}-unit-tests':
mail-to: developer@nowhere.net
- '{name}-perf-tests':
mail-to: projmanager@nowhere.net
If a variable is a list, the job template will be realized with the variable set to each
value in the list. Multiple lists will lead to the template being realized with the
cartesian product of those values. Example:
- project:
name: project-name
pyver:
- 26
- 27
jobs:
- '{name}-{pyver}'
Job Group
If you have several Job Templates that should all be realized together, you can define a
Job Group to collect them. Simply use the Job Group where you would normally use a Job
Template and all of the Job Templates in the Job Group will be realized. For example:
- job-template:
name: '{name}-python-26'
- job-template:
name: '{name}-python-27'
- job-group:
name: python-jobs
jobs:
- '{name}-python-26'
- '{name}-python-27'
- project:
name: foo
jobs:
- python-jobs
Would cause the jobs foo-python-26 and foo-python-27 to be created in Jekins.
Macro
Many of the actions of a Job, such as builders or publishers, can be defined as a Macro,
and then that Macro used in the Job description. Builders are described later, but let's
introduce a simple one now to illustrate the Macro functionality. This snippet will
instruct Jenkins to execute "make test" as part of the job:
- job:
name: foo-test
builders:
- shell: 'make test'
If you wanted to define a macro (which won't save much typing in this case, but could
still be useful to centralize the definition of a commonly repeated task), the
configuration would look like:
- builder:
name: make-test
builders:
- shell: 'make test'
- job:
name: foo-test
builders:
- make-test
This allows you to create complex actions (and even sequences of actions) in YAML that
look like first-class Jenkins Job Builder actions. Not every attribute supports Macros,
check the documentation for the action before you try to use a Macro for it.
Macros can take parameters, letting you define a generic macro and more specific ones
without having to duplicate code:
# The 'add' macro takes a 'number' parameter and will creates a
# job which prints 'Adding ' followed by the 'number' parameter:
- builder:
name: add
builders:
- shell: "echo Adding {number}"
# A specialized macro 'addtwo' reusing the 'add' macro but with
# a 'number' parameter hardcoded to 'two':
- builder:
name: addtwo
builders:
- add:
number: "two"
# Glue to have Jenkins Job Builder to expand this YAML example:
- job:
name: "testingjob"
builders:
# The specialized macro:
- addtwo
# Generic macro call with a parameter
- add:
number: "ZERO"
# Generic macro called without a parameter. Never do this!
# See below for the resulting wrong output :(
- add
Then <builders /> section of the generated job show up as:
<builders>
<hudson.tasks.Shell>
<command>echo Adding two</command>
</hudson.tasks.Shell>
<hudson.tasks.Shell>
<command>echo Adding ZERO</command>
</hudson.tasks.Shell>
<hudson.tasks.Shell>
<command>echo Adding {number}</command>
</hudson.tasks.Shell>
</builders>
As you can see, the specialized macro addtwo reused the definition from the generic macro
add. Whenever you forget a parameter from a macro, it will not be expanded and left as
is, which will most probably cause havoc in your Jenkins builds.
Defaults
Defaults collect job attributes (including actions) and will supply those values when the
job is created, unless superseded by a value in the 'Job'_ definition. If a set of
Defaults is specified with the name global, that will be used by all Job (and Job
Template) definitions unless they specify a different Default object with the defaults
attribute. For example:
- defaults:
name: global
description: 'Do not edit this job through the web!'
Will set the job description for every job created.
Modules
The bulk of the job definitions come from the following modules.
Freestyle Project
The Freestyle Project module handles creating freestyle Jenkins projects (i.e., those that
do not use Maven). You may specify freestyle in the project-type attribute to the Job
definition if you wish, though it is the default, so you may omit project-type altogether
if you are creating a freestyle project.
Example:
job:
name: test_job
project-type: freestyle
Maven Project
The Maven Project module handles creating Maven Jenkins projects.
To create a Maven project, specify maven in the project-type attribute to the Job
definition. It also requires a maven section in the Job definition.
Job Parameters
•
root-module:
• group-id (str): GroupId. (required)
• artifact-id (str): ArtifactId. (required)
• root-pom (str): The path to the pom.xml file. (defaults to pom.xml)
• goals (str): Goals to execute. (required)
• maven-opts (str): Java options to pass to maven (aka MAVEN_OPTS)
• maven-name (str): Installation of maven which should be used. Not setting
maven-name appears to use the first maven install defined in the global jenkins
config.
• ignore-upstream-changes (bool): Do not start a build whenever a SNAPSHOT
dependency is built or not. (defaults to true)
• automatic-archiving (bool): Activate automatic artifact archiving (defaults to
true).
Example:
job:
name: doc_job
project-type: maven
maven:
root-module:
group-id: org.example.docs
artifact-id: example-guide
root-pom: doc/src/pom.xml
goals: "clean generate-sources"
maven-opts: '-Dmyvar=/path/somewhere'
maven-name: Maven3
automatic-archiving: true
Matrix Project
The matrix project module handles creating Jenkins matrix projects. To create a matrix
project specify matrix in the project-type attribute to the Job definition. Currently it
only supports three axes which share the same internal YAML structure:
• label expressions (label-expression)
• user-defined values (user-defined)
• slave name or label (slave)
Job Parameters
•
execution-strategy (optional):
• combination-filter (str): axes selection filter
• sequential (bool): run builds sequentially (default false)
•
touchstone (optional):
• expr (str) -- selection filter for the touchstone build
• result (str) -- required result of the job: stable
(default) or unstable
•
axes (list):
•
axis:
• type (str) -- axis type, must be either 'label-expression',
'user-defined' or 'slave'.
• name (str) -- name of the axis
• values (list) -- values of the axis
Example:
- job:
name: matrix-test
project-type: matrix
execution-strategy:
combination-filter: |
!(os=="fedora11" && arch=="amd64")
sequential: true
touchstone:
expr: 'os == "fedora11"'
result: unstable
axes:
- axis:
type: label-expression
name: os
values:
- ubuntu12.04
- fedora11
- axis:
type: label-expression
name: arch
values:
- amd64
- i386
- axis:
type: slave
name: nodes
values:
- node1
- node2
builders:
- shell: make && make check
Example using user-defined axis:
- job:
name: matrix-user-defined
project-type: matrix
axes:
- axis:
type: user-defined
name: database
values:
- mysql
- postgresql
- sqlite
builders:
- shell: make "$database"
General Job Configuration
The most straightforward way to create a job is simply to define a Job in YAML. It looks
like this:
- job:
name: job-name
That's not very useful, so you'll want to add some actions such as builders, and perhaps
publishers. Those are described later. There are a few basic optional fields for a Job
definition:
- job:
name: job-name
project-type: freestyle
defaults: global
disabled: false
concurrent: true
workspace: /srv/build-area/job-name
quiet-period: 5
block-downstream: false
block-upstream: false
Job Parameters
• project-type: Defaults to "freestyle", but "maven" can also be specified.
• defaults: Specifies a set of defaults to use for this job, defaults to
''global''. If you have values that are common to all of your jobs, create a
global defaults object to hold them, and no further configuration of individual
jobs is necessary. If some jobs should not use the global defaults, use this
field to specify a different set of defaults.
• disabled: Boolean value to set whether or not this job should be disabled in
Jenkins. Defaults to false (job will be enabled).
• concurrent: Boolean value to set whether or not Jenkins can run this job
concurrently. Defaults to false.
• workspace: Path for a custom workspace. Defaults to Jenkins default
configuration.
• quiet-period: Number of seconds to wait between consecutive runs of this job.
Defaults to 0.
• block-downstream: Boolean value to set whether or not this job must block while
downstream jobs are running. Downstream jobs are determined transitively.
Defaults to false.
• block-upstream: Boolean value to set whether or not this job must block while
upstream jobs are running. Upstream jobs are determined transitively. Defaults to
false.
• auth-token: Specifies an authentication token that allows new builds to be
triggered by accessing a special predefined URL. Only those who know the token
will be able to trigger builds remotely.
The Logrotate section allows you to automatically remove old build history. It adds the
logrotate attribute to the Job definition.
Example:
- job:
name: test_job
logrotate:
daysToKeep: 3
numToKeep: 20
artifactDaysToKeep: -1
artifactNumToKeep: -1
The Assigned Node section allows you to specify which Jenkins node (or named group) should
run the specified job. It adds the node attribute to the Job definition.
Example:
- job:
name: test_job
node: precise
That speficies that the job should be run on a Jenkins node or node group named precise.
Builders
Builders define actions that the Jenkins job should execute. Examples include shell
scripts or maven targets. The builders attribute in the Job definition accepts a list of
builders to invoke. They may be components defined below, locally defined macros (using
the top level definition of builder:, or locally defined components found via the
jenkins_jobs.builders entry point.
Component: builders
Macro builder
Entry Point
jenkins_jobs.builders
Example:
job:
name: test_job
builders:
- shell: "make test"
ant Execute an ant target. Requires the Jenkins Ant Plugin.
To setup this builder you can either reference the list of targets or use named
parameters. Below is a description of both forms:
1) Listing targets:
After the ant directive, simply pass as argument a space separated list of targets
to build.
Parameter
space separated list of Ant targets
Parameters
ant-name (str) -- the name of the ant installation, defaults to 'default'
(optional)
Example to call two Ant targets:
builders:
- ant: "target1 target2"
ant-name: "Standard Ant"
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, defaults to 'default'
(optional)
• java-opts (str) -- java options for ant, can have multiples, must be in
quotes (optional)
Example specifying the build file too and several targets:
builders:
- ant:
targets: "debug test install"
buildfile: "build.xml"
properties:
builddir: "/tmp/"
failonerror: true
java-opts:
- "-ea"
- "-Xmx512m"
ant-name: "Standard Ant"
artifact-resolver
Allows one to resolve artifacts from a maven repository like nexus (without having
maven installed) Requires the Jenkins Repository Connector Plugin
Parameters
• fail-on-error (bool) -- Whether to fail the build on error (default false)
• repository-logging (bool) -- Enable repository logging (default false)
• target-directory (str) -- Where to resolve artifacts to
• artifacts (list) --
list of artifacts to resolve
Artifact
• group-id (str) -- Group ID of the artifact
• artifact-id (str) -- Artifact ID of the artifact
• version (str) -- Version of the artifact
• classifier (str) -- Classifier of the artifact (default '')
• extension (str) -- Extension of the artifact (default 'jar')
• target-file-name (str) -- What to name the artifact (default '')
Example:
builders:
- artifact-resolver:
fail-on-error: true
repository-logging: true
target-directory: foo
artifacts:
- group-id: commons-logging
artifact-id: commons-logging
version: 1.1
classifier: src
extension: jar
target-file-name: comm-log.jar
- group-id: commons-lang
artifact-id: commons-lang
version: 1.2
batch Execute a batch command.
Parameter
the batch command to execute
Example:
builders:
- batch: "foo/foo.bat"
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:
- project: "base-build"
conditional-step
Conditionaly 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 is 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 │
├───────────────────┼─────────────────────────────────────────────┤
│current-status │ Run the build step if the current │
│ │ build status is within the configured │
│ │ range │
│ │ │
│ │ condition-worst │
│ │ Worst status │
│ │ │
│ │ condition-best │
│ │ Best status │
├───────────────────┼─────────────────────────────────────────────┤
│shell │ Run the step if the shell command │
│ │ succeed │
│ │ │
│ │ condition-command │
│ │ Shell command │
│ │ to execute │
├───────────────────┼─────────────────────────────────────────────┤
│windows-shell │ Similar to shell, except that │
│ │ commands will be executed by cmd, │
│ │ under Windows │
│ │ │
│ │ condition-command │
│ │ Command to │
│ │ execute │
├───────────────────┼─────────────────────────────────────────────┤
│file-exists │ Run the step if a file exists │
│ │ │
│ │ condition-filename │
│ │ Check │
│ │ existence of │
│ │ this file │
│ │ │
│ │ condition-basedir │
│ │ If │
│ │ condition-filename │
│ │ is relative, │
│ │ it will be │
│ │ considered │
│ │ relative to │
│ │ either │
│ │ workspace, │
│ │ artifact-directory, │
│ │ or │
│ │ jenkins-home. │
│ │ Default is │
│ │ workspace. │
└───────────────────┴─────────────────────────────────────────────┘
Example:
builders:
- conditional-step:
condition-kind: boolean-expression
condition-expression: "${ENV,var=IS_STABLE_BRANCH}"
on-evaluation-failure: mark-unstable
steps:
- shell: "echo Making extra checks"
copyartifact
Copy artifact from another project. Requires the Jenkins Copy Artifact 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)
• which-build (str) -- which build to get artifacts from (optional, default
last-successful)
• 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
• stable (bool) -- specifies to get only last stable build when
last-successful is specified as which-build
• fallback-to-last-successful (bool) -- specifies to fallback to last
successful build when upstream-build is specified as which-build
• param (string) -- specifies to use a build parameter to get the build when
build-param is specified as which-build
Which-build values
• last-successful
• specific-build
• last-saved
• upstream-build
• permalink
• workspace-latest
• build-param
Permalink values
• last
• last-stable
• last-successful
• last-failed
• last-unstable
• last-unsuccessful
Example:
builders:
- copyartifact:
project: foo
filter: *.tar.gz
target: /home/foo
which-build: specific-build
build-number: 123
flatten: true
gradle Execute gradle tasks. Requires the Jenkins Gradle Plugin.
Parameters
• tasks (str) -- List of tasks to execute
• gradle-name (str) -- Use a custom gradle name (optional)
• wrapper (bool) -- use gradle wrapper (default false)
• executable (bool) -- make gradlew executable (default false)
• switches (list) -- Switches for gradle, can have multiples
Example:
builders:
- gradle:
gradle-name: "gradle-1.2"
wrapper: true
executable: 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 (optional)
• force-upgrade (bool) -- Run 'grails upgrade --non-interactive' first
(default false)
• non-interactive (bool) -- append --non-interactive to all build targets
(default false)
• targets (str) -- Specify target(s) to run separated by spaces
• server-port (str) -- Specify a value for the server.port system property
(optional)
• work-dir (str) -- Specify a value for the grails.work.dir system property
(optional)
• project-dir (str) -- Specify a value for the grails.project.work.dir
system property (optional)
• base-dir (str) -- Specify a path to the root of the Grails project
(optional)
• properties (str) -- Additional system properties to set (optional)
• plain-output (bool) -- append --plain-output to all build targets (default
false)
• stack-trace (bool) -- append --stack-trace to all build targets (default
false)
• verbose (bool) -- append --verbose to all build targets (default false)
• refresh-dependencies (bool) -- append --refresh-dependencies to all build
targets (default false)
Example:
builders:
- grails:
use-wrapper: "true"
name: "grails-2.2.2"
force-upgrade: "true"
non-interactive: "true"
targets: "war ear"
server-port: "8003"
work-dir: "./grails-work"
project-dir: "./project-work"
base-dir: "./grails/project"
properties: "program.name=foo"
plain-output: "true"
stack-trace: "true"
verbose: "true"
refresh-dependencies: "true"
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)
Example:
builders:
- inject:
properties-file: example.prop
properties-content: EXAMPLE=foo-bar
maven-target
Execute top-level Maven targets
Parameters
• goals (str) -- Goals to execute
• properties (str) -- Properties for maven, can have multiples
• pom (str) -- Location of pom.xml (defaults to pom.xml)
• maven-version (str) -- Installation of maven which should be used
(optional)
Example:
builders:
- maven-target:
maven-version: Maven3
pom: parent/pom.xml
goals: clean
properties:
- foo=bar
- bar=foo
msbuild
Build .NET project using msbuild. Requires the Jenkins MSBuild Plugin.
Parameters
• msbuild-version (str) -- which msbuild configured in Jenkins to use
(optional)
• solution-file (str) -- location of the solution file to build
• extra-parameters (str) -- extra parameters to pass to msbuild (optional)
• pass-build-variables (bool) -- should build variables be passed to msbuild
(defaults to true)
• continue-on-build-failure (bool) -- should the build continue if msbuild
returns an error (defaults to false)
Example:
builders:
- msbuild:
solution-file: "MySolution.sln"
msbuild-version: "msbuild-4.0"
extra-parameters: "/maxcpucount:4"
pass-build-variables: False
continue-on-build-failure: True
multijob
Define a multijob phase. Requires the Jenkins Multijob Plugin.
This builder may only be used in jenkins_jobs.modules.project_multijob.MultiJob
projects.
Parameters
• name (str) -- MultiJob phase name
• condition (str) -- when to trigger the other job (default 'SUCCESSFUL')
• projects (list) --
list of projects to include in the MultiJob phase
Project
• name (str) -- Project name
• current-parameters (bool) -- Pass current build parameters to the
other job (default false)
• 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)
Example:
builders:
- multijob:
name: PhaseOne
condition: SUCCESSFUL
projects:
- name: PhaseOneJobA
current-parameters: true
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
shell Execute a shell command.
Parameter
the shell command to execute
Example:
builders:
- shell: "make test"
trigger-builds
Trigger builds of other jobs. Requires the Jenkins Parameterized Trigger Plugin.
Parameters
• project (str) -- the Jenkins project to trigger
• predefined-parameters (str) -- key/value pairs to be passed to the job
(optional)
• current-parameters (bool) -- Whether to include the parameters passed to
the current build to the triggered job.
• svn-revision (bool) -- Whether to pass the svn revision to the triggered
job
• block (bool) -- whether to wait for the triggered jobs to finish or not
(default false)
Example:
builders:
- trigger-builds:
- project: "build_started"
predefined-parameters:
FOO="bar"
block: true
Hipchat
Enable hipchat notification of build execution.
Example:
- job:
name: test_job
hipchat:
enabled: true
room: Testjob Build Notifications
start-notify: true
In the jenkins UI specification, the hipchat plugin must be explicitly selected as a
publisher. This is not required (or supported) here - use the enabled parameter to
enable/disable the publisher action. If you set enabled: false, no hipchat parameters are
written to XML.
Notifications
The Notifications module allows you to configure Jenkins to notify other applications
about various build phases. It requires the Jenkins notification plugin.
Component: notifications
Macro notification
Entry Point
jenkins_jobs.notifications
Example:
job:
name: test_job
notifications:
- http:
url: http://example.com/jenkins_endpoint
http Defines an HTTP notification endpoint. Requires the Jenkins Notification Plugin.
Parameters
url (str) -- URL of the endpoint
Example:
notifications:
- http:
url: http://example.com/jenkins_endpoint
Parameters
The Parameters module allows you to specify build parameters for a job.
Component: parameters
Macro parameter
Entry Point
jenkins_jobs.parameters
Example:
job:
name: test_job
parameters:
- string:
name: FOO
default: bar
description: "A parameter named FOO, defaults to 'bar'."
bool A boolean parameter.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- bool:
name: FOO
default: false
description: "A parameter named FOO, defaults to 'false'."
choice A single selection parameter.
Parameters
• name (str) -- the name of the parameter
• choices (list) -- the available choices
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- choice:
name: project
choices:
- nova
- glance
description: "On which project to run?"
file A file parameter.
Parameters
• name (str) -- the target location for the file upload
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- file:
name: test.txt
description: "Upload test.txt."
label A node label parameter.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- label:
name: node
default: precise
description: "The node on which to run the job"
password
A password parameter.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- password:
name: FOO
default: 1HSC0Ts6E161FysGf+e1xasgsHkgleLh09JUTYnipPvw=
description: "A parameter named FOO."
string A string parameter.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- string:
name: FOO
default: bar
description: "A parameter named FOO, defaults to 'bar'."
svn-tags
A svn tag parameter Requires the Jenkins Parameterized Trigger Plugin.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
• url (str) -- the url to list tags from
• filter (str) -- the regular expression to filter tags
Example:
parameters:
- svn-tags:
name: BRANCH_NAME
default: release
description: A parameter named BRANCH_NAME default is release
url: http://svn.example.com/repo
filter: [A-za-z0-9]*
text A text parameter.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
Example:
parameters:
- text:
name: FOO
default: bar
description: "A parameter named FOO, defaults to 'bar'."
validating-string
A validating string parameter Requires the Jenkins Validating String Plugin.
Parameters
• name (str) -- the name of the parameter
• default (str) -- the default value of the parameter (optional)
• description (str) -- a description of the parameter (optional)
• regex (str) -- a regular expression to validate the string
• msg (str) -- a message to display upon failed validation
Example:
parameters:
- validating-string:
name: FOO
default: bar
description: "A parameter named FOO, defaults to 'bar'."
regex: [A-Za-z]*
msg: Your entered value failed validation
Properties
The Properties module supplies a wide range of options that are implemented as Jenkins job
properties.
Component: properties
Macro property
Entry Point
jenkins_jobs.properties
Example:
job:
name: test_job
properties:
- github:
url: https://github.com/openstack-ci/jenkins-job-builder/
authenticated-build
Specifies an authorization matrix where only authenticated users may trigger a
build.
DEPRECATED
Example:
properties:
- authenticated-build
authorization
Specifies an authorization matrix
The available rights are:
job-delete job-configure job-read job-discover job-build job-workspace
job-cancel run-delete run-update scm-tag
Example:
properties:
- authorization:
admin:
- job-delete
- job-configure
- job-read
- job-discover
- job-build
- job-workspace
- job-cancel
- run-delete
- run-update
- scm-tag
anonymous:
- job-discover
- job-read
extended-choice
Creates an extended choice property where values can be read from a file Requires
the Jenkins Extended Choice Parameter Plugin.
Parameters
• name (string) -- name of the property
• description (string) -- description of the property (optional, default '')
• property-file (string) -- location of property file to read from
(optional, default '')
• property-key (string) -- key for the property-file (optional, default '')
• quote-value (bool) -- whether to put quotes around the property when
passing to Jenkins (optional, default false)
• visible-items (string) -- number of items to show in the list (optional,
default 5)
• type (string) -- type of select (optional, default single-select)
• value (string) -- comma separated list of values for the single select or
multi-select box (optional, default '')
• default-value (string) -- used to set the initial selection of the
single-select or multi-select box (optional, default '')
• default-property-file (string) -- location of property file when default
value needs to come from a property file (optional, default '')
• default-property-key (string) -- key for the default property file
(optional, default '')
Example:
properties:
- extended-choice:
name: FOO
description: A foo property
property-file: /home/foo/property.prop
property-key: key
quote-value: true
visible-items: 10
type: multi-select
value: foo,bar,select
default-value: foo
default-property-file: /home/property.prop
default-property-key: fookey
github Sets the GitHub URL for the project.
Parameters
url (str) -- the GitHub URL
Example:
properties:
- github:
url: https://github.com/openstack-ci/jenkins-job-builder/
inject Allows you to inject evironment variables into the build. Requires the Jenkins Env
Inject Plugin.
Parameters
• properties-file (str) -- file to read with properties (optional)
• properties-content (str) -- key=value properties (optional)
• script-file (str) -- file with script to run (optional)
• script-content (str) -- script to run (optional)
• groovy-content (str) -- groovy script to run (optional)
• load-from-master (bool) -- load files from master (default false)
• enabled (bool) -- injection enabled (default true)
• keep-system-variables (bool) -- keep system variables (default true)
• keep-build-variables (bool) -- keep build variable (default true)
Example:
properties:
- inject:
properties-content: FOO=bar
promoted-build
Marks a build for promotion. A promotion process with an identical name must be
created via the web interface in the job in order for the job promotion to persist.
Promotion processes themselves cannot be configured by jenkins-jobs due to the
separate storage of plugin configuration files. Requires the Jenkins Promoted
Builds Plugin.
Parameters
names (list) -- the promoted build names
Example:
properties:
- promoted-build:
names:
- "Release to QA"
- "Jane Must Approve"
throttle
Throttles the number of builds for this job. Requires the Jenkins Throttle
Concurrent Builds Plugin.
Parameters
• max-per-node (int) -- max concurrent builds per node (default 0)
• max-total (int) -- max concurrent builds (default 0)
• enabled (bool) -- whether throttling is enabled (default True)
• option (str) -- throttle project or category
• categories (list) -- multiproject throttle categories
Example:
properties:
- throttle:
max-total: 4
categories:
- cat1
- cat2
Publishers
Publishers define actions that the Jenkins job should perform after the build is complete.
Component: publishers
Macro publisher
Entry Point
jenkins_jobs.publishers
Example:
job:
name: test_job
publishers:
- scp:
site: 'example.com'
source: 'doc/build/html/**/*'
target_path: 'project'
aggregate-tests
Aggregate downstream test results
Parameters
include-failed-builds (bool) -- whether to include failed builds
Example:
publishers:
- aggregate-tests:
include-failed-builds: true
archive
Archive build artifacts
Parameters
• artifacts (str) -- path specifier for artifacts to archive
• excludes (str) -- path specifier for artifacts to exclude
• latest-only (bool) -- only keep the artifacts from the latest successful
build
Example:
publishers:
- archive:
artifacts: '*.tar.gz'
checkstyle
Publish trend reports with Checkstyle. Requires the Checkstyle Plugin.
The checkstyle component accepts a dictionary with the following values:
Parameters
• pattern (str) -- report filename pattern
• canRunOnFailed (bool) -- also runs for failed builds (instead of just
stable or unstable builds)
• shouldDetectModules (bool) --
• healthy (int) -- sunny threshold
• unHealthy (int) -- stormy threshold
• healthThreshold (str) -- threshold priority for health status (high: only
high, normal: high and normal, low: all)
• thresholds (dict) -- .INDENT 2.0
thresholds
•
unstable (dict)
unstable
• totalAll (int)
• totalHigh (int)
• totalNormal (int)
• totalLow (int)
•
failed (dict)
failed
• totalAll (int)
• totalHigh (int)
• totalNormal (int)
• totalLow (int)
• defaultEncoding (str) -- encoding for parsing or showing files (empty will use
platform default)
Example:
publishers:
- checkstyle:
pattern: '**/checkstyle-result.xml'
healthy: 0
unHealthy: 100
healthThreshold: 'high'
thresholds:
unstable:
totalHigh: 10
failed:
totalHigh: 1
cifs Upload files via CIFS. Requires the Jenkins Publish over CIFS Plugin.
Parameters
• site (str) -- name of the cifs site/share
• target (str) -- destination directory
• target-is-date-format (bool) -- whether target is a date format. If true,
raw text should be quoted (defaults to False)
• clean-remote (bool) -- should the remote directory be deleted before
transfering files (defaults to 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 (defaults to
False).
Example:
publishers:
- cifs:
site: 'cifs.share'
target: 'dest/dir'
source: 'base/source/dir/**'
remove-prefix: 'base/source/dir'
excludes: '**/*.excludedfiletype'
claim-build
Claim build failures Requires the Jenkins Claim Plugin.
Example:
publishers:
- claim-build
cobertura
Generate a cobertura coverage report. Requires the Jenkins Cobertura Coverage
Plugin.
Parameters
• report-file (str) -- This is a file name pattern that can be used to
locate the cobertura xml report files (optional)
• only-stable (bool) -- Include only stable builds (default false)
• fail-no-reports (bool) -- fail builds if no coverage reports are found
(default false)
• fail-unhealthy (bool) -- Unhealthy projects will be failed (default false)
• fail-unstable (bool) -- Unstable projects will be failed (default false)
• health-auto-update (bool) -- Auto update threshold for health on
successful build (default false)
• stability-auto-update (bool) -- Auto update threshold for stability on
successful build (default false)
• zoom-coverage-chart (bool) -- Zoom the coverage chart and crop area below
the minimum and above the maximum coverage of the past reports (default
false)
• source-encoding (str) -- Override the source encoding (default ASCII)
• targets (dict) -- .INDENT 2.0
targets
(packages, files, classes, method, line, conditional)
• healthy (int): Healthy threshold (default 0)
• unhealthy (int): Unhealthy threshold (default 0)
• failing (int): Failing threshold (default 0)
Example:
publishers:
- cobertura:
report-file: "/reports/cobertura/coverage.xml"
only-stable: "true"
fail-no-reports: "true"
fail-unhealthy: "true"
fail-unstable: "true"
health-auto-update: "true"
stability-auto-update: "true"
zoom-coverage-chart: "true"
source-encoding: "Big5"
targets:
- files:
healthy: 10
unhealthy: 20
failing: 30
- method:
healthy: 50
unhealthy: 40
failing: 30
copy-to-master
Copy files to master from slave Requires the Jenkins Copy To Slave Plugin.
Parameters
• includes (list) -- list of file patterns to copy
• excludes (list) -- list of file patterns to exclude
• destination (string) -- absolute path into which the files will be copied.
If left blank they will be copied into the workspace of the current job
Example:
publishers:
- copy-to-master:
includes:
- file1
- file2*.txt
excludes:
- file2bad.txt
coverage
WARNING: The coverage function is deprecated. Instead, use the cobertura function
to generate a cobertura coverage report. Requires the Jenkins Cobertura Coverage
Plugin.
Example:
publishers:
- coverage
cppcheck
Cppcheck result publisher Requires the Jenkins Cppcheck Plugin.
Parameters
pattern (str) -- file pattern for cppcheck xml report
for more optional parameters see the example
Example:
publishers:
- cppcheck:
pattern: "**/cppcheck.xml"
# the rest is optional
# build status (new) error count thresholds
thresholds:
unstable: 5
new-unstable: 5
failure: 7
new-failure: 3
# severities which count towards the threshold, default all true
severity:
error: true
warning: true
information: false
graph:
xysize: [500, 200]
# which errors to display, default only sum
display:
sum: false
error: true
email Email notifications on build failure.
Parameters
• recipients (str) -- Recipient email addresses
• notify-every-unstable-build (bool) -- Send an email for every unstable
build (default true)
• send-to-individuals (bool) -- Send an email to the individual who broke
the build (default false)
Example:
publishers:
- email:
recipients: breakage@example.com
email-ext
Extend Jenkin's built in email notification Requires the Jenkins Email-ext Plugin.
Parameters
• recipients (str) -- Comma separated list of emails
• reply-to (str) -- Comma separated list of emails that should be in the
Reply-To header for this project (default is $DEFAULT_RECIPIENTS)
• subject (str) -- Subject for the email, can include variables like
${BUILD_NUMBER} or even groovy or javascript code
• body (str) -- Content for the body of the email, can include variables
like ${BUILD_NUMBER}, but the real magic is using groovy or javascript to
hook into the Jenkins API itself
• attach-build-log (bool) -- Include build log in the email (default false)
• unstable (bool) -- Send an email for an unstable result (default false)
• first-failure (bool) -- Send an email for just the first failure (default
false)
• not-built (bool) -- Send an email if not built (default false)
• aborted (bool) -- Send an email if the build is aborted (default false)
• regression (bool) -- Send an email if there is a regression (default
false)
• failure (bool) -- Send an email if the build fails (default true)
• improvement (bool) -- Send an email if the build improves (default false)
• still-failing (bool) -- Send an email if the build is still failing
(default false)
• success (bool) -- Send an email for a successful build (default false)
• fixed (bool) -- Send an email if the build is fixed (default false)
• still-unstable (bool) -- Send an email if the build is still unstable
(default false)
• pre-build (bool) -- Send an email before the build (default false)
Example:
publishers:
- email-ext:
recipients: foo@example.com, bar@example.com
reply-to: foo@example.com
subject: Subject for Build ${BUILD_NUMBER}
body: The build has finished
attach-build-log: false
unstable: true
first-failure: true
not-built: true
aborted: true
regression: true
failure: true
improvement: true
still-failing: true
success: true
fixed: true
still-unstable: true
pre-build: true
fingerprint
Fingerprint files to track them across builds
Parameters
• files (str) -- files to fingerprint, follows the @includes of Ant fileset
(default is blank)
• record-artifacts (bool) -- fingerprint all archived artifacts (default
false)
Example:
publishers:
- fingerprint:
files: builddir/test*.xml
record-artifacts: false
ftp Upload files via FTP. Requires the Jenkins Publish over FTP Plugin.
Parameters
• site (str) -- name of the ftp site
• target (str) -- destination directory
• target-is-date-format (bool) -- whether target is a date format. If true,
raw text should be quoted (defaults to False)
• clean-remote (bool) -- should the remote directory be deleted before
transfering files (defaults to 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 (defaults to
False).
Example:
publishers:
- ftp:
site: 'ftp.example.com'
target: 'dest/dir'
source: 'base/source/dir/**'
remove-prefix: 'base/source/dir'
excludes: '**/*.excludedfiletype'
groovy-postbuild
Execute a groovy script. Requires the Jenkins Groovy Postbuild Plugin
Parameter
the groovy script to execute
Example:
publishers:
- groovy-postbuild: "manager.buildFailure()"
jabber Integrates Jenkins with the Jabber/XMPP instant messaging protocol Requires the
Jenkins Jabber Plugin.
Parameters
• notify-on-build-start (bool) -- Whether to send notifications to channels
when a build starts (default false)
• notify-scm-committers (bool) -- Whether to send notifications to the users
that are suspected of having broken this build (default false)
• notify-scm-culprits (bool) -- Also send notifications to 'culprits' from
previous unstable/failed builds (default false)
• notify-upstream-committers (bool) -- Whether to send notifications to
upstream committers if no committers were found for a broken build
(default false)
• notify-scm-fixers (bool) -- Whether to send notifications to the users
that have fixed a broken build (default false)
• group-targets (list) -- List of group targets to notify
• individual-targets (list) -- List of individual targets to notify
• strategy (dict) --
When to send notifications (default all)
strategy values
• all -- Always
• failure -- On any failure
• failure-fixed -- On failure and fixes
• change -- Only on state change
• message (dict) --
Channel notification message (default summary-scm)
message values
• summary-scm -- Summary + SCM changes
• summary -- Just summary
• summary-build -- Summary and build parameters
• summary-scm-fail -- Summary, SCM changes, and failed tests
Example:
publishers:
- jabber:
notify-on-build-start: true
group-targets:
- "foo-room@conference-2-fooserver.foo.com"
individual-targets:
- "foo-user@conference-2-fooserver.foo.com"
strategy: all
message: summary-scm
jira Update relevant JIRA issues Requires the Jenkins JIRA Plugin
Example:
publishers:
- jira
join-trigger
Trigger a job after all the immediate downstream jobs have completed
Parameters
projects (list) -- list of projects to trigger
Example:
publishers:
- join-trigger:
projects:
- project-one
- project-two
junit Publish JUnit test results.
Parameters
results (str) -- results filename
Example:
publishers:
- junit:
results: nosetests.xml
logparser
Requires the Jenkins Log Parser Plugin.
Parameters
• parse-rules (str) -- full path to parse rules
• unstable-on-warning (bool) -- mark build unstable on warning
• fail-on-error (bool) -- mark build failed on error
Example::
publishers:
•
logparser:
parse-rules: "/path/to/parserules" unstable-on-warning: true
fail-on-error: true
maven-deploy
Deploy artifacts to Maven repository.
Parameters
• id (str) -- Repository ID
• url (str) -- Repository URL
• unique-version (bool) -- Assign unique versions to snapshots (default
true)
• deploy-unstable (bool) -- Deploy even if the build is unstable (default
false)
Example:
publishers:
- maven-deploy:
id: example
url: http://repo.example.com/maven2/
unique-version: true
deploy-unstable: false
performance
Publish performance test results from jmeter and junit. Requires the Jenkins
Performance Plugin.
Parameters
• failed-threshold (int) -- Specify the error percentage threshold that set
the build failed. A negative value means don't use this threshold (default
0)
• unstable-threshold (int) -- Specify the error percentage threshold that
set the build unstable. A negative value means don't use this threshold
(default 0)
• report (dict) -- .INDENT 2.0
(jmeter or junit)
(dict or str): Specify a custom report file (optional; jmeter default
**/.jtl, junit default */TEST-*.xml)
Examples:
publishers:
- performance:
failed-threshold: 85
unstable-threshold: -1
report:
- jmeter: "/special/file.jtl"
- junit: "/special/file.xml"
publishers:
- performance:
failed-threshold: 85
unstable-threshold: -1
report:
- jmeter
- junit
publishers:
- performance:
failed-threshold: 85
unstable-threshold: -1
report:
- jmeter: "/special/file.jtl"
- junit: "/special/file.xml"
- jmeter
- junit
pipeline
Specify a downstream project in a pipeline. Requires the Jenkins Build Pipeline
Plugin.
Parameter
the name of the downstream project
Example:
publishers:
- pipleline: deploy
You can build pipeline jobs that are re-usable in different pipelines by using a
job-template to define the pipeline jobs, and variable substitution to specify the
name of the downstream job in the pipeline. Job-specific substitutions are useful
here (see project).
See 'samples/pipeline.yaml' for an example pipeline implementation.
scp Upload files via SCP Requires the Jenkins SCP Plugin.
Parameters
• site (str) -- name of the scp site
• target (str) -- destination directory
• source (str) -- source path specifier
• keep-hierarchy (bool) -- keep the file hierarchy when uploading (default
false)
• copy-after-failure (bool) -- copy files even if the job fails (default
false)
• copy-console (bool) -- copy the console log (default false); if specified,
omit 'target'
Example:
publishers:
- scp:
site: 'example.com'
target: 'dest/dir'
source: 'base/source/dir/**'
sonar Sonar plugin support. Requires the Jenkins Sonar Plugin.
Parameters
• jdk (str) -- JDK to use (inherited from the job if omitted). (optional)
• branch (str) -- branch onto which the analysis will be posted (optional)
• language (str) -- source code language (optional)
• maven-opts (str) -- options given to maven (optional)
• additional-properties (str) -- sonar analysis parameters (optional)
• skip-global-triggers (dict) -- .INDENT 2.0
Triggers
• skip-when-scm-change (bool): skip analysis when build triggered by
scm
• skip-when-upstream-build (bool): skip analysis when build triggered
by an upstream build
• skip-when-envvar-defined (str): skip analysis when the specified
environment variable is set to true
This publisher supports the post-build action exposed by the Jenkins Sonar Plugin, which
is triggering a Sonar Analysis with Maven.
Example:
publishers:
- sonar:
jdk: MyJdk
branch: myBranch
language: java
maven-opts: -DskipTests
additional-properties: -DsonarHostURL=http://example.com/
skip-global-triggers:
skip-when-scm-change: true
skip-when-upstream-build: true
skip-when-envvar-defined: SKIP_SONAR
ssh Upload files via SCP. 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 (defaults to False)
• clean-remote (bool) -- should the remote directory be deleted before
transfering files (defaults to 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 (defaults to
False).
Example:
publishers:
- ssh:
site: 'server.example.com'
target: 'dest/dir'
source: 'base/source/dir/**'
remove-prefix: 'base/source/dir'
excludes: '**/*.excludedfiletype'
trigger
Trigger non-parametrised builds of other jobs.
Parameters
• project (str) -- name of the job to trigger
• threshold (str) -- when to trigger the other job (default 'SUCCESS'),
alternatives: SUCCESS, UNSTABLE, FAILURE
Example:
publishers:
- trigger:
project: other_job
trigger-parameterized-builds
Trigger parameterized builds of other jobs. Requires the Jenkins Parameterized
Trigger Plugin.
Parameters
• project (str) -- name of the job to trigger
• predefined-parameters (str) -- parameters to pass to the other job
(optional)
• current-parameters (bool) -- Whether to include the parameters passed to
the current build to the triggered job (optional)
• svn-revision (bool) -- Pass svn revision to the triggered job (optional)
• git-revision (bool) -- Pass git revision to the other job (optional)
• condition (str) -- when to trigger the other job (default 'ALWAYS')
• property-file (str) -- Use properties from file (optional)
Example:
publishers:
- trigger-parameterized-builds:
- project: other_job, foo, bar
predefined-parameters: foo=bar
- project: other_job1, other_job2
predefined-parameters: BUILD_NUM=${BUILD_NUMBER}
property-file: version.prop
- project: yet_another_job
predefined-parameters: foo=bar
git-revision: true
violations
Publish code style violations. Requires the Jenkins Violations Plugin.
The violations component accepts any number of dictionaries keyed by the name of
the violations system. The dictionary has the following values:
Parameters
• min (int) -- sunny threshold
• max (int) -- stormy threshold
• unstable (int) -- unstable threshold
• pattern (str) -- report filename pattern
Any system without a dictionary provided will use default values.
Valid systems are:
checkstyle, codenarc, cpd, cpplint, csslint, findbugs, fxcop, gendarme,
jcreport, jslint, pep8, pmd, pylint, simian, stylecop
Example:
publishers:
- violations:
pep8:
min: 0
max: 1
unstable: 1
pattern: '**/pep8.txt'
workspace-cleanup (post-build)
See Workspace Cleanup Plugin.
The pre-build workspace-cleanup is available as a wrapper.
Parameters
• include (list) -- list of files to be included
• exclude (list) -- list of files to be excluded
• dirmatch (bool) -- Apply pattern to directories too (default: false)
• clean-if (list) --
clean depending on build status
clean-if values
• success (bool) (default: true)
• unstable (bool) (default: true)
• failure (bool) (default: true)
• aborted (bool) (default: true)
• not-built (bool) (default: true)
• fail-build (bool) -- Fail the build if the cleanup fails (default: true)
• clean-parent (bool) -- Cleanup matrix parent workspace (default: false)
Example:
publishers:
- workspace-cleanup:
include:
- "*.zip"
clean-if:
- success: true
- not-built: false
xunit Publish 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', will
default to 'number' if omitted.
• thresholds (dict) -- list containing the thresholds for both 'failed'
and 'skipped' tests. Each entry should in turn have a list of
"threshold name: values". The threshold names are 'unstable',
'unstablenew', 'failure', 'failurenew'. Omitting a value will resort
on xUnit default value (should be 0).
• types (dict) -- per framework configuration. The key should be one of
the internal types we support: 'aunit', 'boosttest', 'checktype',
'cpptest', 'cppunit', 'fpcunit', 'junit', 'mstest', 'nunit',
'phpunit', 'tusar', 'unittest', 'valgrind'. The 'custom' type is not
supported.
Each framework type can be configured using the following parameters:
Parameters
• pattern (str) -- An Ant pattern to look for Junit result files,
relative to the workspace root.
• requireupdate (bool) -- fail the build whenever fresh tests results
have not been found (default: true).
• deleteoutput (bool) -- delete temporary JUnit files (default: true)
• stoponerror (bool) -- Fail the build whenever an error occur during a
result file processing (default: true).
Example:
publishers:
- xunit:
thresholdmode: 'percent'
thresholds:
- failed:
unstable: 0
unstablenew: 0
failure: 0
failurenew: 0
- skipped:
unstable: 0
unstablenew: 0
failure: 0
failurenew: 0
types:
- phpunit:
pattern: junit.log
- cppUnit:
pattern: cppunit.log
Reporters
Reporters are like publishers but only applicable to Maven projets.
Component: reporters
Macro reporter
Entry Point
jenkins_jobs.reporters
Example:
job:
name: test_job
project-type: maven
reporters:
- email:
recipients: breakage@example.com
email Email notifications on build failure.
Parameters
• recipients (str) -- Recipient email addresses
• notify-every-unstable-build (bool) -- Send an email for every unstable
build (default true)
• send-to-individuals (bool) -- Send an email to the individual who broke
the build (default false)
Example:
reporters:
- email:
recipients: breakage@example.com
SCM
The SCM module allows you to specify the source code location for the project. It adds
the scm attribute to the Job definition, which accepts any number of scm definitions.
Note: Adding more than one scm definition requires the Jenkins Multiple SCMs plugin.
Component: scm
Macro scm
Entry Point
jenkins_jobs.scm
Example:
job:
name: test_job
scm:
-git:
url: https://example.com/project.git
-git:
url: https://example.org/otherproject.git
basedir: other
git Specifies the git SCM repository for this job. Requires the Jenkins Git Plugin.
Parameters
• url (str) -- URL of the git repository
• refspec (str) -- refspec to fetch
• name (str) -- name to fetch
• branches (list(str)) -- list of branch specifiers to build
• excluded-users (list(str)) -- list of users to ignore revisions from when
polling for changes. (if polling is enabled)
• included-regions (list(str)) -- list of file/folders to include
• excluded-regions (list(str)) -- list of file/folders to exclude
• merge (dict) -- .INDENT 2.0
merge
•
remote (string) - name of repo that contains branch to
merge to (default 'origin')
• branch (string) - name of the branch to merge to
• basedir (str) -- location relative to the workspace root to clone to (default:
workspace)
• skip-tag (bool) -- Skip tagging
• prune (bool) -- Prune remote branches
• clean (bool) -- Clean after checkout
• fastpoll (bool) -- Use fast remote polling
• disable-submodules (bool) -- Disable submodules
• recursive-submodules (bool) -- Recursively update submodules
• use-author (bool) -- Use author rather than committer in Jenkin's build changeset
• git-tool (str) -- The name of the Git installation to use
• wipe-workspace (bool) -- Wipe out workspace before build
• browser (str) -- what repository browser to use (default '(Auto)')
• browser-url (str) -- url for the repository browser
Browser values
githubweb
fisheye
bitbucketweb
gitblit
gitlab
gitoriousweb
gitweb
redmineweb
viewgit
Example:
scm:
- git:
url: https://example.com/project.git
branches:
- master
- stable
browser: githubweb
browser-url: http://github.com/foo/example.git
svn Specifies the svn SCM repository for this job.
Parameters
• url (str) -- URL of the svn repository
• basedir (str) -- location relative to the workspace root to checkout to
(default '.')
• workspaceupdater (str) -- optional argument to specify how to update the
workspace (default wipeworkspace)
• repos (list) --
list of repositories to checkout (optional)
Repo
• url (str) -- URL for the repository
•
basedir (str) -- Location relative to the workspace
root to checkout to (default '.')
Workspaceupdater values
wipeworkspace
• deletes the workspace before checking out
revertupdate
• do an svn revert then an svn update
emulateclean
• delete unversioned/ignored files then update
update
• do an svn update as much as possible
Example:
scm:
- svn:
workspaceupdater: update
repos:
- url: http://svn.example.com/repo
basedir: .
- url: http://svn.example.com/repo2
basedir: repo2
tfs Specifies the Team Foundation Server repository for this job. Requires the Jenkins
Team Foundation Server Plugin.
NOTE: TFS Password must be entered manually on the project if a user name is
specified. The password will be overwritten with an empty value every time the job
is rebuilt with Jenkins Job Builder.
Parameters
• server-url (str) -- The name or URL of the team foundation server. If the
server has been registered on the machine then it is only necessary to
enter the name.
• project-path (str) -- The name of the project as it is registered on the
server.
• login (str) -- The user name that is registered on the server. The user
name must contain the name and the domain name. Entered as domain\user or
user@domain (optional). NOTE: You must enter in at least two slashes for
the domain\user format in JJB YAML. It will be rendered normally.
• use-update (str) -- If true, Hudson will not delete the workspace at end
of each build. This causes the artifacts from the previous build to remain
when a new build starts. (default true)
• local-path (str) -- The folder where all files will be retrieved into.
The folder name is a relative path, under the workspace of the current
job. (default .)
• workspace (str) --
The name of the workspace under which the source should be retrieved. This
workspace is created at the start of a download, and deleted at the end.
You can normally omit the property unless you want to name a workspace to
avoid conflicts on the server (i.e. when you have multiple projects on one
server talking to a Team Foundation Server). (default
Hudson-${JOB_NAME}-${NODE_NAME})
The TFS plugin supports the following macros that are replaced in the
workspace name:
• ${JOB_NAME} - The name of the job.
•
${USER_NAME} - The user name that the Hudson server or slave is
running as.
•
${NODE_NAME} - The name of the node/slave that the plugin currently
is executed on. Note that this is not the hostname, this value is
the Hudson configured name of the slave/node.
• ${ENV} - The environment variable that is set on the master or slave.
• web-access (dict) --
Adds links in "changes" views within Jenkins to an external system for
browsing the details of those changes. The "Auto" selection attempts to
infer the repository browser from other jobs, if supported by the SCM and
a job with matching SCM details can be found. (optional, default Auto).
web-access value
• web-url -- Enter the URL to the TSWA server. The plugin will
strip the last path (if any) of the URL when building URLs for
change set pages and other pages. (optional, default uses
server-url)
Examples:
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "mydomain\\jane"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
web-access:
- web-url: "http://TFSMachine:8080"
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "jane@mydomain"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
web-access:
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "mydomain\\jane"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
Triggers
Triggers define what causes a jenkins job to start buliding.
Component: triggers
Macro trigger
Entry Point
jenkins_jobs.triggers
Example:
job:
name: test_job
triggers:
- timed: '@daily'
gerrit Trigger on a Gerrit event. Requires the Jenkins Gerrit Trigger Plugin version >=
2.6.0.
Parameters
• trigger-on-patchset-uploaded-event (bool) -- Trigger on patchset upload
• trigger-on-change-abandoned-event (bool) -- Trigger on change abandoned.
Requires Gerrit Trigger Plugin version >= 2.8.0
• trigger-on-change-merged-event (bool) -- Trigger on change merged
• trigger-on-change-restored-event (bool) -- Trigger on change restored.
Requires Gerrit Trigger Plugin version >= 2.8.0
• trigger-on-comment-added-event (bool) -- Trigger on comment added
• trigger-on-draft-published-event (bool) -- Trigger on draft published
event
• trigger-on-ref-updated-event (bool) -- Trigger on ref-updated
• trigger-approval-category (str) -- Approval category for comment added
• trigger-approval-value (int) -- Approval value for comment added
• override-votes (bool) -- Override default vote values
• gerrit-build-successful-verified-value (int) -- Successful ''Verified''
value
• gerrit-build-failed-verified-value (int) -- Failed ''Verified'' value
• failure-message (str) -- Message to leave on failure
• projects (list) --
list of projects to match
Project
• project-compare-type (str) -- ''PLAIN'', ''ANT'' or ''REG_EXP''
• project-pattern (str) -- Project name pattern to match
• branch-compare-type (str) -- ''PLAIN'', ''ANT'' or ''REG_EXP''
• branch-pattern (str) -- Branch name pattern to match
• file-paths (list) -- List of file paths to match (optional)
File Path
• compare-type (str) -- ''PLAIN'', ''ANT'' or ''REG_EXP''
(optional, defaults to ''PLAIN'')
• pattern (str) -- File path pattern to match
• skip-vote (dict) --
map of build outcomes for which Jenkins must skip vote. Requires Gerrit
Trigger Plugin version >= 2.7.0
Outcome
• successful (bool)
• failed (bool)
• unstable (bool)
• notbuilt (bool)
You may select one or more gerrit events upon which to trigger. You must also
supply at least one project and branch, optionally more. If you select the
comment-added trigger, you should alse indicate which approval category and value
you want to trigger the job.
Until version 0.4.0 of Jenkins Job Builder, camelCase keys were used to configure
Gerrit Trigger Plugin, instead of hyphenated-keys. While still supported,
camedCase keys are deprecated and should not be used.
Example:
triggers:
- gerrit:
trigger-on-comment-added-event: true
trigger-approval-category: 'APRV'
trigger-approval-value: 1
projects:
- project-compare-type: 'PLAIN'
project-pattern: 'test-project'
branch-compare-type: 'ANT'
branch-pattern: '**'
file-paths:
- compare-type: ANT
pattern: subdirectory/**
skip-vote:
successful: true
failed: true
unstable: true
notbuilt: true
github Trigger a job when github repository is pushed to Requires the Jenkins GitHub
Plugin.
Example:
triggers:
- github
github-pull-request
Build pull requests in github and report results Requires the Jenkins GitHub Pull
Request Builder Plugin.
Parameters
• admin-list (list) -- the users with admin rights (optional)
• cron (string) -- cron syntax of when to run (optional)
• white-list (list) -- users whose pull requests build (optional)
• org-list (list) -- orgs whose users should be white listed (optional)
Example:
triggers:
- github-pull-request:
admin-list:
- user1
- user2
cron: * * * * *
white-list:
- user3
- user4
org-list:
- org1
- org2
pollscm
Poll the SCM to determine if there has been a change.
Parameter
the polling interval (cron syntax)
Example:
triggers:
- pollscm: "\*/15 * * * \*"
timed Trigger builds at certain times.
Parameter
when to run the job (cron syntax)
Example:
triggers:
- timed: "@midnight"
Wrappers
Wrappers can alter the way the build is run as well as the build output.
Component: wrappers
Macro wrapper
Entry Point
jenkins_jobs.wrappers
Example:
job:
name: test_job
wrappers:
- timeout:
timeout: 90
fail: true
ansicolor
Translate ANSI color codes to HTML in the console log. Requires the Jenkins Ansi
Color Plugin.
Example:
wrappers:
- ansicolor
build-name
Set the name of the build Requires the Jenkins Build Name Setter Plugin.
Parameters
name (str) -- Name for the build. Typically you would use a variable from
Jenkins in the name. The syntax would be ${FOO} for the FOO variable.
Example:
wrappers:
- build-name:
name: Build-${FOO}
build-user-vars
Set environment variables to the value of the user that started the build.
Requires the Jenkins Build User Vars Plugin.
Example:
wrappers:
- build-user-vars
copy-to-slave
Copy files to slave before build Requires the Jenkins Copy To Slave Plugin.
Parameters
• includes (list) -- list of file patterns to copy
• excludes (list) -- list of file patterns to exclude
• flatten (bool) -- flatten directory structure
• relative-to (str) -- base location of includes/excludes, must be
userContent ($JENKINS_HOME/userContent) home ($JENKINS_HOME) or workspace
• include-ant-excludes (bool) -- exclude ant's default excludes
Example:
wrappers:
- copy-to-slave:
includes:
- file1
- file2*.txt
excludes:
- file2bad.txt
inject Add or override environment variables to the whole build process Requires the
Jenkins EnvInject Plugin.
Parameters
• properties-file (str) -- path to the properties file (default '')
• properties-content (str) -- key value pair of properties (default '')
• script-file (str) -- path to the script file (default '')
• script-content (str) -- contents of a script (default '')
Example:
wrappers:
- inject:
properties-file: /usr/local/foo
properties-content: PATH=/foo/bar
script-file: /usr/local/foo.sh
script-content: echo $PATH
jclouds
Uses JClouds to provide slave launching on most of the currently usable Cloud
infrastructures. Requires the Jenkins JClouds Plugin.
Parameters
• single-use (bool) -- Whether or not to terminate the slave after use
(default: False).
• instances (list) -- The name of the jclouds template to create an instance
from, and its parameters.
• cloud-name (str) -- The name of the jclouds profile containing the
specified template.
• count (int) -- How many instances to create (default: 1).
• stop-on-terminate (bool) -- Whether or not to suspend instead of terminate
the instance (default: False).
Example:
wrappers:
- jclouds:
single-use: True
instances:
- jenkins-dev-slave:
cloud-name: mycloud1
count: 1
stop-on-terminate: True
- jenkins-test-slave:
cloud-name: mycloud2
count: 2
stop-on-terminate: False
locks Control parallel execution of jobs. Requires the Jenkins Locks and Latches Plugin.
Arg list of locks to use
Example:
wrappers:
- locks:
- FOO
- FOO2
mask-passwords
Hide passwords in the console log. Requires the Jenkins Mask Passwords Plugin.
Example:
wrappers:
- mask-passwords
port-allocator
Assign unique TCP port numbers Requires the Jenkins Port Allocator Plugin.
Parameters
name (str) -- Variable name of the port or a specific port number
Example:
wrappers:
- port-allocator:
name: SERVER_PORT
release
Add release build configuration Requires the Jenkins Release Plugin.
Parameters
• keep-forever (bool) -- Keep build forever (default is 'true')
• override-build-parameters (bool) -- Enable build-parameter override
• version-template (string) -- Release version template
• parameters (list) -- Release parameters (see the Parameters module)
• pre-build (list) -- Pre-build steps (see the Builders module)
• post-build (list) -- Post-build steps (see Builders)
• post-success (list) -- Post successful-build steps (see Builders)
• post-failed (list) -- Post failed-build steps (see Builders)
Example:
wrappers:
- release:
keep-forever: false
parameters:
- string:
name: RELEASE_BRANCH
default: ''
description: Git branch to release from.
post-success:
- shell: |
#!/bin/bash
copy_build_artefacts.sh
timeout
Abort the build if it runs too long. Requires the Jenkins Build Timeout Plugin.
Parameters
• timeout (int) -- Abort the build after this number of minutes
• fail (bool) -- Mark the build as failed (default false)
Example:
wrappers:
- timeout:
timeout: 90
fail: true
timestamps
Add timestamps to the console log. Requires the Jenkins Timestamper Plugin.
Example:
wrappers:
- timestamps
workspace-cleanup (pre-build)
See Workspace Cleanup Plugin.
The post-build workspace-cleanup is available as a publisher.
Parameters
• include (list) -- list of files to be included
• exclude (list) -- list of files to be excluded
• dirmatch (bool) -- Apply pattern to directories too
Example:
wrappers:
- workspace-cleanup:
include:
- "*.zip"
Zuul
The Zuul module adds triggers that configure jobs for use with Zuul.
To change the Zuul notification URL, set a global default:
- defaults:
name: global
zuul-url: http://127.0.0.1:8001/jenkins_endpoint
The above URL is the default.
zuul Configure this job to be triggered by Zuul.
Example:
triggers:
- zuul
zuul-post
Configure this post-merge job to be triggered by Zuul.
Example:
triggers:
- zuul-post
EXTENDING
Jenkins Job Builder is quite modular. It is easy to add new attributes to existing
components, a new module to support a Jenkins plugin, or include locally defined methods
to deal with an idiosyncratic build system.
XML Processing
Most of the work of building XML from the YAML configuration file is handled by individual
functions that implement a single characteristic. For example, see the
jenkins_jobs/modules/builders.py file for the Python module that implements the standard
Jenkins builders. The shell function at the top of the file implements the standard
Execute a shell build step. All of the YAML to XML functions in Jenkins Job Builder have
the same signature:
component(parser, xml_parent, data)
Parameters
• parser (YAMLParser) -- the jenkins jobs YAML parser
• xml_parent (Element) -- this attribute's parent XML element
• data (dict) -- the YAML data structure for this attribute and below
The function is expected to examine the YAML data structure and create new XML nodes and
attach them to the xml_parent element. This general pattern is applied throughout the
included modules.
Modules
Nearly all of Jenkins Job Builder is implemented in modules. The main program has no
concept of builders, publishers, properties, or any other aspects of job definition. Each
of those building blocks is defined in a module, and due to the use of setuptools entry
points, most modules are easily extensible with new components.
To add a new module, define a class that inherits from jenkins_jobs.modules.base.Base, and
add it to the jenkins_jobs.modules entry point in your setup.py.
class jenkins_jobs.modules.base.Base(registry)
A base class for a Jenkins Job Builder Module.
The module is initialized before any YAML is parsed.
Parameters
registry (ModuleRegistry) -- the global module registry.
component_list_type = None
The component list type will be used to look up possible implementations of
the component type via entry points (entry points provide a list of
components, so it should be plural). Set both component_type and
component_list_type to None if module doesn't have components.
component_type = None
The component type for components of this module. This will be used to look
for macros (they are defined singularly, and should not be plural). Set
both component_type and component_list_type to None if module doesn't have
components.
gen_xml(parser, 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
handle_data(parser)
This method is called before any XML is generated. By overriding this
method, the module may manipulate the YAML data structure on the parser
however it likes before any XML is generated. If it has changed the data
structure at all, it must return True, otherwise, it must return False.
Parameters
parser (YAMLParser) -- the global YAML Parser
Return type
boolean
sequence = 10
The sequence number for the module. Modules are invoked in the order of
their sequence number in order to produce consistently ordered XML output.
Components
Most of the standard modules supply a number of components, and it's easy to provide your
own components for use by those modules. For instance, the Builders module provides
several builders, such as the shell builder as well as the trigger_builds builder. If you
wanted to add a new builder, all you need to do is write a function that conforms to the
Component Interface, and then add that function to the appropriate entry point (via a
setup.py file).
Module Registry
All modules and their associated components are registered in the module registry. It can
be accessed either from modules via the registry field, or via the parser parameter of
components.
class jenkins_jobs.builder.ModuleRegistry(config)
dispatch(component_type, parser, xml_parent, component, template_data={})
This is a method that you can call from your implementation of Base.gen_xml
or component. It allows modules to define a type of component, and benefit
from extensibility via Python entry points and Jenkins Job Builder Macros.
Parameters
• component_type (string) -- the name of the component (e.g.,
builder)
• parser (YAMLParser) -- the global YMAL Parser
• xml_parent (Element) -- the parent XML element
• template_data (dict) -- values that should be interpolated into the
component definition
See jenkins_jobs.modules.base.Base for how to register components of a
module.
See the Publishers module for a simple example of how to use this method.
• genindex
• modindex
• search
AUTHOR
Jenkins Job Builder Maintainers
COPYRIGHT
2012, Jenkins Job Builder Maintainers