Provided by: jenkins-job-builder_3.11.0-2_all 
NAME
jenkins-jobs - Jenkins Job Builder Documentation
Jenkins Job Builder takes simple descriptions of Jenkins jobs in YAML or JSON 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.
To install:
$ pip install --user jenkins-job-builder
Online documentation:
• https://jenkins-job-builder.readthedocs.io/en/latest/
DEVELOPERS
Bug report:
• https://storyboard.openstack.org/#!/project/723
Repository:
• https://opendev.org/jjb/jenkins-job-builder
Cloning:
git clone https://opendev.org/jjb/jenkins-job-builder.git
Install pre-commit from https://pre-commit.com/#intro in order to run some minimal testing on your
commits.
A virtual environment is recommended for development. For example, Jenkins Job Builder may be installed
from the top level directory:
$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -r test-requirements.txt -e .
Patches are submitted via Gerrit at:
• https://review.opendev.org
Please do not submit GitHub pull requests, they will be automatically closed.
Mailing list:
• https://groups.google.com/forum/#!forum/jenkins-job-builder
IRC:
• #openstack-jjb on OFTC
More details on how you can contribute is available on our wiki at:
• https://docs.openstack.org/infra/manual/developers.html
WRITING A PATCH
We ask that all code submissions be pep8 and pyflakes clean. The easiest way to do that is to run tox
before submitting code for review in Gerrit. It will run pep8 and pyflakes in the same manner as the
automated test suite that will run on proposed patchsets.
When creating new YAML components, please observe the following style conventions:
• All YAML identifiers (including component names and arguments) should be lower-case and multiple word
identifiers should use hyphens. E.g., "build-trigger".
• The Python functions that implement components should have the same name as the YAML keyword, but
should use underscores instead of hyphens. E.g., "build_trigger".
This consistency will help users avoid simple mistakes when writing YAML, as well as developers when
matching YAML components to Python implementation.
UNIT TESTS
Unit tests have been included and are in the tests folder. Many unit tests samples are included as
examples in our documentation to ensure that examples are kept current with existing behaviour. To run
the unit tests, execute the command:
tox -e py34,py27
• Note: View tox.ini to run tests on other versions of Python, generating the documentation and
additionally for any special notes on running the test to validate documentation external URLs from
behind proxies.
INSTALLING WITHOUT SETUP.PY
For YAML support, you will need libyaml installed.
Mac OS X:
$ brew install libyaml
Then install the required python packages using pip:
$ sudo pip install PyYAML python-jenkins
QUICK START GUIDE
This guide was made with the impatient in mind so explanation is sparse. It will guide users through a
set of typical use cases for JJB using the same job definitions we use to test JJB.
1. Clone the repository to get the JJB job definition examples
2. The installation can be either from pypi (released version) or from the clone (master).
Usage of the commands below assumes that you are at the root of the cloned directory.
Use Case 1: Test a job definition
JJB creates Jenkins XML configuration file from a YAML/JSON definition file and just uploads it to
Jenkins. JJB provides a convenient test command to allow you to validate the XML before you attempt to
upload it to Jenkins.
Test a YAML job definition:
jenkins-jobs test tests/yamlparser/fixtures/templates002.yaml
The above command prints the generated Jenkins XML to the console. If you prefer to send it to a
directory:
jenkins-jobs test -o output tests/yamlparser/fixtures/templates002.yaml
The output directory will contain files with the XML configurations.
Use Case 2: Updating Jenkins Jobs
Once you've tested your job definition and are happy with it then you can use the update command to
deploy the job to Jenkins. The update command requires a configuration file. An example file is
supplied in the etc folder, you should update it to match your Jenkins master:
jenkins-jobs --conf etc/jenkins_jobs.ini-sample update tests/yamlparser/fixtures/templates002.yaml
The above command will update your Jenkins master with the generated jobs.
Caution: JJB caches Jenkins job information locally. Changes made using the Jenkins UI will not update
that cache, which may lead to confusion. See updating-jobs for more information.
Use Case 3: Working with JSON job definitions
You can also define your jobs in json instead of yaml:
jenkins-jobs --conf etc/jenkins_jobs.ini-sample update tests/jsonparser/fixtures/simple.json
The above command just uses a simple job definition. You can also convert any of the YAML examples to
JSON and feed that to JJB.
Use Case 4: Deleting a job
To delete a job:
jenkins-jobs --conf etc/jenkins_jobs.ini-sample delete simple
The above command deletes the job simple from the Jenkins master.
Use Case 5: Providing plugins info
To generate a plugins info, using an account with Administrator rights:
jenkins-jobs get-plugins-info -o plugins_info.yaml
To run JJB update using the plugins_info.yaml:
jenkins-jobs update -p plugins_info.yaml ./myjobs
Please refer to the jenkins-jobs command-reference and the definition pages for more details.
INSTALLATION
To install Jenkins Job Builder from source, run:
pip install --user jenkins-job-builder
A virtual environment is recommended for development. For example, Jenkins Job Builder may be installed
from the top level directory:
$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -r test-requirements.txt -e .
Alternatively, the current release can be installed from pypi:
sudo pip install jenkins-job-builder
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.
Documentation
Documentation is included in the doc folder. To generate docs locally execute the command:
tox -e docs
The generated documentation is then available under doc/build/html/index.html.
As over time URLs change or become stale there is also a testenv available to verify any links added. To
run locally execute the command:
tox -e docs-linkcheck
• Note: When behind a proxy it is necessary to use TOX_TESTENV_PASSENV to pass any proxy settings for
this test to be able to check links are valid.
Unit Tests
Unit tests have been included and are in the tests folder. We recently started including unit tests as
examples in our documentation so to keep the examples up to date it is very important that we include
unit tests for every module. To run the unit tests, execute the command:
tox -e py27
• Note: View tox.ini to run tests on other versions of Python.
Test Coverage
To measure test coverage, execute the command:
tox -e cover
CONFIGURATION FILE
After installation, you will need to create a configuration file. By default, jenkins-jobs looks for
~/.config/jenkins_jobs/jenkins_jobs.ini, <script directory>/jenkins_jobs.ini or
/etc/jenkins_jobs/jenkins_jobs.ini (in that order), but you may specify an alternative location when
running jenkins-jobs. The file should have the following format:
[job_builder]
ignore_cache=True
keep_descriptions=False
include_path=.:scripts:~/git/
recursive=False
exclude=.*:manual:./development
allow_duplicates=False
update=all
[jenkins]
user=jenkins
password=1234567890abcdef1234567890abcdef
url=https://jenkins.example.com
query_plugins_info=False
##### This is deprecated, use job_builder section instead
#ignore_cache=True
[plugin "hipchat"]
authtoken=dummy
[plugin "stash"]
username=user
password=pass
job_builder section
ignore_cache
(Optional) If set to True, Jenkins Job Builder won't use any cache.
keep_descriptions
By default jenkins-jobs will overwrite the jobs descriptions even if no description has been
defined explicitly. When this option is set to True, that behavior changes and it will only
overwrite the description if you specified it in the yaml. False by default.
include_path
(Optional) Can be set to a ':' delimited list of paths, which jenkins job builder will search for
any files specified by the custom application yaml tags 'include', 'include-raw' and
'include-raw-escape'.
recursive
(Optional) If set to True, jenkins job builder will search for job definition files recursively.
exclude
(Optional) If set to a list of values separated by ':', these paths will be excluded from the list
of paths to be processed when searching recursively. Values containing no / will be matched
against directory names at all levels, those starting with / will be considered absolute, while
others containing a / somewhere other than the start of the value will be considered relative to
the starting path.
allow_duplicates
(Optional) By default jenkins-jobs will abort when a duplicate macro, template, job-group or job
name is encountered as it cannot establish the correct one to use. When this option is set to
True, only a warning is emitted.
allow_empty_variables
(Optional) When expanding strings, by default jenkins-jobs will raise an exception if there's a
key in the string, that has not been declared in the input YAML files. Setting this option to True
will replace it with the empty string, allowing you to use those strings without having to define
all the keys it might be using.
print_job_urls
(Optional) If set to True it will print full jobs urls while updating jobs, so user can be sure
which instance was updated. User may click the link to go directly to that job. False by default.
retain_anchors
(Optional) If set to True, YAML anchors will be retained across files, allowing jobs to be
composed from bits of YAML defined in separate files. Note this means that the order of
processing files matters - jenkins-jobs loads files in alphabetical order (all files in a dir are
loaded before any files in subdirs). For example, if your anchors are in a file named foo.yml they
will be accessible in qux.yml but not in bar.yml. They will also be accessible in mydir/bar.yml
and mydir/qux.yml. False by default.
update (Optional) If set, allows the user to specify if only "jobs" or "views" (or "all") are updated.
Users can override the setting here by passing --jobs-only or --views-only CLI options. (Valid
options: jobs, views, all)
jenkins section
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.
timeout
(Optional) The connection timeout (in seconds) to the Jenkins server. By default this is set to
the system configured socket timeout.
query_plugins_info
Whether to query the Jenkins instance for plugin info. If no configuration files are found (either
in the default paths or given through the command-line), jenkins-jobs will skip querying for
plugin information. False by default.
hipchat section
send-as
This is the hipchat user name that will be used when sending notifications.
authtoken
The API token necessary to send messages to hipchat. This can be generated in the hipchat web
interface by a user with administrative access for your organization. This authtoken is set for
each job individually; the JJB Hipchat Plugin does not currently support setting different tokens
for different projects, so the token you use will have to be scoped such that it can be used for
any room your jobs might be configured to notify. For more information on this topic, please see
the Hipchat API Documentation
stash section
username
This is the stash user name that will be used to connect to stash when using the stash publisher
plugin and not defining it in the yaml part.
password
This is the related password that will be used with the stash username when using the stash
publisher plugin and not defining it in the yaml part.
__future__ section
This section is to control enabling of beta features or behaviour changes that deviate from previously
released behaviour in ways that may require effort to convert existing JJB configs to adopt. This
essentially will act as a method to share these new behaviours while under active development so they can
be changed ahead of releases.
param_order_from_yaml
Used to switch on using the order of the parameters are defined in yaml to control the order of
corresponding XML elements being written out. This is intended as a global flag and can affect
multiple modules.
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; that is discussed in the next
section.
Test Mode
Once you have a configuration defined, you can run the job builder in test mode.
If you want to run a simple test with just a single YAML job definition file and see the XML output on
stdout:
jenkins-jobs test /path/to/foo.yaml
You can also pass JJB a directory containing multiple job definition files:
jenkins-jobs test /path/to/defs -o /path/to/output
which will write XML files to the output directory for all of the jobs defined in the defs directory.
If you run:
jenkins-jobs test /path/to/defs -o /path/to/output --config-xml
the output directory will contain config.xml files similar to the internal storage format of Jenkins.
This might allow you to more easily compare the output to an existing Jenkins installation.
Updating Jobs
When you're satisfied with the generated XML from the test, you can run:
jenkins-jobs update /path/to/defs
which will upload the job and view definitions to Jenkins if needed. Jenkins Job Builder maintains, for
each host, a cache [1] of previously configured jobs and views, so that you can run that command as often
as you like, and it will only update the jobs configurations in Jenkins if the defined definitions have
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/views, simply pass the job/view names as additional arguments after the
job definition path. To update Foo1 and Foo2 run:
jenkins-jobs update /path/to/defs Foo1 Foo2
You can also enable the parallel execution of the program passing the workers option with a value of 0,
2, or higher. Use 0 to run as many workers as cores in the host that runs it, and 2 or higher to specify
the number of workers to use:
jenkins-jobs update --workers 0 /path/to/defs
To update only views or only jobs, simply add the argument --views-only or --jobs-only after the command:
jenkins-jobs update --views-only Foo-view
jenkins-jobs update --jobs-only Foo-job
Passing Multiple Paths
It is possible to pass multiple paths to JJB using colons as a path separator on *nix systems and
semi-colons on Windows systems. For example:
jenkins-jobs test /path/to/global:/path/to/instance:/path/to/instance/project
This helps when structuring directory layouts as you may selectively include directories in different
ways to suit different needs. If you maintain multiple Jenkins instances suited to various needs you may
want to share configuration between those instances (global). Furthermore, there may be various ways you
would like to structure jobs within a given instance.
RECURSIVE SEARCHING OF PATHS
In addition to passing multiple paths to JJB it is also possible to enable recursive searching to process
all yaml files in the tree beneath each path. For example:
For a tree:
/path/
to/
defs/
ci_jobs/
release_jobs/
globals/
macros/
templates/
jenkins-jobs update -r /path/to/defs:/path/to/globals
JJB will search defs/ci_jobs, defs/release_jobs, globals/macros and globals/templates in addition to the
defs and globals trees.
EXCLUDING PATHS
To allow a complex tree of jobs where some jobs are managed differently without needing to explicitly
provide each path, the recursive path processing supports excluding paths based on absolute paths,
relative paths and patterns. For example:
For a tree:
/path/
to/
defs/
ci_jobs/
manual/
release_jobs/
manual/
qa_jobs/
globals/
macros/
templates/
special/
jenkins-jobs update -r -x man*:./qa_jobs -x /path/to/defs/globals/special \
/path/to/defs:/path/to/globals
JJB will search the given paths, ignoring the directories qa_jobs, ci_jobs/manual, release_jobs/manual,
and globals/special when building the list of yaml files to be processed. Absolute paths are denoted by
starting from the root, relative by containing the path separator, and patterns by having neither.
Patterns use simple shell globing to match directories.
Deleting Jobs/Views
Jenkins Job Builder supports deleting jobs and views from Jenkins.
To delete a specific job:
jenkins-jobs delete Foo1
To delete a list of jobs or views, simply pass them as additional arguments after the command:
jenkins-jobs delete Foo1 Foo2
To delete only views or only jobs, simply add the argument --views-only or --jobs-only after the command:
jenkins-jobs delete --views-only Foo1
jenkins-jobs delete --jobs-only Foo1
The update command includes a delete-old option to remove obsolete jobs:
jenkins-jobs update --delete-old /path/to/defs
Obsolete jobs are jobs once managed by JJB (as distinguished by a special comment that JJB appends to
their description), that were not generated in this JJB run.
There is also a command to delete all jobs and/or views. WARNING: Use with caution.
To delete all jobs and views:
jenkins-jobs delete-all
TO delete all jobs:
jenkins-jobs delete-all --jobs-only
To delete all views:
jenkins-jobs delete-all --views-only
Globbed Parameters
Jenkins job builder supports globbed parameters to identify jobs from a set of definition files. This
feature only supports JJB managed jobs.
To update jobs/views that only have 'foo' in their name:
jenkins-jobs update ./myjobs \*foo\*
To delete jobs/views that only have 'foo' in their name:
jenkins-jobs delete --path ./myjobs \*foo\*
Providing Plugins Info
With Jenkins LTS 1.651.1+ retrieving plugins info became a secure feature and now requires Administrator
rights to use [#f2]. This causes JJB to no longer be able to work in situations where a user wants to
publish jobs to Jenkins but is not able to receive the Administrator permissions. In this case we can
provide a plugins_info.yaml file containing the plugin versions data needed by JJB to parse the job
templates.
To generate a plugins info, using an account with Administrator rights:
jenkins-jobs get-plugins-info -o plugins_info.yaml
To run JJB update using the plugins_info.yaml:
jenkins-jobs update -p plugins_info.yaml ./myjobs
Command Reference
usage: jenkins-jobs [-h] [--conf CONF] [-l LOG_LEVEL] [--ignore-cache]
[--flush-cache] [--version] [--allow-empty-variables]
[--server SECTION] [--user USER] [--password PASSWORD]
{delete,delete-all,get-plugins-info,list,test,update} ...
positional arguments:
{delete,delete-all,get-plugins-info,list,test,update}
update, test, list or delete job
delete-all delete *ALL* jobs from Jenkins server, including those
not managed by Jenkins Job Builder.
get-plugins-info get plugins info yaml by querying Jenkins server.
list List jobs
optional arguments:
-h, --help show this help message and exit
--conf CONF configuration file [JJB_CONF]
-l LOG_LEVEL, --log_level LOG_LEVEL
log level (default: info) [JJB_LOG_LEVEL]
--ignore-cache ignore the cache and update the jobs anyhow (that will
only flush the specified jobs cache)
--flush-cache flush all the cache entries before updating
--version show version
--allow-empty-variables
Don't fail if any of the variables inside any string
are not defined, replace with empty string instead.
--server SECTION, -s SECTION
The Jenkins server ini section to use. Defaults to
'jenkins' [JJB_SECTION]
--user USER, -u USER The Jenkins user to use for authentication. This
overrides the user specified in the configuration
file. [JJB_USER]
--password PASSWORD, -p PASSWORD
Password or API token to use for authenticating
towards Jenkins. This overrides the password specified
in the configuration file. [JJB_PASSWORD]
usage: jenkins-jobs test [-h] [-r] [-x EXCLUDE] [--config-xml]
[-p PLUGINS_INFO_PATH] [-o OUTPUT_DIR]
[path] [names ...]
positional arguments:
path colon-separated list of paths to YAML files or
directories
names name(s) of job(s)
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
--config-xml use alternative output file layout using config.xml
files
-p PLUGINS_INFO_PATH, --plugin-info PLUGINS_INFO_PATH
path to plugin info YAML file
-o OUTPUT_DIR path to output XML
usage: jenkins-jobs update [-h] [-r] [-x EXCLUDE] [--delete-old]
[-p PLUGINS_INFO_PATH] [--workers N_WORKERS]
[--existing-only] [-j | -v]
[path] [names ...]
positional arguments:
path colon-separated list of paths to YAML files or
directories
names name(s) of job(s)
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
--delete-old delete obsolete jobs
-p PLUGINS_INFO_PATH, --plugin-info PLUGINS_INFO_PATH
path to plugin info YAML file. Can be used to provide
previously retrieved plugins info when connecting
credentials don't have permissions to query.
--workers N_WORKERS number of workers to use, 0 for autodetection and 1
for just one worker.
--existing-only update existing jobs only
-j, --jobs-only update only jobs
-v, --views-only update only views
usage: jenkins-jobs delete-all [-h] [-r] [-x EXCLUDE] [-j] [-v]
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-j, --jobs-only delete only jobs
-v, --views-only delete only views
usage: jenkins-jobs delete [-h] [-r] [-x EXCLUDE] [-p PATH] [-j] [-v]
name [name ...]
positional arguments:
name name of job
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-p PATH, --path PATH colon-separated list of paths to YAML files or
directories
-j, --jobs-only delete only jobs
-v, --views-only delete only views
usage: jenkins-jobs get-plugins-info [-h] [-o PLUGINS_INFO_FILE]
optional arguments:
-h, --help show this help message and exit
-o PLUGINS_INFO_FILE, --output-file PLUGINS_INFO_FILE
file to save output to.
FOOTNOTES
[1] The cache default location is at ~/.cache/jenkins_jobs, which can be overridden by setting the
XDG_CACHE_HOME environment variable.
[2] Jenkins Security Advisory affecting plugins info retrieval
https://www.jenkins.io/security/advisory/2016-05-11/#information-on-installed-plugins-exposed-via-api
JOB DEFINITIONS
The job definitions for Jenkins Job Builder are kept in any number of YAML or JSON 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/.yml or .json files in
that directory will be read, and all the jobs they define will be created or updated.
NOTE:
Jenkins Job Builder 2.x plugins are designed to default to generating the xml format for the latest
supported version of JJB. This is a change in behaviour from 1.x and below which defaulted to the
oldest supported plugin version.
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.
These are job parameters that are common to every type of Jenkins job.
Example:
- job:
name: job-name
project-type: freestyle
defaults: global
description: 'Do not edit this job through the web!'
disabled: false
display-name: 'Fancy job name'
concurrent: true
workspace: /srv/build-area/job-name
quiet-period: 5
block-downstream: false
block-upstream: false
retry-count: 3
node: NodeLabel1 || NodeLabel2
logrotate:
daysToKeep: 3
numToKeep: 20
artifactDaysToKeep: -1
artifactNumToKeep: -1
Job Parameters
• project-type: Defaults to "freestyle", but "maven" as well as "multijob", "flow", "pipeline" or
"externaljob" 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.
• description: The description for the job. By default, the description "!-- Managed by Jenkins
Job Builder" is applied.
• disabled: Boolean value to set whether or not this job should be disabled in Jenkins. Defaults
to false (job will be enabled).
• display-name: Optional name shown for the project throughout the Jenkins web GUI in place of the
actual job name. The jenkins_jobs tool cannot fully remove this trait once it is set, so use
caution when setting it. Setting it to the same string as the job's name is an effective un-set
workaround. Alternately, the field can be cleared manually using the Jenkins web interface.
• 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.
• folder: The folder attribute provides an alternative to using '<path>/<name>' as the job name to
specify which Jenkins folder to upload the job to.
Requires the Jenkins CloudBees Folders Plugin.
• child-workspace: Path for a child custom workspace. Defaults to Jenkins default configuration.
This parameter is only valid for matrix type jobs.
• 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.
• retry-count: If a build fails to checkout from the repository, Jenkins will retry the specified
number of times before giving up.
• node: Restrict where this job can be run. If there is a group of machines that the job can be
built on, you can specify that label as the node to tie on, which will cause Jenkins to build
the job on any of the machines with that label. For matrix projects, this parameter will only
restrict where the parent job will run.
• logrotate: The Logrotate section allows you to automatically remove old build history. It adds
the logrotate attribute to the Job definition. All logrotate attributes default to "-1" (keep
forever). Deprecated on jenkins >=1.637: use the build-discarder property instead
• jdk: The name of the jdk to use
• raw: If present, this section should contain a single xml entry. This XML will be inserted at
the top-level of the Job definition.
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. Any variables not specified at the project level
will be inherited from the Defaults.
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. In the rare situation that you must encode braces within literals inside a template (for
example a shell function definition in a builder), doubling the braces will prevent them from being
interpreted as a template variable.
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.
If you use the variable {template-name}, the name of the template itself (e.g. {name}-unit-tests in the
above example) will be substituted in. This is useful in cases where you need to trace a job back to its
template.
Sometimes it is useful to have the same job name format used even where the template contents may vary.
Ids provide a mechanism to support such use cases in addition to simplifying referencing templates when
the name contains the more complex substitution with default values.
Default Values for Template Variables
To facilitate reuse of templates with many variables that can be substituted, but where in most cases the
same or no value is needed, it is possible to specify defaults for the variables within the templates
themselves.
There are 2 ways JJB allows us to define defaults for a parameter in a job-template.
1. Defining the default variable value in the job-template itself
With this method we declare the default value of the variable in the job-template itself just once. We
can section off the job-template into two sections like this:
- job-template:
name: '{project-name}-verify'
#####################
# Variable Defaults #
#####################
branch: master
#####################
# Job Configuration #
#####################
parameters:
- string:
name: BRANCH
default: '{branch}'
scm:
- git:
refspec: 'refs/heads/{branch}'
In this case there is still two branch definitions for the job-template. However we also provide the
default value for the {branch} variable at the top of the file. Just once. This will be the value that
the job takes on if it is not passed in by a project using the template.
2. Using {var|default}
In this method we can define the default with the definition of the variable. For example:
- job-template:
name: '{project-name}-verify'
parameters:
- string:
name: BRANCH
default: '{branch|master}'
However where this method falls apart if we need to use the same JJB variable in more than one place
as we will have multiple places to define the default value for the template. For example:
- job-template:
name: '{project-name}-verify'
parameters:
- string:
name: BRANCH
default: '{branch|master}'
scm:
- git:
refspec: 'refs/heads/{branch|master}'
We can see in this case the {branch|master} variable is defined in two places. Not ideal.
More complex example:
- project:
name: template_variable_defaults
jobs:
- 'template-variable-defaults-{num}':
num: 1
disabled_var: true
- 'template-variable-defaults-{num}':
test_var: Goodbye World
num: 2
- job-template:
# template specific defaults
# empty value causes disabled_var to be ignored internally
disabled_var:
test_var: Hello World
type: periodic
# template settings
name: 'template-variable-defaults-{num}-{type}'
id: 'template-variable-defaults-{num}'
disabled: '{obj:disabled_var}'
builders:
- shell: |
echo "Job Name: template-variable-defaults-{num}-{type}"
echo "Variable: {test_var}"
To use a default value for a variable used in the name would be uncommon unless it was in addition to
another variable. However you can use Ids simplify such use cases.
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}'
If there are templates being realized that differ only in the variable used for its name (thus not a use
case for job-specific substitutions), additional variables can be specified for project variables.
Example:
- job-template:
name: '{name}-{pyver}'
builders:
- shell: 'git co {branch_name}'
- project:
name: project-name
pyver:
- 26:
branch_name: old_branch
- 27:
branch_name: new_branch
jobs:
- '{name}-{pyver}'
You can also specify some variable combinations to exclude from the matrix with the exclude keyword, to
avoid generating jobs for those combinations. You can specify all the variables of the combination or
only a subset, if you specify a subset, any value of the omited variable will match:
- project:
name: project-name
axe1:
- axe1val1
- axe1val2
axe2:
- axe2val1
- axe2val2
axe3:
- axe3val1
- axe3val2
exclude:
- axe1: axe1val1
axe2: axe2val1
axe3: axe3val2
- axe2: axe2val2
axe3: axe3val1
jobs:
- build-{axe1}-{axe2}-{axe3}
- job-template:
name: build-{axe1}-{axe2}-{axe3}
builders:
- shell: "echo Combination {axe1}:{axe2}:{axe3}"
The above example will omit the jobs:
• build-axe1val1-axe2val1-axe3val2
• build-axe1val1-axe2val2-axe3val1
• build-axe1val2-axe2val2-axe3val1
To achieve the same without the exclude tag one would have to do something a bit more complicated, that
gets more complicated for each dimension in the combination, for the previous example, the counterpart
would be:
- project:
name: project-name_comb1
axe1:
- axe1val1
- axe1val2
axe2: axe2val1
axe3: axe3val1
jobs:
- build-{axe1}-{axe2}-{axe3}
- project:
name: project-name_comb2
axe1:
- axe1val1
- axe1val2
axe2: axe2val2
axe3: axe3val2
jobs:
- build-{axe1}-{axe2}-{axe3}
- project:
name: project-name_comb3
axe1: axe1val2
axe2: axe2val1
axe3: axe3val2
jobs:
- build-{axe1}-{axe2}-{axe3}
- job-template:
name: build-{axe1}-{axe2}-{axe3}
builders:
- shell: "echo Combination {axe1}:{axe2}:{axe3}"
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}-unit-tests'
builders:
- shell: unittest
publishers:
- email:
recipients: '{mail-to}'
- job-template:
name: '{name}-perf-tests'
builders:
- shell: perftest
publishers:
- email:
recipients: '{mail-to}'
- job-group:
name: '{name}-tests'
jobs:
- '{name}-unit-tests':
mail-to: developer@nowhere.net
- '{name}-perf-tests':
mail-to: projmanager@nowhere.net
- project:
name: project-name
jobs:
- '{name}-tests'
Would cause the jobs project-name-unit-tests and project-name-perf-tests to be created in Jenkins.
Views
A view is a particular way of displaying a specific set of jobs. To create a view, you must define a view
in a YAML file and have a variable called view-type with a valid value. It looks like this:
- view:
name: view-name
view-type: list
Views are processed differently than Jobs and therefore will not work within a Project or a Job Template.
View Template
Allow views to also be configured via templates similar to job-templates. This is useful when you have
multiple views defined that have similar configuration except for a few variables. View Templates can be
passed variables to fill in sections automatically via a project configuration using the new 'views' key.
Minimal Example:
- view-template:
name: '{name}-template-{seq}'
description: 'testing view templates feature'
view-type: list
regex: 'test-view-.*'
- project:
name: 'test-view'
views:
- '{name}-template-{seq}'
seq:
- a
- b
- c
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.
Macro Notes
If a macro is not passed any parameters it will not have any expansion performed on it. Thus if you
forget to provide any parameters to a macro that expects some, the parameter-templates ({foo}) will be
left as is in the resulting output; this is almost certainly not what you want. Note if you provide an
invalid parameter, the expansion will fail; the expansion will only be skipped if you provide no
parameters at all.
Macros are expanded using Python string substitution rules. This can especially cause confusion with
shell snippets that use { as part of their syntax. As described, if a macro has no parameters, no
expansion will be performed and thus it is correct to write the script with no escaping, e.g.:
- builder:
name: a_builder
builders:
- shell: |
VARIABLE=${VARIABLE:-bar}
function foo {
echo "my shell function"
}
However, if the macro has parameters, you must escape the { you wish to make it through to the output,
e.g.:
- builder:
name: a_builder
builders:
- shell: |
PARAMETER={parameter}
VARIABLE=${{VARIABLE:-bar}}
function foo {{
echo "my shell function"
}}
Note that a job-template will have parameters by definition (at least a name). Thus embedded-shell
within a job-template should always use {{ to achieve a literal {. A generic builder will need to
consider the correct quoting based on its use of parameters.
Folders
Jenkins supports organising jobs, views, and slaves using a folder hierarchy. This allows for easier
separation of access as well credentials and resources which can be assigned to only be available for a
specific folder.
JJB has two methods of supporting uploading jobs to a specific folder:
• Name the job to contain the desired folder <folder>/my-job-name
• Use the folder attribute on a job definition, via a template, or through Defaults.
Supporting both an attributed and use of it directly in job names allows for teams to have all jobs using
their defaults automatically use a top-level folder, while still allowing for them to additionally nest
jobs for their own preferences.
Job Name Example:
- job:
name: python-jobs/tox-py27
builders:
- shell: |
tox -e py27
Folder Attribute Example:
- defaults:
name: team1
folder: team1-jobs
- job:
name: ruby-jobs/rspec
defaults: team1
builders:
- shell: |
rvm use --create ruby-2.3.0@rspec
bundle install
bundle exec rspec
Item ID's
It's possible to assign an id to any of the blocks and then use that to reference it instead of the name.
This has two primary functions:
• A unique identifier where you wish to use the same naming format for multiple templates. This allows
you to follow a naming scheme while still using multiple templates to handle subtle variables in job
requirements.
• Provides a simpler name for a job-template where you have multiple variables including default values
in the name and don't wish to have to include this information in every use. This also makes changing
the template output name without impacting references.
Example:
- project:
name: test_template_id
jobs:
- 'simple-template':
test_var: Hello World
type: periodic
num: 1
- 'not-as-simple-template':
test_var: Goodbye World
type: canary
num: 2
- job-template:
name: 'template-test-ids-{num}-{type}'
id: simple-template
builders:
- shell: |
echo "Template name: {template-name}"
echo "Job name: template-test-ids-{num}-{type}"
echo "{test_var}"
- job-template:
name: 'template-test-ids-{num}-{type}'
id: not-as-simple-template
builders:
- shell: |
echo "Template name: {template-name}"
echo "Job name: template-test-ids-{num}-{type}"
- shell: |
echo "{test_var}"
Raw config
It is possible, but not recommended, to use raw within a module to inject raw xml into the job configs.
This is relevant in case there is no appropriate module for a Jenkins plugin or the module does not
behave as you expect it to do.
For example:
wrappers:
- raw:
xml: |
<hudson.plugins.xvnc.Xvnc>
<takeScreenshot>true</takeScreenshot>
<useXauthority>false</useXauthority>
</hudson.plugins.xvnc.Xvnc>
Is the raw way of adding support for the xvnc wrapper.
To get the appropriate xml to use you would need to create/edit a job in Jenkins and grab the relevant
raw xml segment from the config.xml.
The xml string can refer to variables just like anything else and as such can be parameterized like
anything else.
You can use raw in most locations, the following example show them with arbitrary xml-data:
- project:
name: complete002
version:
- 1.2
jobs:
- 'complete001_{version}'
- job-template:
name: 'complete001_{version}'
project-type: maven
scm:
- raw:
xml: |
<!-- <scm> for raw replaces the whole scm section.
where as for others the raw part is added to the existing.
-->
<scm>
<scmraw/>
</scm>
triggers:
- raw:
xml: |
<triggersraw/>
wrappers:
- raw:
xml: |
<wrappersraw/>
builders:
- raw:
xml: |
<buildersraw/>
publishers:
- raw:
xml: |
<publishersraw/>
properties:
- raw:
xml: |
<propertiesraw/>
parameters:
- raw:
xml: |
<parametersraw/>
notifications:
- raw:
xml: |
<metadataraw/>
reporters:
- raw:
xml:
<reportersraw/>
Note: If you have a need to use raw please consider submitting a patch to add or fix the module that will
remove your need to use raw.
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.
You can define variables that will be realized in a Job Template.
- defaults:
name: global
arch: 'i386'
- project:
name: project-name
jobs:
- 'build-{arch}'
- 'build-{arch}':
arch: 'amd64'
- job-template:
name: 'build-{arch}'
builders:
- shell: "echo Build arch {arch}."
Would create jobs build-i386 and build-amd64.
You can also reference a variable {template-name} in any value and it will be subtitued by the name of
the current job template being processed.
Variable References
If you want to pass an object (boolean, list or dict) to templates you can use an {obj:key} variable in
the job template. This triggers the use of code that retains the original object type.
For example:
- project:
name: test_custom_distri
disabled: true
distributions: !!python/tuple [precise, jessie]
architectures: !!python/tuple &architectures
- amd64
- i386
axis_a:
type: user-defined
name: architectures
values: *architectures
jobs:
- '{name}-source'
- job-template:
name: '{name}-source'
project-type: matrix
disabled: '{obj:disabled}'
axes:
- axis:
type: user-defined
name: distribution
values: '{obj:distributions}'
- axis: '{obj:axis_a}'
JJB also supports interpolation of parameters within parameters. This allows a little more flexibility
when ordering template jobs as components in different projects and job groups.
For example:
- job-template:
name: '{value-stream}_{project-id}_foo'
display-name: '{value-stream} {project-id} foo'
publishers:
- trigger-parameterized-builds:
- project: '{downstream}'
current-parameters: False
condition: ALWAYS
git-revision: True
- job-template:
name: '{value-stream}_{project-id}_bar'
display-name: '{value-stream} {project-id} bar'
publishers:
- trigger-parameterized-builds:
- project: '{downstream}'
current-parameters: False
condition: ALWAYS
git-revision: True
- job-group:
name: 'pipeline2'
project-id: 'p2'
jobs:
- '{value-stream}_{project-id}_foo':
downstream: '{value-stream}_{project-id}_bar'
- '{value-stream}_{project-id}_bar':
- job-group:
name: 'pipeline1'
project-id: 'p1'
jobs:
- '{value-stream}_{project-id}_bar':
downstream: '{value-stream}_{project-id}_foo'
- '{value-stream}_{project-id}_foo':
- project:
name: derp
jobs:
- 'pipeline1':
value-stream: 'production'
- 'pipeline2':
value-stream: 'experimental'
- defaults:
name: 'global'
downstream: ''
By default JJB will fail if it tries to interpolate a variable that was not defined, but you can change
that behavior and allow empty variables with the allow_empty_variables configuration option.
For example, having a configuration file with that option enabled:
[job_builder]
allow_empty_variables = True
Will prevent JJb from failing if there are any non-initialized variables used and replace them with the
empty string instead.
TIP:
Refer to Default Values for Template Variables for details on setting variable defaults.
Variable Inheritance
It is possible in JJB to define defaults for variables at different levels such that it is possible for
users of job-templates to override variables defined in the job-template.
Variable priorities for each definition type are as follows:
1. job-group
2. project
3. job-template
4. defaults
From this list we can immediately see that if we want to make variables in job-templates override-able
then using defaults configuration is useless as it has the lowest precedence when JJB is deciding where
to pull from.
On the other side of the spectrum, job-groups has the highest precedence. Which unfortunately means if we
define a variable in a job-group with the intention of overriding it at the project level then we are out
of luck. For this reason avoid setting variables in job-groups unless we want to enforce a setting for a
set of jobs and prevent projects from overriding it.
Declaring variable defaults
Refer to Default Values for Template Variables for details on how to declare variable defaults.
Overriding job-template variables
When a project wants to use a job-template it can use override it as follows:
- project:
name: foo
jobs:
- '{project-name}-merge'
- '{project-name}-verify'
branch: master
This is the standard way that most folks use and it will set branch: master for every job-template in the
list. However sometimes we may want to provide an alternative value for a specific job in the list. In
this case the more specific declaration takes precedence:
- project:
name: foo
jobs:
- '{project-name}-merge':
branch: production
- '{project-name}-verify'
branch: master
In this case the verify job will get the value master but the merge job will instead get the branch value
production.
Yaml Anchors & Aliases
The yaml specification supports anchors and aliases which means that JJB definitions allow references to
variables in templates.
For example:
- wrapper_defaults: &wrapper_defaults
name: 'wrapper_defaults'
wrappers:
- timeout:
timeout: 180
fail: true
- timestamps
- job_defaults: &job_defaults
name: 'defaults'
<<: *wrapper_defaults
- job-template:
name: 'myjob'
<<: *job_defaults
- project:
name: myproject
jobs:
- myjob
The anchors and aliases are expanded internally within JJB's yaml loading calls and are not limited to
individual documents. That means you can't use the same anchor name in included files without collisions.
A simple example can be seen in the specs full length example with the following being more
representative of usage within JJB:
- wrapper_defaults: &wrapper_defaults
name: 'wrapper_defaults'
wrappers:
- timeout:
timeout: 180
fail: true
- timestamps
- job_defaults: &job_defaults
name: 'defaults'
<<: *wrapper_defaults
- job-template:
name: 'myjob'
<<: *job_defaults
Which will be expanded to the following yaml before being processed:
- wrapper_defaults:
name: wrapper_defaults
wrappers:
- timeout:
fail: true
timeout: 180
- timestamps
- job_defaults:
name: defaults
wrappers:
- timeout:
fail: true
timeout: 180
- timestamps
- job-template:
name: myjob
wrappers:
- timeout:
fail: true
timeout: 180
- timestamps
Custom Yaml Tags
Custom application specific yamls tags are supported to provide enhancements when reading yaml
configuration.
Action Tags
These allow manipulation of data being stored in one layout in the source yaml for convenience and/or
clarity, to another format to be processed by the targeted module instead of requiring all modules in JJB
being capable of supporting multiple input formats.
The tag !join: will treat the first element of the following list as the delimiter to use, when joining
the remaining elements into a string and returning a single string to be consumed by the specified module
option.
This allows users to maintain elements of data in a list structure for ease of review/maintenance, and
have the yaml parser convert it to a string for consumption as any argument for modules. The main
expected use case is to allow for generic plugin data such as shell properties to be populated from a
list construct which the yaml parser converts to a single string, instead of trying to support this
within the module code which would require a templating engine similar to Jinja.
Generic Example:
- string-with-comma: !join:
- ','
-
- item1
- item2
- item3
- string-with-space: !join:
- ' '
-
- item1
- item2
- item3
Environment Inject:
- project:
name: string_join_example
jobs:
- 'string-join-data-{name}':
name: set1
files: !join:
- ','
-
- /path/to/file1
- /path/to/file2
- /path/to/file3
- /path/to/file4
- /path/to/file5
- /path/to/file6
- /path/to/file7
- /path/to/file8
- /path/to/file9
- /path/to/file10
- /path/to/file11
- /path/to/file12
- /path/to/file13
- /path/to/file14
- /path/to/file15
- /path/to/file16
- /path/to/file17
- /path/to/file18
- /path/to/file19
- /path/to/file20
- 'string-join-data-{name}':
name: set2
files: !join:
- ','
-
- /another/different/path/to/file1
- /another/different/path/to/file2
- /another/different/path/to/file3
- /another/different/path/to/file4
- /another/different/path/to/file5
- /another/different/path/to/file6
- /another/different/path/to/file7
- /another/different/path/to/file8
- /another/different/path/to/file9
- /another/different/path/to/file10
- /another/different/path/to/file11
- /another/different/path/to/file12
- /another/different/path/to/file13
- /another/different/path/to/file14
- /another/different/path/to/file15
- /another/different/path/to/file16
- /another/different/path/to/file17
- /another/different/path/to/file18
- /another/different/path/to/file19
- /another/different/path/to/file20
- job-template:
name: 'string-join-data-{name}'
properties:
- inject:
keep-system-variables: true
properties-content: |
FILE_LIST={files}
builders:
- shell: |
echo "Template name: {template-name}"
echo "Data to be processed:"
echo "${{INPUT_DATA}}"
While this mechanism can also be used items where delimiters are supported by the module, that should be
considered a bug that the existing code doesn't handle being provided a list and delimiter to perform the
correct conversion for you. Should you discover a module that takes arguments with delimiters and the
existing JJB codebase does not handle accepting lists, then this can be used as a temporary solution in
place of using very long strings:
Extended Params Example:
parameters:
- extended-choice:
name: OPTIONS_VALUE
description: "Available options"
property-key: key
quote-value: true
type: multi-select
value: "foo|bar|select"
visible-items: 2
multi-select-delimiter: '|'
default-value: foo
default-property-key: fookey
- extended-choice:
name: OPTIONS_FILE
description: "Available options"
property-file: /home/foo/property.prop
property-key: key
quote-value: true
type: multi-select
visible-items: 2
multi-select-delimiter: '|'
default-property-file: /home/property.prop
default-property-key: fookey
- extended-choice:
name: OPTIONS_CHECKBOX
type: checkbox
value: !join:
- ','
-
- OptionA
- OptionB
- OptionC
visible-items: 2
- extended-choice:
name: MULTISELECTOPTIONS
description: "Available options"
property-key: key
quote-value: true
type: multi-select
value: !join:
- '|'
-
- foo
- bar
- select
visible-items: 2
multi-select-delimiter: '|'
default-value: foo
- extended-choice:
name: JSON
type: json
groovy-script: >-
import net.sf.json.JSONObject;
def jsonEditorOptions = JSONObject.fromObject(/{schema:
{"type": "object", "title": "Name", "properties":
{"name": {"type": "string", "propertyOrder" : 1}}}}/);
- extended-choice:
name: MULTILEVELMULTISELECT
type: multi-level-multi-select
value: !join:
- ','
-
- foo
- bar
- baz
- extended-choice:
name: MULTILEVELSINGLESELECT
type: multi-level-single-select
value: foo
Inclusion Tags
These allow inclusion of arbitrary files as a method of having blocks of data managed separately to the
yaml job configurations. A specific usage of this is inlining scripts contained in separate files,
although such tags may also be used to simplify usage of macros or job templates.
The tag !include: will treat the following string as file which should be parsed as yaml configuration
data.
Example:
- job:
name: test-job-1
builders:
!include: include001.yaml.inc
contents of include001.yaml.inc:
- timeout-wrapper
- pre-scm-shell-ant
- copy-files
The tag !include-raw: will treat the given string or list of strings as filenames to be opened as one or
more data blob, which should be read into the calling yaml construct without any further parsing. Any
data in a file included through this tag, will be treated as string data.
Examples:
- job:
name: test-job-include-raw-1
builders:
- shell:
!include-raw: include-raw001-hello-world.sh
- shell:
!include-raw: include-raw001-vars.sh
contents of include-raw001-hello-world.sh:
#!/bin/bash
#
# Sample script showing how the yaml include-raw tag can be used
# to inline scripts that are maintained outside of the jenkins
# job yaml configuration.
echo "hello world"
exit 0
contents of include-raw001-vars.sh:
#!/bin/bash
#
# sample script to check that brackets aren't escaped
# when using the include-raw application yaml tag
VAR1="hello"
VAR2="world"
VAR3="${VAR1} ${VAR2}"
[[ -n "${VAR3}" ]] && {
# this next section is executed as one
echo "${VAR3}"
exit 0
}
using a list of files:
- job:
name: test-job-include-raw-1
builders:
- shell:
!include-raw:
- include-raw001-hello-world.sh
- include-raw001-vars.sh
The tag !include-raw-escape: treats the given string or list of strings as filenames to be opened as one
or more data blobs, which should be escaped before being read in as string data. This allows
job-templates to use this tag to include scripts from files without needing to escape braces in the
original file.
WARNING:
When used as a macro !include-raw-escape: should only be used if parameters are passed into the
escaped file and you would like to escape those parameters. If the file does not have any jjb
parameters passed into it then !include-raw: should be used instead otherwise you will run into an
interesting issue where include-raw-escape: actually adds additional curly braces around existing
curly braces. For example ${PROJECT} becomes ${{PROJECT}} which may break bash scripts.
Examples:
- job-template:
name: test-job-include-raw-{num}
builders:
- shell:
!include-raw-escape: include-raw001-hello-world.sh
- shell:
!include-raw-escape: include-raw001-vars.sh
- project:
name: test-job-template-1
num: 1
jobs:
- 'test-job-include-raw-{num}'
contents of include-raw001-hello-world.sh:
#!/bin/bash
#
# Sample script showing how the yaml include-raw tag can be used
# to inline scripts that are maintained outside of the jenkins
# job yaml configuration.
echo "hello world"
exit 0
contents of include-raw001-vars.sh:
#!/bin/bash
#
# sample script to check that brackets aren't escaped
# when using the include-raw application yaml tag
VAR1="hello"
VAR2="world"
VAR3="${VAR1} ${VAR2}"
[[ -n "${VAR3}" ]] && {
# this next section is executed as one
echo "${VAR3}"
exit 0
}
using a list of files:
- job-template:
name: test-job-include-raw-{num}
builders:
- shell:
!include-raw-escape:
- include-raw001-hello-world.sh
- include-raw001-vars.sh
- project:
name: test-job-template-1
num: 1
jobs:
- 'test-job-include-raw-{num}'
For all the multi file includes, the files are simply appended using a newline character.
To allow for job templates to perform substitution on the path names, when a filename containing a python
format placeholder is encountered, lazy loading support is enabled, where instead of returning the
contents back during yaml parsing, it is delayed until the variable substitution is performed.
Example:
- wrapper:
!include: lazy-load-jobs-timeout.yaml.inc
- project:
name: test
version:
- 1.1
jobs:
- 'build_myproject_{version}'
- job-template:
name: 'build_myproject_{version}'
wrappers:
!include: lazy-load-wrappers-{version}.yaml.inc
builders:
- shell:
!include-raw: echo_vars_{version}.sh
using a list of files:
- wrapper:
!include: lazy-load-jobs-timeout.yaml.inc
- project:
name: test
num: "002"
version:
- 1.1
jobs:
- 'build_myproject_{version}'
- job-template:
name: 'build_myproject_{version}'
wrappers:
!include: lazy-load-wrappers-{version}.yaml.inc
builders:
- shell:
!include-raw:
- lazy-load-scripts/echo_vars_{version}.sh
- include-raw{num}-cool.sh
NOTE:
Because lazy-loading involves performing the substitution on the file name, it means that
jenkins-job-builder can not call the variable substitution on the contents of the file. This means
that the !include-raw: tag will behave as though !include-raw-escape: tag was used instead whenever
name substitution on the filename is to be performed.
Given the behaviour described above, when substitution is to be performed on any filename passed via
!include-raw-escape: the tag will be automatically converted to !include-raw: and no escaping will be
performed.
The tag !include-jinja2: will treat the given string or list of strings as filenames to be opened as
Jinja2 templates, which should be rendered to a string and included in the calling YAML construct. (This
is analogous to the templating that will happen with !include-raw.)
Examples:
- builder:
name: test-builder
builders:
- shell:
!include-jinja2: jinja01.yaml.inc
- job:
name: test-job
builders:
- test-builder:
var: "test variable"
test_list:
- a
- b
- c
contents of jinja01.yaml.inc:
{{ var }}
{% for item in test_list -%}
{{ item }}
{% endfor %}
The tag !j2: takes a string and treats it as a Jinja2 template. It will be rendered (with the variables
in that context) and included in the calling YAML construct.
Examples:
- builder:
name: test-builder
builders:
- shell:
!j2: |
{{ var }}
{% for item in test_list -%}
{{ item }}
{% endfor %}
- job:
name: test-job
builders:
- test-builder:
var: "test variable"
test_list:
- a
- b
- c
The tag !j2-yaml: is similar to the !j2: tag, just that it loads the Jinja-rendered string as YAML and
embeds it in the calling YAML construct. This provides a very flexible and convenient way of generating
pieces of YAML structures. One of use cases is defining complex YAML structures with much simpler
configuration, without any duplication.
Examples:
- job-template:
name: test-job-template
triggers:
- gerrit:
projects:
!j2-yaml: |
{% for item in triggers %}
- branches:
- branch-compare-type: PLAIN
branch-pattern: '{{ item.branch }}'
project-compare-type: REG_EXP
project-pattern: '{{ item.repositories|join("|") }}'
{% endfor %}
- project:
name: test-job-project
jobs:
- test-job-template:
triggers:
- repositories:
- a
- b
- c
branch: master
- repositories:
- d
- e
- f
branch: stable
Another use case is controlling lists dynamically, like conditionally adding list elements based on
project configuration.
Examples:
- job-template:
name: 'test-job-{variant}'
properties: !j2-yaml: |
- rebuild
{% if discard_old_builds|default %}
- build-discarder:
days-to-keep: 7
{% endif %}
- project:
name: test-project
jobs:
- 'test-job-{variant}':
variant: abc
- 'test-job-{variant}':
variant: def
discard_old_builds: true
Modules
The bulk of the job definitions come from the following modules.
ExternalJob Project
The External Job Project module handles creating ExternalJob Jenkins projects. You may specify
externaljob in the project-type attribute of the Job definition.
This type of job allows you to record the execution of a process run outside Jenkins, even on a remote
machine. This is designed so that you can use Jenkins as a dashboard of your existing automation system.
Requires the Jenkins External Monitor Job Type Plugin.
Example:
name: openstack-infra
project-type: externaljob
class project_externaljob.ExternalJob(registry)
Flow Project
The flow Project module handles creating Jenkins flow projects. You may specify flow in the project-type
attribute of the Job definition.
Requires the Jenkins Build Flow Plugin.
In order to use it for job-template you have to escape the curly braces by doubling them in the DSL: { ->
{{ , otherwise it will be interpreted by the python str.format() command.
Job Parameters
• dsl (str): The DSL content. (optional)
• needs-workspace (bool): This build needs a workspace. (default false)
• dsl-file (str): Path to the DSL script in the workspace. Has effect only when
needs-workspace is true. (optional)
Job example:
- job:
name: test_job
project-type: flow
dsl: |
build("job1")
parallel (
{ build("job2a") },
{ build("job2b") }
)
Job template example:
- job-template:
name: '{name}-unit-tests'
project-type: flow
dsl: |
build("job1")
parallel (
{{ build("job2a") }},
{{ build("job2b") }}
)
build("job2c")
builders:
- shell: unittest
publishers:
- email:
recipients: '{mail-to}'
- job-group:
name: '{name}-tests'
jobs:
- '{name}-unit-tests':
mail-to: developer@nowhere.net
- project:
name: project-name
jobs:
- '{name}-tests'
Job example runninng a DSL file from the workspace:
- job:
name: test_job
project-type: flow
needs-workspace: true
dsl-file: script.groovy
class project_flow.Flow(registry)
Folder Project
The folder Project module handles creating Jenkins folder projects. You may specify folder in the
project-type attribute of the Job definition.
Requires the Jenkins CloudBees Folders Plugin.
Job example:
- job:
name: folder_test
project-type: folder
Job template example:
- job-template:
name: 'folder-{name}'
project-type: folder
- project:
name: test
jobs:
- 'folder-{name}'
class project_folder.Folder(registry)
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
class project_freestyle.Freestyle(registry)
GitHub Organization Project
The Github Organization project module handles creating Jenkins Github Organization jobs, which are made
up of multibranch pipelines for all repositories containing the specified Jenkinsfile(s). You may
specify githuborg in the project-type attribute of the Job definition.
Plugins required:
• GitHub Branch Source Plugin
Job Parameters
• github-org (dict): Refer to github_org for documentation.
• periodic-folder-trigger (str): How often to scan for new branches or pull/change requests. Valid
values: 1m, 2m, 5m, 10m, 15m, 20m, 25m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 2d, 1w, 2w, 4w. (default
none)
• prune-dead-branches (bool): If dead branches upon check should result in their job being
dropped. (default true)
• number-to-keep (int): How many builds should be kept. (default '-1, all')
• days-to-keep (int): For how many days should a build be kept. (default '-1, forever')
• script-path (str): Path to Jenkinsfile, relative to workspace. (default 'Jenkinsfile')
Job examples:
name: github-org-minimal
project-type: githuborg
project: example-project
github-org:
repo-owner: example-owner
name: githuborg-job-full
project-type: githuborg
project: example-project
periodic-folder-trigger: 2h
prune-dead-branches: false
number-to-keep: 10
days-to-keep: 90
script-path: some.Jenkinsfile
github-org:
repo-owner: example-owner
class project_githuborg.GithubOrganization(registry)
project_githuborg.github_org(xml_parent, data)
Configure GitHub Organization and SCM settings.
Parameters
• repo-owner (str) -- Specify the name of the GitHub Organization or GitHub User Account.
(required)
• api-uri (str) -- The GitHub API uri for hosted / on-site GitHub. Must first be configured
in Global Configuration. (default GitHub)
• branch-discovery (str) -- Discovers branches on the repository. Valid options: no-pr,
only-pr, all, false. (default 'no-pr')
• build-strategies (list) -- Provides control over whether to build a branch (or branch
like things such as change requests and tags) whenever it is discovered initially or a
change from the previous revision has been detected. (optional) Refer to
~build_strategies.
• credentials-id (str) -- Credentials used to scan branches and pull requests, check out
sources and mark commit statuses. (optional)
• discover-pr-forks-strategy (str) -- Fork strategy. Valid options: merge-current, current,
both, false. (default 'merge-current')
• discover-pr-forks-trust (str) -- Discovers pull requests where the origin repository is a
fork of the target repository. Valid options: contributors, everyone, permission or
nobody. (default 'contributors')
• discover-pr-origin (str) -- Discovers pull requests where the origin repository is the
same as the target repository. Valid options: merge-current, current, both, false.
(default 'merge-current')
• discover-tags (bool) -- Discovers tags on the repository. (default false)
• head-pr-filter-behaviors (list) -- Definition of Filter Branch PR behaviors. Requires
the SCM Filter Branch PR Plugin. Refer to ~add_filter_branch_pr_behaviors.
• notification-context (str) -- Change the default GitHub check notification context from
"continuous-integration/jenkins/SUFFIX" to a custom text, Requires the Github Custom
Notification Context SCM Behaviour.
• property-strategies (dict) -- Provides control over how to build a branch (like to
disable SCM triggering or to override the pipeline durability) (optional) Refer to
~property_strategies.
• ssh-checkout (bool) --
Checkout over SSH.
•
credentials ('str'): Credentials to use for
checkout of the repo over ssh.
Extensions
•
clean (dict)
• after (bool) - Clean the workspace after checkout
• before (bool) - Clean the workspace before checkout
• depth (int) - Set shallow clone depth (default 1)
•
disable-pr-notifications (bool) - Disable default github status
notifications on pull requests (default false) (Requires the GitHub Branch Source
Plugin.)
•
do-not-fetch-tags (bool) - Perform a clone without tags
(default false)
•
lfs-pull (bool) - Call git lfs pull after checkout
(default false)
• prune (bool) - Prune remote branches (default false)
• refspecs (list(str)): Which refspecs to fetch.
• shallow-clone (bool) - Perform shallow clone (default false)
•
sparse-checkout (dict)
• paths (list) - List of paths to sparse checkout. (optional)
•
submodule (dict)
• disable (bool) - By disabling support for submodules you can still keep using
basic git plugin functionality and just have Jenkins to ignore submodules
completely as if they didn't exist.
• recursive (bool) - Retrieve all submodules recursively (uses '--recursive'
option which requires git>=1.6.5)
• tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses
'--remote' option which requires git>=1.8.2)
• parent-credentials (bool) - Use credentials from default remote of parent
repository (default false).
• reference-repo (str) - Path of the reference repo to use during clone (optional)
• timeout (int) - Specify a timeout (in minutes) for submodules operations
(default 10).
• timeout (str) - Timeout for git commands in minutes (optional)
•
use-author (bool): Use author rather than committer in Jenkin's
build changeset (default false)
•
wipe-workspace (bool) - Wipe out workspace before build
(default true)
Job examples:
name: github-org-minimal
project-type: githuborg
project: example-project
github-org:
repo-owner: example-owner
name: github-org-full
project-type: githuborg
github-org:
api-uri: http://example.org/github
ssh-checkout:
credentials: 'ssh_secret'
repo-owner: example-owner
credentials-id: example-credential
branch-discovery: all
head-filter-regex: "(.*/master|.*/release/.*)"
head-pr-filter-behaviors:
head-pr-destined-regex:
branch-regexp: "foo/.*"
tag-regexp: "20\\..*"
head-pr-destined-wildcard:
branch-includes: "foo*"
tag-includes: "qaz*"
branch-excludes: "bar*"
tag-excludes: "*baz"
head-pr-originated-regex:
branch-regexp: "(foo/.*|bar/.*)"
tag-regexp: "1\\..*"
head-pr-originated-wildcard:
branch-includes: "qaz*"
tag-includes: "bar*"
branch-excludes: "baz*"
tag-excludes: "*qaz"
discover-pr-forks-strategy: both
discover-pr-forks-trust: everyone
discover-pr-origin: both
discover-tags: true
notification-context: 'jenkins.example.com/my_context'
property-strategies:
all-branches:
- suppress-scm-triggering: true
- pipeline-branch-durability-override: max-survivability
- trigger-build-on-pr-comment: "Ci build!"
- trigger-build-on-pr-review: true
- trigger-build-on-pr-update: true
build-strategies:
- all-strategies-match:
strategies:
- regular-branches: true
- skip-initial-build: true
- any-strategies-match:
strategies:
- change-request: {}
- tags: {}
- tags:
ignore-tags-newer-than: 1
ignore-tags-older-than: 7
- tags: {}
- change-request:
ignore-target-only-changes: true
- change-request: {}
- regular-branches: true
- skip-initial-build: true
- named-branches:
- exact-name:
name: 'test'
case-sensitive: true
- regex-name:
regex: 'test.*$'
case-sensitive: true
- wildcards-name:
excludes: 'testexclude'
includes: 'testinclude'
- named-branches:
- exact-name: {}
- regex-name: {}
- wildcards-name: {}
clean:
after: true
before: true
committer:
user: CI System
email: no-reply@ci.example.com
prune: true
local-branch: true
sparse-checkout:
paths:
- "path1"
- "path2"
- "path3"
shallow-clone: true
depth: 3
do-not-fetch-tags: true
disable-pr-notifications: true
refspecs:
- '+refs/heads/*:refs/remotes/@{remote}/*'
submodule:
disable: false
recursive: true
parent-credentials: true
timeout: 100
threads: 1
timeout: "100"
skip-notifications: true
use-author: true
wipe-workspace: true
lfs-pull: 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 supports four axes which share
the same internal YAML structure:
• label expressions (label-expression)
• user-defined values (user-defined)
• slave name or label (slave)
• JDK name (jdk)
Requires the Jenkins Matrix Project Plugin.
The module also supports additional, plugin-defined axes:
• DynamicAxis (dynamic), requires the Jenkins DynamicAxis Plugin
• GroovyAxis (groovy), requires the Jenkins GroovyAxis Plugin
• YamlAxis (yaml), requires the Jenkins Yaml Axis Plugin
To tie the parent job to a specific node, you should use node parameter. On a matrix project, this will
tie only the parent job. To restrict axes jobs, you can define a single value slave axis.
Job Parameters
NOTE:
You can only pick one of the strategies.
•
execution-strategy (optional, built in Jenkins):
• 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
• yaml-strategy (optional, requires Yaml Axis Plugin):
• exclude-key (str) -- top key containing exclusion rules
• Either one of:
• filename (str) -- Yaml file containing exclusions
• text (str) -- Inlined Yaml. Should be literal text: | exclude:...
•
axes (list):
•
axis:
• type (str) -- axis type, must be either type defined by Matrix Project Plugin
(label-expression, user-defined, slave or jdk) or a type defined by a plugin
(see top of this document for a list of supported plugins).
• name (str) -- name of the axis
• values (list) -- values of the axis
The module supports also ShiningPanda axes:
Example:
name: matrix-test003
project-type: matrix
axes:
- axis:
type: python
values:
- python-2.6
- python-2.7
- python-3.4
- axis:
type: tox
values:
- py26
- py27
- py34
Requires the Jenkins ShiningPanda Plugin.
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
- axis:
type: dynamic
name: config
values:
- config_list
- axis:
type: user-defined
name: database
values:
- mysql
- postgresql
- sqlite
- axis:
type: groovy
name: foo
command: return [one,two,three]
builders:
- shell: make && make check
Examples for yaml axis:
name: matrix-with-yaml-axis
project-type: matrix
axes:
- axis:
type: yaml
filename: config.yaml
name: python
- axis:
type: yaml
filename: config.yaml
name: database
name: matrix-with-yaml-strategy-and-exclude-in-file
project-type: matrix
yaml-strategy:
exclude-key: 'exclude'
filename: 'exclude.yaml'
axes:
- axis:
type: yaml
filename: 'config.yaml'
name: python
- axis:
type: yaml
filename: 'config.yaml'
name: database
name: matrix-with-yaml-strategy-and-inlined-exclude
project-type: matrix
yaml-strategy:
exclude-key: 'exclude'
text: |
exclude:
- database: postgre
python: py27
- python: py35
database: mysql
axes:
- axis:
type: yaml
filename: config.yaml
name: python
- axis:
type: yaml
filename: config.yaml
name: database
class project_matrix.Matrix(registry)
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.
• artifact-id (str): ArtifactId.
• root-pom (str): The path to the pom.xml file. (default '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.
• private-repository ('str'): Whether to use a private maven repository Possible values are
default, local-to-workspace and local-to-executor.
• ignore-upstream-changes (bool): Do not start a build whenever a SNAPSHOT dependency is built or
not. (default true)
• incremental-build (bool): Activate incremental build - only build changed modules (default
false).
• automatic-archiving (bool): Activate automatic artifact archiving (default true).
• automatic-site-archiving (bool): Activate automatic site documentation artifact archiving
(default true).
• automatic-fingerprinting (bool): Activate automatic fingerprinting of consumed and produced
artifacts (default true).
• per-module-email (bool): Send an e-mail for each failed module (default true).
• parallel-build-modules (bool): Build modules in parallel (default false)
• resolve-dependencies (bool): Resolve Dependencies during Pom parsing (default false).
• run-headless (bool): Run headless (default false).
• disable-downstream (bool): Disable triggering of downstream projects (default false).
• process-plugins (bool): Process Plugins during Pom parsing (default false).
• custom-workspace (str): Path to the custom workspace. If no path is provided, custom workspace
is not used. (optional)
• settings (str): Path to custom maven settings file. If settings type is 'file' then this is a
Path. Otherwise it is the id for ConfigFileProvider. (optional)
• settings-type (str): Type of settings file file|cfp. (default file)
• global-settings (str): Path to custom maven global settings file. If settings type is 'file'
then this is a Path. Otherwise it is the id for ConfigFileProvider. (optional)
• global-settings-type (str): Type of settings file file|cfp. (default file)
• post-step-run-condition (str): Run the post-build steps only if the build succeeds ('SUCCESS'),
build succeeds or is unstable ('UNSTABLE'), regardless of build result ('FAILURE'). (default
'FAILURE').
Requires the Jenkins Config File Provider Plugin for the Config File Provider "settings" and
"global-settings" config.
Example:
project-type: maven
maven:
root-pom: pom.xml
goals: deploy
root-module:
group-id: gabba.gabba
artifact-id: hey
settings: test
global-settings: test
incremental-build: true
automatic-archiving: false
automatic-site-archiving: false
parallel-build-modules: true
resolve-dependencies: true
process-plugins: true
run-headless: true
disable-downstream: true
custom-workspace: path/to/some/repository
CFP Example:
project-type: maven
maven:
root-pom: pom.xml
goals: deploy
settings: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012
global-settings: org.jenkinsci.plugins.configfiles.maven.GlobalMavenSettingsConfig0123456789012
post-step-run-condition: SUCCESS
class project_maven.Maven(registry)
MultiJob Project
The MultiJob Project module handles creating MultiJob Jenkins projects. You may specify multijob in the
project-type attribute of the Job definition.
This project type may use jenkins_jobs.modules.builders.multijob() builders.
Requires the Jenkins Multijob Plugin.
Example:
job:
name: test_job
project-type: multijob
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
class project_multijob.MultiJob(registry)
Pipeline Project
The Pipeline Project module handles creating Jenkins Pipeline projects (formerly known as the Workflow
projects). You may specify pipeline in the project-type attribute of the Job definition.
Requires the Jenkins Pipeline Plugin.
In order to write an inline script within a job-template you have to escape the curly braces by doubling
them in the DSL: { -> {{ , otherwise it will be interpreted by the python str.format() command.
Job Parameters
• sandbox (bool): If the script should run in a sandbox (default false)
• dsl (str): The DSL content or,
• pipeline-scm (str): in case "Pipeline as code" feature is used. Then you should specify:
• scm: single scm component (or a reference) describing the source code repository
• script-path: path to the Groovy file containing the job's steps (optional, default:
Jenkinsfile)
• lightweight-checkout (bool): If selected, try to obtain the Pipeline script contents
directly from the SCM without performing a full checkout. (optional, default: false)
Note that dsl and pipeline-scm parameters are mutually exclusive.
Inline DSL job example:
- job:
name: test_job
project-type: pipeline
dsl: |
build job: "job1"
parallel [
2a: build job: "job2a",
2b: node "dummynode" {
sh "echo I'm alive!"
}
]
Inline DSL job template example:
- job-template:
name: '{name}-unit-tests'
project-type: pipeline
dsl: |
build job: "job1"
parallel [
2a: build job: "job2a",
2b: node "dummynode" {{
sh "echo {isay}"
}}
]
- job-group:
name: '{name}-tests'
jobs:
- '{name}-unit-tests':
isay: 'hello'
- project:
name: project-name
jobs:
- '{name}-tests'
"Pipeline as code" example:
- job:
name: test-job
project-type: pipeline
sandbox: true
pipeline-scm:
scm:
- hg:
url: http://hg.example.org/test_job
clean: true
script-path: Jenkinsfile.groovy
lightweight-checkout: true
"Pipeline as code" example using templates:
- scm:
name: project-scm
scm:
- hg:
url: http://hg.example.org/project
clean: true
- job-template:
name: '{name}-unit-tests'
project-type: pipeline
pipeline-scm:
scm:
- project-scm
sandbox: true
description: 'maintainer: {maintainer}'
- job-template:
name: '{name}-perf-tests'
project-type: pipeline
pipeline-scm:
scm:
- project-scm
sandbox: false
description: 'maintainer: {maintainer}'
- job-group:
name: '{name}-tests'
jobs:
- '{name}-unit-tests':
maintainer: dev@example.org
- '{name}-perf-tests':
maintainer: qa@example.org
- project:
name: project-name
jobs:
- '{name}-tests'
"Pipeline as nested stage" example :
- job-template:
name: '{name}-unit-tests'
project-type: pipeline
dsl: |
stage('Build another job') {{
build(job: "{isay}")
}}
- job-group:
name: '{name}-tests'
jobs:
- '{name}-unit-tests':
isay: 'hello'
- project:
name: project-name
jobs:
- '{name}-tests'
class project_pipeline.Pipeline(registry)
Workflow Project
Deprecated: please use project_pipeline instead.
The workflow Project module handles creating Jenkins workflow projects. You may specify workflow in the
project-type attribute of the Job definition. For now only inline scripts are supported.
Requires the Jenkins Workflow Plugin.
In order to use it for job-template you have to escape the curly braces by doubling them in the DSL: { ->
{{ , otherwise it will be interpreted by the python str.format() command.
Job Parameters
• dsl (str): The DSL content.
• sandbox (bool): If the script should run in a sandbox (default false)
Job example:
- job:
name: test_job
project-type: workflow
dsl: |
build job: "job1"
parallel [
2a: build job: "job2a",
2b: node "dummynode" {
sh "echo I'm alive!"
}
]
Job template example:
- job-template:
name: '{name}-unit-tests'
project-type: workflow
dsl: |
build job: "job1"
parallel [
2a: build job: "job2a",
2b: node "dummynode" {{
sh "echo {isay}"
}}
]
- job-group:
name: '{name}-tests'
jobs:
- '{name}-unit-tests':
isay: 'hello'
- project:
name: project-name
jobs:
- '{name}-tests'
class project_workflow.Workflow(registry)
Multibranch Pipeline Project
The Multibranch Pipeline project module handles creating Jenkins workflow projects. You may specify
multibranch in the project-type attribute of the Job definition.
Multibranch Pipeline implementantion in JJB is marked as experimental which means that there is no
guarantee that its behavior (or configuration) will not change, even between minor releases.
Plugins required:
• Workflow Plugin.
• Pipeline Multibranch Defaults Plugin (optional)
• Basic Branch Build Strategies Plugin (optional)
Job Parameters
• scm (list): The SCM definition.
• bitbucket (dict): Refer to ~bitbucket_scm for documentation.
• gerrit (dict): Refer to ~gerrit_scm for documentation.
• git (dict): Refer to ~git_scm for documentation.
• github (dict): Refer to ~github_scm for documentation.
• periodic-folder-trigger (str): How often to scan for new branches or pull/change requests. Valid
values: 1m, 2m, 5m, 10m, 15m, 20m, 25m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 2d, 1w, 2w, 4w. (default
none)
• prune-dead-branches (bool): If dead branches upon check should result in their job being
dropped. (default true)
• number-to-keep (int): How many builds should be kept. (default '-1, all')
• days-to-keep (int): For how many days should a build be kept. (default '-1, forever')
• script-path (str): Path to Jenkinsfile, relative to workspace. (default 'Jenkinsfile')
• script-id (str): Script id from the global Jenkins script store provided by the config-file
provider plugin. Mutually exclusive with script-path option.
• sandbox (bool): This option is strongly recommended if the Jenkinsfile is using load to evaluate
a groovy source file from an SCM repository. Usable only with script-id option. (default
'false')
Job examples:
name: 'demo-multibranch-defaults'
project-type: multibranch-defaults
script-id: my-pipeline
sandbox: true
scm:
- github:
repo: 'foo'
repo-owner: 'johndoe'
credentials-id: 'secret'
name: 'demo-multibranch-defaults'
project-type: multibranch-defaults
scm:
- github:
repo: 'foo'
repo-owner: 'johndoe'
credentials-id: 'secret'
name: 'demo-multibranch-multi-scm-full'
description: 'Workflow demo'
project-type: multibranch
periodic-folder-trigger: 1d
prune-dead-branches: True
number-to-keep: '10'
days-to-keep: '10'
script-path: 'some.Jenkinsfile'
scm:
- bitbucket:
repo-owner: 'SANDBOX'
repo: 'test'
credentials-id: 'secret'
- git:
url: 'https://example.com/jonhndoe/keep-frontend.git'
credentials-id: 'secret'
- github:
repo: 'foo'
repo-owner: 'johndoe'
credentials-id: 'secret'
class project_multibranch.WorkflowMultiBranch(registry)
class project_multibranch.WorkflowMultiBranchDefaults(registry)
project_multibranch.add_filter_branch_pr_behaviors(traits, data)
Configure Filter Branch PR behaviors
Requires the SCM Filter Branch PR Plugin.
Parameters
head-pr-filter-behaviors (list) --
Definition of filters.
•
head-pr-destined-regex (dict): Filter by name incl. PR destined to
this branch with regexp
•
branch-regexp (str) Regular expression to filter branches and
PRs (optional, default ".*")
•
tag-regexp (str) Regular expression to filter tags
(optional, default "(?!.*)")
•
head-pr-destined-wildcard (dict): Filter by name incl. PR
destined to this branch with wildcard
•
branch-includes (str) Wildcard expression to include branches
and PRs (optional, default "*")
•
tag-includes (str) Wildcard expression to include tags
(optional, default "")
•
branch-excludes (str) Wildcard expression to exclude branches
and PRs (optional, default "")
•
tag-excludes (str) Wildcard expression to exclude tags
(optional, default "*")
•
head-pr-originated-regex (dict): Filter by name incl. PR destined
to this branch with regexp
•
branch-regexp (str) Regular expression to filter branches
and PRs (optional, default ".*")
•
tag-regexp (str) Regular expression to filter tags
(optional, default "(?!.*)")
•
head-pr-originated-wildcard (dict): Filter by name incl. PR
destined to this branch with wildcard
•
branch-includes (str) Wildcard expression to include branches
and PRs (optional, default "*")
•
tag-includes (str) Wildcard expression to include tags
(optional, default "")
•
branch-excludes (str) Wildcard expression to exclude branches
and PRs (optional, default "")
•
tag-excludes (str) Wildcard expression to exclude tags
(optional, default "*")
project_multibranch.add_filter_by_name_wildcard_behaviors(traits, data)
Configure branch filtering behaviors.
Parameters
filter-by-name-wildcard (dict) --
Enable filter by name with wildcards. Requires the SCM API Plugin.
•
includes ('str'): Space-separated list
of name patterns to consider. You may use * as a wildcard; for example: master
release*
•
excludes ('str'): Name patterns to
ignore even if matched by the includes list. For example: release*
project_multibranch.bitbucket_scm(xml_parent, data)
Configure BitBucket scm
Requires the Bitbucket Branch Source Plugin.
Parameters
• credentials-id (str) -- The credential to use to scan BitBucket. (required)
• repo-owner (str) -- Specify the name of the Bitbucket Team or Bitbucket User Account.
(required)
• repo (str) -- The BitBucket repo. (required)
• discover-tags (bool) -- Discovers tags on the repository. (default false)
• lfs (bool) -- Git LFS pull after checkout. (default false)
• server-url (str) -- The address of the bitbucket server. (optional)
• head-filter-regex (str) -- A regular expression for filtering discovered source branches.
Requires the SCM API Plugin.
• head-pr-filter-behaviors (list) -- Definition of Filter Branch PR behaviors. Requires
the SCM Filter Branch PR Plugin. Refer to ~add_filter_branch_pr_behaviors.
• discover-branch (str) -- Discovers branches on the repository. Valid options: ex-pr,
only-pr, all. Value is not specified by default.
• discover-pr-origin (str) -- Discovers pull requests where the origin repository is the
same as the target repository. Valid options: mergeOnly, headOnly, mergeAndHead. Value
is not specified by default.
• discover-pr-forks-strategy (str) -- Fork strategy. Valid options: merge-current, current,
both, false. (default 'merge-current')
• discover-pr-forks-trust (str) -- Discovers pull requests where the origin repository is a
fork of the target repository. Valid options: contributors, everyone, permission or
nobody. (default 'contributors')
• build-strategies (list) -- Provides control over whether to build a branch (or branch
like things such as change requests and tags) whenever it is discovered initially or a
change from the previous revision has been detected. (optional) Refer to
~build_strategies.
• property-strategies (dict) -- Provides control over how to build a branch (like to
disable SCM triggering or to override the pipeline durability) (optional) Refer to
~property_strategies.
• local-branch (bool) -- Check out to matching local branch If given, checkout the revision
to build as HEAD on this branch. If selected, then the branch name is computed from the
remote branch without the origin. In that case, a remote branch origin/master will be
checked out to a local branch named master, and a remote branch
origin/develop/new-feature will be checked out to a local branch named
develop/newfeature. Requires the Git Plugin.
• refspecs (list(str)) -- Which refspecs to look for.
• checkout-over-ssh (dict) --
Checkout repo over ssh.
•
credentials ('str'): Credentials to use for
checkout of the repo over ssh.
• filter-by-name-wildcard (dict) --
Enable filter by name with wildcards. Requires the SCM API Plugin.
•
includes ('str'): Space-separated list
of name patterns to consider. You may use * as a wildcard; for example: master
release*
•
excludes ('str'): Name patterns to
ignore even if matched by the includes list. For example: release*
Extensions
•
clean (dict)
• after (bool) - Clean the workspace after checkout
• before (bool) - Clean the workspace before checkout
• prune (bool) - Prune remote branches (default false)
• shallow-clone (bool) - Perform shallow clone (default false)
•
sparse-checkout (dict)
• paths (list) - List of paths to sparse checkout. (optional)
• depth (int) - Set shallow clone depth (default 1)
•
do-not-fetch-tags (bool) - Perform a clone without tags
(default false)
•
submodule (dict)
• disable (bool) - By disabling support for submodules you can still keep using
basic git plugin functionality and just have Jenkins to ignore submodules
completely as if they didn't exist.
• recursive (bool) - Retrieve all submodules recursively (uses '--recursive'
option which requires git>=1.6.5)
• tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses
'--remote' option which requires git>=1.8.2)
• parent-credentials (bool) - Use credentials from default remote of parent
repository (default false).
• reference-repo (str) - Path of the reference repo to use during clone (optional)
• timeout (int) - Specify a timeout (in minutes) for submodules operations
(default 10).
• timeout (str) - Timeout for git commands in minutes (optional)
•
use-author (bool): Use author rather than committer in Jenkin's
build changeset (default false)
•
wipe-workspace (bool) - Wipe out workspace before build
(default true)
•
lfs-pull (bool) - Call git lfs pull after checkout
(default false)
Minimal Example:
name: 'demo-multibranch-bitbucket-min'
project-type: multibranch
scm:
- bitbucket:
repo-owner: 'SANDBOX'
repo: 'test'
Full Example:
name: 'demo-multibranch-bitbucket-min'
project-type: multibranch
script-path: 'some.Jenkinsfile'
scm:
- bitbucket:
credentials-id: 'secret'
repo-owner: 'SANDBOX'
repo: 'test'
server-url: https://bitbucket.example.com:8080
discover-tags: true
lfs: true
head-filter-regex: 'master|\d+\.\d+'
head-pr-filter-behaviors:
head-pr-destined-regex:
branch-regexp: "foo/.*"
tag-regexp: "20\\..*"
head-pr-destined-wildcard:
branch-includes: "foo*"
tag-includes: "qaz*"
branch-excludes: "bar*"
tag-excludes: "*baz"
head-pr-originated-regex:
branch-regexp: "(foo/.*|bar/.*)"
tag-regexp: "1\\..*"
head-pr-originated-wildcard:
branch-includes: "qaz*"
tag-includes: "bar*"
branch-excludes: "baz*"
tag-excludes: "*qaz"
discover-pr-origin: headOnly
discover-branch: all
discover-pr-forks-strategy: current
discover-pr-forks-trust: everyone
local-branch: true
checkout-over-ssh:
credentials: 'ssh_secret'
filter-by-name-wildcard:
includes: '*'
excludes: 'master'
property-strategies:
all-branches:
- suppress-scm-triggering: true
- pipeline-branch-durability-override: max-survivability
refspecs:
- '+refs/heads/*:refs/remotes/@{remote}/*'
- '+refs/tags/*:refs/remotes/@{remote}/*'
build-strategies:
- all-strategies-match:
strategies:
- regular-branches: true
- skip-initial-build: true
- any-strategies-match:
strategies:
- change-request: {}
- tags: {}
- tags:
ignore-tags-newer-than: 1
ignore-tags-older-than: 7
- tags: {}
- change-request:
ignore-target-only-changes: true
- change-request: {}
- regular-branches: true
- skip-initial-build: true
- named-branches:
- exact-name:
name: 'test'
case-sensitive: true
- regex-name:
regex: 'test.*$'
case-sensitive: true
- wildcards-name:
excludes: 'testexclude'
includes: 'testinclude'
- named-branches:
- exact-name: {}
- regex-name: {}
- wildcards-name: {}
clean:
after: true
before: true
committer:
user: CI System
email: no-reply@ci.example.com
prune: true
sparse-checkout:
paths:
- "path1"
- "path2"
- "path3"
shallow-clone: true
depth: 3
do-not-fetch-tags: true
submodule:
disable: false
recursive: true
parent-credentials: true
timeout: 100
threads: 1
timeout: "100"
skip-notifications: true
use-author: true
wipe-workspace: true
lfs-pull: true
project_multibranch.build_strategies(xml_parent, data)
Configure Basic Branch Build Strategies.
Requires the Basic Branch Build Strategies Plugin.
Other build strategies can be configured via raw XML injection.
Parameters
build-strategies (list) --
Definition of build strategies.
•
all-strategies-match (dict): All sub strategies must match for
this strategy to match. * strategies (list): Sub strategies
•
any-strategies-match (dict): Builds whenever any of the sub
strategies match. * strategies (list): Sub strategies
•
tags (dict): Builds tags
•
ignore-tags-newer-than (int) The number of days since the tag
was created before it is eligible for automatic building. (optional,
default -1)
•
ignore-tags-older-than (int) The number of days since the tag
was created after which it is no longer eligible for automatic building.
(optional, default -1)
•
change-request (dict): Builds change requests / pull requests
•
ignore-target-only-changes (bool) Ignore rebuilding merge
branches when only the target branch changed. (optional, default false)
•
regular-branches (bool): Builds regular branches whenever a
change is detected. (optional, default None)
•
skip-initial-build (bool): Skip initial build on first branch
indexing. (optional, default None)
• named-branches (list): Builds named branches whenever a change is detected.
•
exact-name (dict) Matches the name verbatim.
• name (str) The name to match. (optional)
•
case-sensitive (bool) Check this box if the name should
be matched case sensitively. (default false)
• regex-name (dict) Matches the name against a regular expression.
•
regex (str) A Java regular expression to restrict the
names. Names that do not match the supplied regular expression will be
ignored. (default ^.*$)
•
case-sensitive (bool) Check this box if the name should
be matched case sensitively. (default false)
• wildcards-name (dict) Matches the name against an include/exclude set of wildcards.
•
includes (str) Space-separated list of name patterns to
consider. You may use * as a wildcard; for example: master release*
(default *)
•
excludes (str) Name patterns to ignore even if matched
by the includes list. For example: release (optional)
•
raw (dict): Injects raw BuildStrategy XML to use other build
strategy plugins.
project_multibranch.gerrit_scm(xml_parent, data)
Configure Gerrit SCM
Requires the Gerrit Code Review Plugin.
Parameters
• url (str) -- The git url. (required)
• credentials-id (str) -- The credential to use to connect to the GIT URL.
• ignore-on-push-notifications (bool) -- If a job should not trigger upon push
notifications. (default false)
• refspecs (list(str)) -- Which refspecs to look for. (default
['+refs/changes/*:refs/remotes/@{remote}/*', '+refs/heads/*:refs/remotes/@{remote}/*'])
• includes (str) -- Comma-separated list of branches to be included. (default '*')
• excludes (str) -- Comma-separated list of branches to be excluded. (default '')
• build-strategies (list) -- Provides control over whether to build a branch (or branch
like things such as change requests and tags) whenever it is discovered initially or a
change from the previous revision has been detected. (optional) Refer to
~build_strategies.
• property-strategies (dict) -- Provides control over how to build a branch (like to
disable SCM triggering or to override the pipeline durability) (optional) Refer to
~property_strategies.
• filter-checks (dict) -- Enable the filtering by pending checks, allowing to discover the
changes that need validation only. This feature is using the gerrit checks plugin.
(optional) query-operator: Name of the query operator, supported values are: 'SCHEME' or
'ID'. query-string: Value of the query operator.
Extensions
•
clean (dict)
• after (bool) - Clean the workspace after checkout
• before (bool) - Clean the workspace before checkout
• prune (bool) - Prune remote branches (default false)
• shallow-clone (bool) - Perform shallow clone (default false)
•
sparse-checkout (dict)
• paths (list) - List of paths to sparse checkout. (optional)
• depth (int) - Set shallow clone depth (default 1)
•
do-not-fetch-tags (bool) - Perform a clone without tags
(default false)
•
submodule (dict)
• disable (bool) - By disabling support for submodules you can still keep using
basic git plugin functionality and just have Jenkins to ignore submodules
completely as if they didn't exist.
• recursive (bool) - Retrieve all submodules recursively (uses '--recursive'
option which requires git>=1.6.5)
• tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses
'--remote' option which requires git>=1.8.2)
• parent-credentials (bool) - Use credentials from default remote of parent
repository (default false).
• reference-repo (str) - Path of the reference repo to use during clone (optional)
• timeout (int) - Specify a timeout (in minutes) for submodules operations
(default 10).
• timeout (str) - Timeout for git commands in minutes (optional)
•
use-author (bool): Use author rather than committer in Jenkin's
build changeset (default false)
•
wipe-workspace (bool) - Wipe out workspace before build
(default true)
•
lfs-pull (bool) - Call git lfs pull after checkout
(default false)
Minimal Example:
name: 'demo-multibranch-gerrit-min'
project-type: multibranch
scm:
- gerrit:
url: 'https://review.gerrithub.io/johndoe/foo'
Full Example:
name: 'demo-multibranch-gerrit-min'
project-type: multibranch
script-path: some.Jenkinsfile
scm:
- gerrit:
url: 'https://review.gerrithub.io/johndoe/foo'
credentials-id: secret
ignore-on-push-notifications: true
refspecs: 'refs/heads/*'
property-strategies:
all-branches:
- suppress-scm-triggering: true
- pipeline-branch-durability-override: max-survivability
filter-checks:
query-operator: 'SCHEME'
query-string: 'jenkins'
build-strategies:
- all-strategies-match:
strategies:
- regular-branches: true
- skip-initial-build: true
- any-strategies-match:
strategies:
- change-request: {}
- tags: {}
- tags:
ignore-tags-newer-than: 1
ignore-tags-older-than: 7
- tags: {}
- change-request:
ignore-target-only-changes: true
- change-request: {}
- regular-branches: true
- skip-initial-build: true
- named-branches:
- exact-name:
name: 'test'
case-sensitive: true
- regex-name:
regex: 'test.*$'
case-sensitive: true
- wildcards-name:
excludes: 'testexclude'
includes: 'testinclude'
- named-branches:
- exact-name: {}
- regex-name: {}
- wildcards-name: {}
clean:
after: true
before: true
prune: true
local-branch: true
sparse-checkout:
paths:
- "path1"
- "path2"
- "path3"
shallow-clone: true
depth: 3
do-not-fetch-tags: true
submodule:
disable: false
recursive: true
parent-credentials: true
timeout: 100
threads: 1
timeout: "100"
use-author: true
wipe-workspace: true
lfs-pull: true
project_multibranch.git_scm(xml_parent, data)
Configure Git SCM
Requires the Git Plugin.
Parameters
• url (str) -- The git repo url. (required)
• credentials-id (str) -- The credential to use to connect to the GIT repo. (default '')
• discover-branches (bool) -- Discovers branches on the repository. (default true)
• discover-tags (bool) -- Discovers tags on the repository. (default false)
• ignore-on-push-notifications (bool) -- If a job should not trigger upon push
notifications. (default false)
• head-filter-regex (str) -- A regular expression for filtering discovered source branches.
Requires the SCM API Plugin.
• head-pr-filter-behaviors (list) -- Definition of Filter Branch PR behaviors. Requires
the SCM Filter Branch PR Plugin. Refer to ~add_filter_branch_pr_behaviors.
• build-strategies (list) -- Provides control over whether to build a branch (or branch
like things such as change requests and tags) whenever it is discovered initially or a
change from the previous revision has been detected. (optional) Refer to
~build_strategies.
• property-strategies (dict) -- Provides control over how to build a branch (like to
disable SCM triggering or to override the pipeline durability) (optional) Refer to
~property_strategies.
Extensions
•
clean (dict)
• after (bool) - Clean the workspace after checkout
• before (bool) - Clean the workspace before checkout
• prune (bool) - Prune remote branches (default false)
• shallow-clone (bool) - Perform shallow clone (default false)
•
sparse-checkout (dict)
• paths (list) - List of paths to sparse checkout. (optional)
• depth (int) - Set shallow clone depth (default 1)
•
do-not-fetch-tags (bool) - Perform a clone without tags
(default false)
•
submodule (dict)
• disable (bool) - By disabling support for submodules you can still keep using
basic git plugin functionality and just have Jenkins to ignore submodules
completely as if they didn't exist.
• recursive (bool) - Retrieve all submodules recursively (uses '--recursive'
option which requires git>=1.6.5)
• tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses
'--remote' option which requires git>=1.8.2)
• parent-credentials (bool) - Use credentials from default remote of parent
repository (default false).
• reference-repo (str) - Path of the reference repo to use during clone (optional)
• timeout (int) - Specify a timeout (in minutes) for submodules operations
(default 10).
• timeout (str) - Timeout for git commands in minutes (optional)
•
use-author (bool): Use author rather than committer in Jenkin's
build changeset (default false)
•
wipe-workspace (bool) - Wipe out workspace before build
(default true)
•
lfs-pull (bool) - Call git lfs pull after checkout
(default false)
Minimal Example:
name: 'demo-multibranch-git-min'
project-type: multibranch
scm:
- git:
url: 'https://example.com/jonhndoe/keep-frontend.git'
Full Example:
name: 'demo-multibranch-git-min'
project-type: multibranch
script-path: some.Jenkinsfile
scm:
- git:
url: 'https://example.com/jonhndoe/keep-frontend.git'
credentials-id: secret
discover-branches: false
ignore-on-push-notifications: true
discover-tags: true
head-filter-regex: 'master|\d+\.\d+'
head-pr-filter-behaviors:
head-pr-destined-regex:
branch-regexp: "foo/.*"
tag-regexp: "20\\..*"
head-pr-destined-wildcard:
branch-includes: "foo*"
tag-includes: "qaz*"
branch-excludes: "bar*"
tag-excludes: "*baz"
head-pr-originated-regex:
branch-regexp: "(foo/.*|bar/.*)"
tag-regexp: "1\\..*"
head-pr-originated-wildcard:
branch-includes: "qaz*"
tag-includes: "bar*"
branch-excludes: "baz*"
tag-excludes: "*qaz"
property-strategies:
all-branches:
- suppress-scm-triggering: true
- pipeline-branch-durability-override: max-survivability
build-strategies:
- all-strategies-match:
strategies:
- regular-branches: true
- skip-initial-build: true
- any-strategies-match:
strategies:
- change-request: {}
- tags: {}
- tags:
ignore-tags-newer-than: 1
ignore-tags-older-than: 7
- tags: {}
- change-request:
ignore-target-only-changes: true
- change-request: {}
- regular-branches: true
- skip-initial-build: true
- named-branches:
- exact-name:
name: 'test'
case-sensitive: true
- regex-name:
regex: 'test.*$'
case-sensitive: true
- wildcards-name:
excludes: 'testexclude'
includes: 'testinclude'
- named-branches:
- exact-name: {}
- regex-name: {}
- wildcards-name: {}
- raw:
xml: |
<com.igalg.jenkins.plugins.multibranch.buildstrategy.IncludeRegionBranchBuildStrategy plugin="multibranch-build-strategy-extension">
<includedRegions>my/cool/project/*.cpp</includedRegions>
</com.igalg.jenkins.plugins.multibranch.buildstrategy.IncludeRegionBranchBuildStrategy>
clean:
after: true
before: true
prune: true
local-branch: true
sparse-checkout:
paths:
- "path1"
- "path2"
- "path3"
shallow-clone: true
depth: 3
do-not-fetch-tags: true
submodule:
disable: false
recursive: true
parent-credentials: true
timeout: 100
threads: 1
timeout: "100"
use-author: true
wipe-workspace: true
lfs-pull: true
project_multibranch.github_scm(xml_parent, data)
Configure GitHub SCM
Requires the GitHub Branch Source Plugin.
Parameters
• api-uri (str) -- The GitHub API uri for hosted / on-site GitHub. Must first be configured
in Global Configuration. (default GitHub)
• ssh-checkout (bool) --
Checkout over SSH.
•
credentials ('str'): Credentials to use for
checkout of the repo over ssh.
• credentials-id (str) -- Credentials used to scan branches and pull requests, check out
sources and mark commit statuses. (optional)
• repo-owner (str) -- Specify the name of the GitHub Organization or GitHub User Account.
(required)
• repo (str) -- The GitHub repo. (required)
• branch-discovery (str) -- Discovers branches on the repository. Valid options: no-pr,
only-pr, all, false. (default 'no-pr')
• discover-pr-forks-strategy (str) -- Fork strategy. Valid options: merge-current, current,
both, false. (default 'merge-current')
• discover-pr-forks-trust (str) -- Discovers pull requests where the origin repository is a
fork of the target repository. Valid options: contributors, everyone, permission or
nobody. (default 'contributors')
• discover-pr-origin (str) -- Discovers pull requests where the origin repository is the
same as the target repository. Valid options: merge-current, current, both, false.
(default 'merge-current')
• discover-tags (bool) -- Discovers tags on the repository. (default false)
• head-pr-filter-behaviors (list) -- Definition of Filter Branch PR behaviors. Requires
the SCM Filter Branch PR Plugin. Refer to ~add_filter_branch_pr_behaviors.
• build-strategies (list) -- Provides control over whether to build a branch (or branch
like things such as change requests and tags) whenever it is discovered initially or a
change from the previous revision has been detected. (optional) Refer to
~build_strategies.
• notification-context (str) -- Change the default GitHub check notification context from
"continuous-integration/jenkins/SUFFIX" to a custom text, Requires the Github Custom
Notification Context SCM Behaviour.
• property-strategies (dict) -- Provides control over how to build a branch (like to
disable SCM triggering or to override the pipeline durability) (optional) Refer to
~property_strategies.
• filter-by-name-wildcard (dict) --
Enable filter by name with wildcards. Requires the SCM API Plugin.
•
includes ('str'): Space-separated list
of name patterns to consider. You may use * as a wildcard; for example: master
release*
•
excludes ('str'): Name patterns to
ignore even if matched by the includes list. For example: release*
Extensions
•
clean (dict)
• after (bool) - Clean the workspace after checkout
• before (bool) - Clean the workspace before checkout
• prune (bool) - Prune remote branches (default false)
• shallow-clone (bool) - Perform shallow clone (default false)
•
sparse-checkout (dict)
• paths (list) - List of paths to sparse checkout. (optional)
• depth (int) - Set shallow clone depth (default 1)
•
do-not-fetch-tags (bool) - Perform a clone without tags
(default false)
•
disable-pr-notifications (bool) - Disable default github status
notifications on pull requests (default false) (Requires the GitHub Branch Source
Plugin.)
• refspecs (list(str)): Which refspecs to fetch.
•
submodule (dict)
• disable (bool) - By disabling support for submodules you can still keep using
basic git plugin functionality and just have Jenkins to ignore submodules
completely as if they didn't exist.
• recursive (bool) - Retrieve all submodules recursively (uses '--recursive'
option which requires git>=1.6.5)
• tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses
'--remote' option which requires git>=1.8.2)
• parent-credentials (bool) - Use credentials from default remote of parent
repository (default false).
• reference-repo (str) - Path of the reference repo to use during clone (optional)
• timeout (int) - Specify a timeout (in minutes) for submodules operations
(default 10).
• timeout (str) - Timeout for git commands in minutes (optional)
•
use-author (bool): Use author rather than committer in Jenkin's
build changeset (default false)
•
wipe-workspace (bool) - Wipe out workspace before build
(default true)
•
lfs-pull (bool) - Call git lfs pull after checkout
(default false)
Minimal Example:
name: 'demo-multibranch-github-min'
project-type: multibranch
scm:
- github:
repo: 'foo'
repo-owner: 'johndoe'
Full Example:
name: scm-github-full
project-type: multibranch
script-path: some.Jenkinsfile
scm:
- github:
api-uri: http://example.org/github
ssh-checkout:
credentials: 'ssh_secret'
repo: example-repo
repo-owner: example-owner
credentials-id: example-credential
branch-discovery: all
head-filter-regex: "(.*/master|.*/release/.*)"
head-pr-filter-behaviors:
head-pr-destined-regex:
branch-regexp: "foo/.*"
tag-regexp: "20\\..*"
head-pr-destined-wildcard:
branch-includes: "foo*"
tag-includes: "qaz*"
branch-excludes: "bar*"
tag-excludes: "*baz"
head-pr-originated-regex:
branch-regexp: "(foo/.*|bar/.*)"
tag-regexp: "1\\..*"
head-pr-originated-wildcard:
branch-includes: "qaz*"
tag-includes: "bar*"
branch-excludes: "baz*"
tag-excludes: "*qaz"
discover-pr-forks-strategy: both
discover-pr-forks-trust: everyone
discover-pr-origin: both
discover-tags: true
notification-context: 'jenkins.example.com/my_context'
property-strategies:
all-branches:
- suppress-scm-triggering: true
- pipeline-branch-durability-override: max-survivability
- trigger-build-on-pr-comment: "Ci build!"
- trigger-build-on-pr-review: true
- trigger-build-on-pr-update: true
build-strategies:
- all-strategies-match:
strategies:
- regular-branches: true
- skip-initial-build: true
- any-strategies-match:
strategies:
- change-request: {}
- tags: {}
- tags:
ignore-tags-newer-than: 1
ignore-tags-older-than: 7
- tags: {}
- change-request:
ignore-target-only-changes: true
- change-request: {}
- regular-branches: true
- skip-initial-build: true
- named-branches:
- exact-name:
name: 'test'
case-sensitive: true
- regex-name:
regex: 'test.*$'
case-sensitive: true
- wildcards-name:
excludes: 'testexclude'
includes: 'testinclude'
- named-branches:
- exact-name: {}
- regex-name: {}
- wildcards-name: {}
clean:
after: true
before: true
committer:
user: CI System
email: no-reply@ci.example.com
prune: true
local-branch: true
sparse-checkout:
paths:
- "path1"
- "path2"
- "path3"
shallow-clone: true
depth: 3
do-not-fetch-tags: true
disable-pr-notifications: true
refspecs:
- '+refs/heads/*:refs/remotes/@{remote}/*'
submodule:
disable: false
recursive: true
parent-credentials: true
timeout: 100
threads: 1
timeout: "100"
skip-notifications: true
use-author: true
wipe-workspace: true
lfs-pull: true
project_multibranch.property_strategies(xml_parent, data)
Configure Basic Branch Property Strategies.
Requires the Branch API Plugin.
Parameters
property-strategies (dict) --
Definition of property strategies. Either named-branches or all-branches may be specified,
but not both.
•
all-branches (list): A list of property strategy definitions
for use with all branches.
•
suppress-scm-triggering (bool): Suppresses automatic SCM
triggering (optional)
•
pipeline-branch-durability-override (str): Set a custom
branch speed/durability level. Valid values: performance-optimized,
survivable-nonatomic, or max-survivability (optional) Requires the
Pipeline Multibranch Plugin
•
trigger-build-on-pr-comment (str): The comment body to
trigger a new build for a PR job when it is received. This is compiled as
a case insensitive regular expression, so use ".*" to trigger a build on
any comment whatsoever. (optional) Requires the GitHub PR Comment Build
Plugin
•
trigger-build-on-pr-review (bool): This property will
cause a job for a pull request (PR-*) to be triggered immediately when a
review is made on the PR in GitHub. This has no effect on jobs that are
not for pull requests. (optional) Requires the GitHub PR Comment Build
Plugin
•
trigger-build-on-pr-update (bool): This property will
cause a job for a pull request (PR-*) to be triggered immediately when
the PR title or description is edited in GitHub. This has no effect on
jobs that are not for pull requests. (optional) Requires the GitHub PR
Comment Build Plugin
•
named-branches (dict): Named branches get different properties.
Comprised of a list of defaults and a list of property strategy exceptions for use
with specific branches.
•
defaults (list): A list of property strategy definitions
to be applied by default to all branches, unless overridden by an entry
in exceptions
•
suppress-scm-triggering (bool): Suppresses automatic SCM
triggering (optional)
•
pipeline-branch-durability-override (str): Set a custom
branch speed/durability level. Valid values:
performance-optimized, survivable-nonatomic, or
max-survivability (optional) Requires the Pipeline Multibranch
Plugin
•
trigger-build-on-pr-comment (str): The comment body to
trigger a new build for a PR job when it is received. This is
compiled as a case insensitive regular expression, so use ".*"
to trigger a build on any comment whatsoever. (optional)
Requires the GitHub PR Comment Build Plugin
•
trigger-build-on-pr-review (bool): This property will
cause a job for a pull request (PR-*) to be triggered
immediately when a review is made on the PR in GitHub. This has
no effect on jobs that are not for pull requests. (optional)
Requires the GitHub PR Comment Build Plugin
•
trigger-build-on-pr-update (bool): This property will
cause a job for a pull request (PR-*) to be triggered
immediately when the PR title or description is edited in
GitHub. This has no effect on jobs that are not for pull
requests. (optional) Requires the GitHub PR Comment Build Plugin
•
exceptions (list): A list of branch names and the property
strategies to be used on that branch, instead of any listed in defaults.
•
exception (dict): Defines exception
•
branch-name (str): Name of the branch to which these
properties will be applied.
•
properties (list): A list of properties to apply to
this branch.
•
suppress-scm-triggering (bool): Suppresses
automatic SCM triggering (optional)
•
pipeline-branch-durability-override (str): Set a
custom branch speed/durability level. Valid
values: performance-optimized,
survivable-nonatomic, or max-survivability
(optional) Requires the Pipeline Multibranch
Plugin
Delivery Pipeline View
The view delivery pipeline module handles creation of Delivery Pipeline views. To create a delivery
pipeline view specify delivery_pipeline in the view-type attribute to the Delivery Pipeline View
definition. Requires the Jenkins Delivery Pipeline Plugin.
View Parameters
• name (str): The name of the view.
• view-type (str): The type of view.
• description (str): A description of the view. (optional)
• filter-executors (bool): Show only executors that can execute the included views. (default
false)
• filter-queue (bool): Show only included jobs in builder queue. (default false)
•
components (list):
• name (str): Name of the pipeline, usually the name of the component or product.
• initial-job (str): First job in the pipeline.
• final-job (str): Final job to display in the pipeline view regardless of its downstream
jobs. (default '')
• show-upstream (bool): Whether to show upstream. (default false)
•
regexps (list):
• regexp (str): Regular expression to find initial jobs.
• show-upstream (bool): Whether to show upstream. (default false)
• aggregated-changes-grouping-pattern (str): Group changelog by regex pattern. (default '')
• allow-abort (bool): Allow cancelling a running job from the delivery pipeline view. (default
false)
• allow-manual-triggers (bool): Displays a button in the pipeline view if a task is manual (Build
other projects (manual step)) from Build Pipeline Plugin. (default false)
• allow-pipeline-start (bool): Allow starting a new pipeline run from the delivery pipeline view.
(default false)
• allow-rebuild (bool): Allow rerunning a task from the delivery pipeline view. (default false)
• link-relative (bool): Use relative links for jobs in this pipeline view to allow for easier
navigation. (default false)
• link-to-console-log (bool): Changes behaviour of task link in delivery pipeline view to go
directly to the console log. (default false)
• max-number-of-visible-pipelines (int): Limits the number of pipelines shown in the view,
regardless of how many pipelines are configured. A negative value will not enforce a limit.
• no-of-columns (int): Number of columns used for showing pipelines. Possible values are 1
(default), 2 and 3.
• no-of-pipelines (int): Number of pipelines instances shown for each pipeline. Possible values
are numbers from 1 to 50 (default 3).
• paging-enabled (bool): Enable pagination in normal view, to allow navigation to older pipeline
runs which are not displayed on the first page. Not available in full screen view. (default
false)
• show-absolute-date-time (bool): Show dates and times as absolute values instead of as relative
to the current time. (default false)
• show-aggregated-changes (bool): Show an aggregated changelog between different stages. (default
false)
• show-aggregated-pipeline (bool): Show an aggregated view where each stage shows the latest
version being executed. (default false)
• show-avatars (bool): Show avatars pictures instead of names of the people involved in a pipeline
instance. (default false)
• show-changes (bool): Show SCM change log for the first job in the pipeline. (default false)
• show-description (bool): Show a build description connected to a specific pipeline task.
(default false)
• show-promotions (bool): Show promotions from Promoted Builds Plugin. (default false)
• show-static-analysis-results (bool): Show different analysis results from Analysis Collector
Plugin. (default false)
• show-test-results (bool): Show test results as pass/failed/skipped. (default false)
• show-total-build-time (bool): Show total build time for a pipeline run. (default false)
• sorting (str): How to sort the pipelines in the current view. Only applicable when multiple
pipelines are configured in the same view. Possible values are 'none' (default), 'title' (sort
by title), 'failed_last_activity' (sort by failed pipelines, then by last activity),
'last_activity' (sort by last activity).
• update-interval (int): How often the pipeline view will be updated. To be specified in seconds.
(default 2)
Minimal Example:
name: Test pipeline
description: Test jobs created by JJB.
view-type: delivery_pipeline
components:
- name: Test
initial-job: Test-A
Full Example:
name: Test pipeline
description: Test jobs created by JJB.
view-type: delivery_pipeline
components:
- name: Test
initial-job: Test-A
regexps:
- regexp: ^Test-A
no-of-pipelines: 1
allow-manual-triggers: yes
show-total-build-time: yes
allow-rebuild: yes
allow-pipeline-start: yes
allow-abort: yes
paging-enabled: yes
link-to-console-log: yes
class view_delivery_pipeline.DeliveryPipeline(registry)
List View
The view list module handles creating Jenkins List views.
To create a list view specify list in the view-type attribute to the List View definition.
View Parameters
• name (str): The name of the view.
• view-type (str): The type of view.
• description (str): A description of the view. (default '')
• filter-executors (bool): Show only executors that can execute the included views. (default
false)
• filter-queue (bool): Show only included jobs in builder queue. (default false)
• job-name (list): List of jobs to be included.
• job-filters (dict): Job filters to be included. Requires View Job Filters
•
most-recent (dict)
most-recent
• max-to-include (int): Maximum number of jobs to include. (default 0)
• check-start-time (bool): Check job start time. (default false)
•
build-duration (dict)
build-duration
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• build-duration-type ('str'): Duration of the build. (default Latest)
• amount-type: ('str'): Duration in hours, days or builds. (default Hours)
• amount: ('int'): How far back to check. (default 0)
• less-than: ('bool'): Check build duration less than or more than. (default
True)
• build-duration-minutes: ('int'): Build duration minutes. (default 0)
•
build-trend (dict)
build-trend
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• build-trend-type ('str'): Duration of the build. (default Latest)
• amount-type: ('str'): Duration in hours, days or builds. (default Hours)
• amount: ('int'): How far back to check. (default 0)
• status: ('str'): Job status. (default Completed)
•
job-status (dict)
job-status
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• unstable ('bool'): Jobs with status unstable. (default False)
• failed ('bool'): Jobs with status failed. (default False)
• aborted ('bool'): Jobs with status aborted. (default False)
• disabled ('bool'): Jobs with status disabled. (default False)
• stable ('bool'): Jobs with status stable. (default False)
•
fallback (dict)
fallback
• fallback-type ('str'): Fallback type to include/exclude for all jobs in a
view, if no jobs have been included by previous filters. (default
REMOVE_ALL_IF_ALL_INCLUDED)
•
build-status (dict)
build-status
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• never-built ('bool'): Jobs that are never built. (default False)
• building ('bool'): Jobs that are being built. (default False)
• in-build-queue ('bool'): Jobs that are in the build queue. (default False)
•
user-relevence (dict)
user-relevence
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• build-count ('str'): Count of builds. (default AtLeastOne)
• amount-type: ('str'): Duration in hours, days or builds. (default Hours)
• amount: ('int'): How far back to check. (default 0)
• match-user-id ('bool'): Jobs matching user-id. (default False)
• match-user-fullname ('bool'): Jobs matching user fullname. (default False)
• ignore-case ('bool'): Ignore case. (default False)
• ignore-whitespace ('bool'): Ignore whitespace. (default False)
• ignore-non-alphaNumeric ('bool'): Ignore non-alphaNumeric. (default False)
• match-builder ('bool'): Jobs matching builder. (default False)
• match-email ('bool'): Jobs matching email. (default False)
• match-scm-changes ('bool'): Jobs matching scm changes. (default False)
•
regex-job (dict)
regex-job
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• regex-name ('str'): Regular expression name. (default '')
• regex ('str'): Regular expression. (default '')
•
job-tpye (dict)
job-type
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• job-type ('str'): Type of Job. (default hudson.model.FreeStyleProject)
•
parameter (dict)
parameter
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• name ('str'): Job name to match. (default '')
• value ('str'): Value to match. (default '')
• desc ('str'): Description to match. (default '')
• use-default-value ('bool'): Use default value. (default False)
• match-builds-in-progress ('bool'): Match build in progress. (default False)
• match-all-builds ('bool'): Match all builds. (default False)
• max-builds-to-match ('int'): Maximum builds to match. (default 0)
•
other-views (dict)
other-views
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• view-name ('str'): View name. (default select a view other than this one)
•
scm (dict)
scm
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• scm-type ('str'): Type of SCM. (default hudson.scm.NullSCM)
•
secured-job (dict)
secured-job
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
•
user-permissions (dict)
user-permissions
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• configure ('bool'): User with configure permissions. (default false)
• amount-type: ('bool'): User with build permissions. (default false)
• amount: ('bool'): User with workspace permissions. (default false)
• permission-check: ('str'): Match user permissions. (default MustMatchAll)
•
upstream-downstream (dict)
upstream-downstream
• include-upstream ('bool'): Jobs that match upstream. (default False)
• include-downstream ('bool'): Jobs that match downstream. (default False)
• recursive ('bool'): Jobs that are recursive. (default False)
• exclude-originals ('bool'): Jobs that are originals. (default False)
•
unclassified (dict)
unclassified
• match-type ('str'): Jobs that match a filter to include. (default
includeMatched)
• columns (list): List of columns to be shown in view.
• regex (str): . Regular expression for selecting jobs (optional)
• recurse (bool): Recurse in subfolders.(default false)
• status-filter (bool): Filter job list by enabled/disabled status. (optional)
Example:
name: list-view-name01
view-type: list
description: 'Sample description'
filter-executors: true
filter-queue: true
job-name:
- job-name-1
- job-name-3
- job-name-2
- Job-name-4
columns:
- status
- weather
- job
- last-success
- last-failure
- last-duration
- build-button
- last-stable
- robot-list
- find-bugs
- jacoco
- git-branch
- favorite
- schedule-build
- priority-sorter
- build-filter
- desc
- policy-violations
- member-graph-view
- built-on
- extra-tests-total
- extra-tests-failed
- extra-tests-passed
- extra-tests-skipped
- extra-tests-format-0
- extra-tests-format-1
- extra-build-parameters
- extra-build-description
- extra-last-user-name
- extra-workspace-link
- extra-configure-button
- extra-last-output
recurse: true
status-filter: false
Example:
name: regex-example
view-type: list
description: 'description'
columns:
- status
- weather
- job
- last-success
- last-failure
- last-duration
- extra-build-parameter: MY_PARAMETER
regex: (?!test.*).*
class view_list.List(registry)
Nested View
The view nested module handles creating Jenkins Nested views.
To create a nested view specify nested in the view-type attribute to the Nested View definition.
View Parameters
• name (str): The name of the view.
• view-type (str): The type of view.
• description (str): A description of the view. (default '')
• filter-executors (bool): Show only executors that can execute the included views. (default
false)
• filter-queue (bool): Show only included jobs in builder queue. (default false)
• views (list): The views to nest.
• default-view (str): Name of the view to use as the default from the nested ones. (the first one
by default)
• columns (list): List of columns to be shown in view. (default empty list)
Example:
name: NestedViewTest
view-type: nested
views:
- name: All
view-type: all
columns:
- status
- weather
class view_nested.Nested(registry)
Pipeline View
The view pipeline module handles creating Jenkins Build Pipeline views. To create a pipeline view
specify pipeline in the view-type attribute to the Pipeline View definition.
Requires the Jenkins Build Pipeline Plugin.
View Parameters
• name (str): The name of the view.
• view-type (str): The type of view.
• description (str): A description of the view. (optional)
• filter-executors (bool): Show only executors that can execute the included views. (default
false)
• filter-queue (bool): Show only included jobs in builder queue. (default false)
• first-job (str): Parent Job in the view.
• no-of-displayed-builds (str): Number of builds to display. (default 1)
• title (str): Build view title. (optional)
• linkStyle (str): Console output link style. Can be 'Lightbox', 'New Window', or 'This Window'.
(default Lightbox)
• css-Url (str): Url for Custom CSS files (optional)
• latest-job-only (bool) Trigger only latest job. (default false)
• manual-trigger (bool) Always allow manual trigger. (default false)
• show-parameters (bool) Show pipeline parameters. (default false)
• parameters-in-headers (bool) Show pipeline parameters in headers. (default false)
• starts-with-parameters (bool) Use Starts with parameters. (default false)
• refresh-frequency (str) Frequency to refresh in seconds. (default '3')
• definition-header (bool) Show pipeline definition header. (default false)
Example:
name: testBPview
view-type: pipeline
description: 'This is a description'
filter-executors: false
filter-queue: false
first-job: job-one
no-of-displayed-builds: 5
title: Title
link-style: New Window
css-Url: fake.urlfor.css
latest-job-only: true
manual-trigger: true
show-parameters: true
parameters-in-headers: true
start-with-parameters: true
refresh-frequency: 3
definition-header: true
Example:
name: testBPview
view-type: pipeline
first-job: job-one
class view_pipeline.Pipeline(registry)
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 invoking cmake --build <dir>) (default false).
•
arguments (str) -- Specify arguments to pass to the
build tool or cmake (separated by spaces). Arguments may contain
spaces if they are enclosed in double quotes. (optional)
•
environment-variables (str) -- Specify extra
environment variables to pass to the build tool as key-value pairs
here. Each entry must be on its own line, for example:
DESTDIR=${WORKSPACE}/artifacts/dir
KEY=VALUE
Version 1.x
Parameters available only to versions 1.x of the plugin
• build-dir (str): The directory where the project will be built in. Relative to the
workspace directory. (optional)
• install-dir (str): The directory where the project will be installed in, relative to the
workspace directory. (optional)
• build-type (list): Sets the "build type" option. A custom type different than the default
ones specified on the CMake plugin can also be set, which will be automatically used in
the "Other Build Type" option of the plugin. (default "Debug")
Default types present in the CMake plugin
• Debug
• Release
• RelWithDebInfo
• MinSizeRel
• make-command (str): The make command (default "make").
• install-command (arg): The install command (default "make install").
• custom-cmake-path (str): Path to cmake executable. (optional)
• clean-install-dir (bool): If true, delete the install dir before each build (default
false).
Example (Versions 2.x):
builders:
- cmake:
source-dir: 'path/to/source'
working-dir: 'path/to/build'
install-dir: 'path/to/install'
build-type: 'CustomReleaseType'
generator: 'NMake Makefiles'
installation-name: 'CMake custom install'
preload-script: 'path/to/source/cmake.preload'
other-arguments: '-DCMAKE_FIND_ROOT_PATH="path/to/something/else"'
clean-build-dir: true
build-tool-invocations:
- use-cmake: true
arguments: 'clean'
environment-variables: |
DESTDIR=${WORKSPACE}/artifacts/dir
URL=http://www.example.org/
- use-cmake: false
arguments: 'test'
environment-variables: |
RESTRICT="TRUE"
TARGET="NONE"
Example (Versions 1.x):
builders:
- cmake:
source-dir: 'path/to/source'
build-dir: 'path/to/build'
install-dir: 'path/to/install'
build-type: 'CustomReleaseType'
generator: 'NMake Makefiles'
make-command: '/usr/bin/make'
install-command: 'make new-install'
preload-script: 'path/to/source/cmake.preload'
other-arguments: '-DCMAKE_FIND_ROOT_PATH="path/to/something/else"'
custom-cmake-path: '/usr/bin/cmake'
clean-build-dir: true
clean-install-dir: true
conditional-step()
Conditionally execute some build steps.
Requires the Jenkins Conditional BuildStep Plugin.
Depending on the number of declared steps, a Conditional step (single) or a Conditional steps
(multiple) is created in Jenkins.
Parameters
• condition-kind (str) -- Condition kind that must be verified before the steps are
executed. Valid values and their additional attributes are described in the conditions
table.
• on-evaluation-failure (str) -- What should be the outcome of the build if the evaluation
of the condition fails. Possible values are fail, mark-unstable, run-and-mark-unstable,
run and dont-run. (default 'fail').
• steps (list) -- List of steps to run if the condition is verified. Items in the list can
be any builder known by Jenkins Job Builder.
───────────────────────────────────────────────────────────────────────────
Condition kind Description
───────────────────────────────────────────────────────────────────────────
always Condition is always verified
───────────────────────────────────────────────────────────────────────────
never Condition is never verified
───────────────────────────────────────────────────────────────────────────
boolean-expression Run the step if the expression
expends to a representation of true
condition-expression
Expression to
expand
(required)
───────────────────────────────────────────────────────────────────────────
build-cause Run if the current build has a
specific cause
cause The cause why
the build was
triggered.
Following
causes are
supported -
USER_CAUSE
build
was
triggered
by a
manual
interaction.
(default)
SCM_CAUSE
build
was
triggered
by a
SCM
change.
TIMER_CAUSE
build
was
triggered
by a
timer.
CLI_CAUSE
build
was
triggered
by via
CLI
interface
REMOTE_CAUSE
build
was
triggered
via
remote
interface.
UPSTREAM_CAUSE
build
was
triggered
by an
upstream
project.
Following
supported if
XTrigger
plugin
installed:
FS_CAUSE
build
was
triggered
by a
file
system
change
(FSTrigger
Plugin).
URL_CAUSE
build
was
triggered
by a
URL
change
(URLTrigger
Plugin)
IVY_CAUSE
build
triggered
by an
Ivy
dependency
version
has
change
(IvyTrigger
Plugin)
SCRIPT_CAUSE
build
was
triggered
by a
script
(ScriptTrigger
Plugin)
BUILDRESULT_CAUSE
build
was
triggered
by a
result
of
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: │ │ │
│ │ │
--
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.
The Builder
The Builder class manages Jenkins jobs. It's responsible for creating/deleting/updating jobs and can be
called from your application. You can pass it a filename or an open file-like object that represents your
YAML configuration. See the jenkins_jobs/builder.py file for more details.
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(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(job_data)
This method is called before any XML is generated. By overriding this method, a module may
arbitrarily modify a data structure which will probably be the JJB YamlParser's
intermediate data representation. If it has changed the data structure at all, it must
return True, otherwise, it must return False.
Parameters
job_data (dict) -- the intermediate representation of job data loaded from JJB Yaml
files without variables interpolation or other yaml expansions.
Return type
bool
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.registry.ModuleRegistry(jjb_config, plugins_list=None)
dispatch(component_type, xml_parent, component, template_data={}, job_data=None)
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 (str) -- the name of the component (e.g., builder)
• parser (YAMLParser) -- the global YAML Parser
• xml_parent (Element) -- the parent XML element
• component -- component definition
• template_data (dict) -- values that should be interpolated into the component
definition
• job_data (dict) -- full job 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.
get_plugin_info(plugin_name)
Provide information about plugins within a module's impl of Base.gen_xml.
The return value is a dictionary with data obtained directly from a running Jenkins
instance. This allows module authors to differentiate generated XML output based on
information such as specific plugin versions.
Parameters
plugin_name (str) -- Either the shortName or longName of a plugin as see in a query
that looks like: http://<jenkins-hostname>/pluginManager/api/json?pretty&depth=2
During a 'test' run, it is possible to override JJB's query to a live Jenkins instance by
passing it a path to a file containing a YAML list of dictionaries that mimics the plugin
properties you want your test output to reflect:
jenkins-jobs test -p /path/to/plugins-info.yaml
Below is example YAML that might be included in /path/to/plugins-info.yaml.
- longName: 'Jenkins HipChat Plugin'
shortName: 'hipchat'
version: "0.1.8"
• genindex
• modindex
• search
AUTHOR
Jenkins Job Builder Maintainers
COPYRIGHT
2021, Jenkins Job Builder Maintainers
3.11.0 Dec 17, 2021 JENKINS-JOBS(1)