JENKINS-JOBS(1)
🎀 NAME 🎀
hey bestie, welcome to JENKINS-JOBS(1) — this is the Jenkins Job Builder documentation and honestly it's giving main character energy 💅
jenkins-jobs — Jenkins Job Builder Documentation, fr fr 👑
so like, here's the tea ☕: Jenkins Job Builder takes simple descriptions of Jenkins (https://www.jenkins.io/) jobs in YAML (https://yaml.org) or JSON (http://json.org/) format and uses them to configure Jenkins. and the best part?? you can keep your job descriptions in human readable text format in a version control system so making changes and auditing is so much easier 🧚✨ It also has a flexible template system, so creating many similarly configured jobs is easy — iconic behaviour honestly 🫶
to install:
$ pip install --user jenkins-job-builderonline documentation:
🦋 DEVELOPERS 🦋
okay future maintainer, this part is for you 💜
bug report:
repository:
cloning:
git clone https://opendev.org/jjb/jenkins-job-builder.gitinstall pre-commit from https://pre-commit.com/#intro in order to run some minimal testing on your commits. yes bestie, do it 🙈
a virtual environment is recommended for development, no cap. 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:
please do not submit GitHub pull requests, they will be automatically closed 😭 like they literally get auto-closed bestie, don't do it
mailing list:
IRC:
#openstack-jjbon OFTC
more details on how you can contribute is available on our wiki at:
✨ WRITING A PATCH ✨
we ask that all code submissions be pep8 (https://pypi.org/project/pep8) and pyflakes (https://pypi.org/project/pyflakes) clean 🧼 like spotless. the easiest way to do that is to run tox (https://tox.wiki/en/latest/) 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. it's called ✨synergy✨ and we love her
🧪 UNIT TESTS 🧪
unit tests have been included and are in the tests folder. many unit test 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 py38unit tests could be run in parallel, using pytest-parallel pytest plugin:
tox -e py38 -- --workers=auto- Note: View
tox.inito 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. iykyk 🫶
🍓 INSTALLING WITHOUT SETUP.PY 🍓
for YAML support, you will need libyaml (https://pyyaml.org/wiki/LibYAML) installed, bestie.
Mac OS X:
$ brew install libyamlthen install the required python packages using pip (https://pypi.org/project/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. let's gooo 🚀
- Clone the repository (https://opendev.org/jjb/jenkins-job-builder/) to get the JJB job definition examples (https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests)
- The Installation (<>) can be either from pypi (https://pypi.org/project/jenkins-job-builder/) (released version) or from the clone (master).
usage of the commands below assumes that you are at the root of the cloned directory. important bestie 📌
🔥 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. vibe check your XML first, always ✨
test a YAML job definition:
jenkins-jobs test tests/yamlparser/job_fixtures/templates002.yamlthe 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/job_fixtures/templates002.yamlthe output directory will contain files with the XML configurations. obsessed 😍
💜 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/job_fixtures/templates002.yamlthe 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 (<#updating-jobs>) for more information. ngl this one bites people, be careful bestie
🦋 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.jsonthe above command just uses a simple job definition. you can also convert any of the YAML examples to JSON and feed that to JJB. flexible queen 💅
🎀 Use Case 4: Deleting a job 🎀
to delete a job:
jenkins-jobs --conf etc/jenkins_jobs.ini-sample delete simplethe above command deletes the job simple from the Jenkins master. bye bye jobie 👋
⭐ 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.yamlto run JJB update using the plugins_info.yaml:
jenkins-jobs update -p plugins_info.yaml ./myjobsplease refer to the jenkins-jobs Command Reference (<#command-reference>) and the Job Definitions (<>) pages for more details 🫶
💅 INSTALLATION 💅
to install Jenkins Job Builder from source, run:
pip install git+https://opendev.org/jjb/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-builderthe OpenStack project uses Puppet to manage its infrastructure systems, including Jenkins. if you use Puppet, you can use the OpenStack Jenkins module (https://opendev.org/opendev/puppet-jenkins/src/branch/master) to install Jenkins Job Builder. puppet girlies stay winning 🧚
📚 Documentation 📚
documentation is included in the doc folder. to generate docs locally execute the command:
tox -e docsthe 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_PASSENVto 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 py38- Note: View
tox.inito run tests on other versions of Python.
🌈 Test Coverage 🌈
to measure test coverage, execute the command:
tox -e cover💖 CONFIGURATION FILE 💖
Okay so you installed everything, iconic, but bestie you are not done yet — you need a config file or jenkins-jobs is just gonna stand there like 🧍. By default, jenkins-jobs goes looking for ~/.config/jenkins_jobs/jenkins_jobs.ini, then <script directory>/jenkins_jobs.ini, then /etc/jenkins_jobs/jenkins_jobs.ini (in that exact order, no skipping), but you're totally allowed to point it somewhere else when you run jenkins-jobs. The file should look like this:
[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 you set this toTrue, Jenkins Job Builder will not use any cache. Like, zero. None. 💅keep_descriptions— By defaultjenkins-jobswill overwrite the jobs descriptions even if no description has been defined explicitly. When you set this option toTrue, that behaviour changes and it will only overwrite the description if you specified it in the yaml.Falseby default.include_path— (Optional) You can set this to a':'delimited list of paths, and jenkins job builder will search those for any files specified by the custom application yaml tagsinclude,include-rawandinclude-raw-escape. 🦋recursive— (Optional) If set toTrue, jenkins job builder will search for job definition files recursively.exclude— (Optional) If you set this to a list of values separated by':', these paths get excluded from the list of paths to be processed when searching recursively. Here's the tea: values containing no/get matched against directory names at all levels, ones starting with/are considered absolute, and anything else with a/somewhere other than the start is considered relative to the starting path. 🫶allow_duplicates— (Optional) By defaultjenkins-jobswill abort when a duplicate macro, template, job-group or job name shows up, because it genuinely cannot figure out which one is the correct one to use 😭. When this option is set toTrue, only a warning is emitted instead.allow_empty_variables— (Optional) When expanding strings, by defaultjenkins-jobswill raise an exception if there's a key in the string that has not been declared in the input YAML files. Setting this option toTruewill replace it with the empty string, so you can use those strings without having to define every single key it might be using. Game changer.print_job_urls— (Optional) If set toTrueit will print full jobs urls while updating jobs, so the user can be sure which instance was updated. You can click the link and go directly to that job, cute.Falseby default.retain_anchors— (Optional) If set toTrue, YAML anchors will be retained across files, allowing jobs to be composed from bits of YAML defined in separate files. Note 👏 this 👏 means 👏 the order of processing files matters —jenkins-jobsloads 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 namedfoo.ymlthey will be accessible inqux.ymlbut not inbar.yml. They will also be accessible inmydir/bar.ymlandmydir/qux.yml.Falseby 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-onlyor--views-onlyCLI options. (Valid options:jobs,views,all)filter_modules— (Optional) A space-separated set of strings which of names of additional modules to load Jinja2 filters from when templating YAML objects. Heads up, the modules must be in the Python path. To learn about writing custom Jinja2 filters, please see the Jinja2 Documentationhttps://jinja.palletsprojects.com/en/latest/api/#writing-filters
💜 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. Yes bestie, that's a whole checklist, do all of it.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-jobswill skip querying for plugin information.Falseby 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 Documentationhttps://developer.atlassian.com/server/hipchat/about-the-hipchat-rest-api/
🍓 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. Fancy experimental vibes, periodt. 🧚
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's discussed in the next section. Patience, bestie. 💅
✨ Test Mode ✨
Once you have a configuration defined, you can run the job builder in test mode. Vibe check first, always.
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.yamlYou can also pass JJB a directory containing multiple job definition files:
jenkins-jobs test /path/to/defs -o /path/to/outputwhich 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-xmlthe 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. Obsessed with a clean diff, honestly.
🔥 Updating Jobs 🔥
When you're satisfied with the generated XML from the test, you can run:
jenkins-jobs update /path/to/defswhich 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. 💀 It simply does not know. It cannot know.
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 Foo2You 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/defsTo 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/projectThis 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. It's giving flexible, it's giving modular. 👑
🦋 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/globalsJJB will search defs/ci_jobs, defs/release_jobs, globals/macros and globals/templates in addition to the defs and globals trees. It goes deep, no cap. 🌟
Excluding Paths</p> 🚫📂
Okay so bestie, imagine you've got a whole ✨complex✨ tree of jobs and some of them get managed differently, but you do not wanna sit there typing out every single path like a Victorian orphan. Good news: the recursive path processing is unlocked by design, and it supports excluding paths based on absolute paths, relative paths and patterns. Slay. Example time:
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/globalsSo what's happening here: 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. 🧚
And here's how it tells them apart (iykyk):
- Absolute paths are denoted by starting from the root
- Relative by containing the path separator
- Patterns by having neither
Patterns use simple shell globing to match directories. Periodt. 💅
Deleting Jobs/Views 🗑️💀
Jenkins Job Builder supports deleting jobs and views from Jenkins. yes, actually deleting them, no takebacks.
To delete a specific job:
jenkins-jobs delete Foo1To delete a list of jobs or views, simply pass them as additional arguments after the command:
jenkins-jobs delete Foo1 Foo2Wanna delete only views or only jobs? Just add the argument --views-only or --jobs-only after the command:
jenkins-jobs delete --views-only Foo1
jenkins-jobs delete --jobs-only Foo1The update command includes a delete-old option to remove obsolete jobs:
jenkins-jobs update --delete-old /path/to/defsObsolete 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. 😭 like genuinely.
To delete all jobs and views:
jenkins-jobs delete-allJust the jobs? 👇
jenkins-jobs delete-all --jobs-onlyJust the views? 👇
jenkins-jobs delete-all --views-onlyGlobbed Parameters 🌟
Jenkins job builder supports globbed parameters to identify jobs from a set of definition files. Quick heads up tho: 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 [2]. Which is honestly giving gatekeeping energy 🙄. 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. Problem solved, iconic behavior fr fr. 🫶
To generate a plugins info, using an account with Administrator rights:
jenkins-jobs get-plugins-info -o plugins_info.yamlTo run JJB update using the plugins_info.yaml:
jenkins-jobs update -p plugins_info.yaml ./myjobsCommand Reference 📖👑
Here's the whole usage dump, untouched, exactly as it is. No notes. 💅
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
options:
-h, --help show this help message and exit
--conf CONF configuration file [JJB_CONF]
-l, --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, -s SECTION The Jenkins server ini section to use. Defaults to
'jenkins' [JJB_SECTION]
--user, -u USER The Jenkins user to use for authentication. This
overrides the user specified in the configuration
file. [JJB_USER]
--password, -p PASSWORD
Password or API token to use for authenticating
towards Jenkins. This overrides the password specified
in the configuration file. [JJB_PASSWORD]And the test subcommand 🌸:
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)
options:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
--config-xml use alternative output file layout using config.xml
files
-p, --plugin-info PLUGINS_INFO_PATH
path to plugin info YAML file
-o OUTPUT_DIR path to output XMLThe update subcommand 🔥:
usage: jenkins-jobs update [-h] [-r] [-x EXCLUDE] [--delete-old]
[-p PLUGINS_INFO_PATH] [--workers N_WORKERS]
[--existing-only] [--enabled-only] [-j | -v]
[path] [names ...]
positional arguments:
path colon-separated list of paths to YAML files or
directories
names name(s) of job(s)
options:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
--delete-old delete obsolete jobs
-p, --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
--enabled-only update enabled jobs only
-j, --jobs-only update only jobs
-v, --views-only update only viewsdelete-all 🗑️ (the jump-scare command):
usage: jenkins-jobs delete-all [-h] [-r] [-x EXCLUDE] [-j] [-v] [-f]
options:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-j, --jobs-only delete only jobs
-v, --views-only delete only views
-f, --force Do not ask interactively for confirmation. Ba
cautious!Not me pointing at that -f, --force line. It literally says Ba cautious! and honestly? valid. 🙈
delete 💅:
usage: jenkins-jobs delete [-h] [-r] [-x EXCLUDE] [-p PATH] [-j] [-v]
name [name ...]
positional arguments:
name name of job
options:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-p, --path PATH colon-separated list of paths to YAML files or
directories
-j, --jobs-only delete only jobs
-v, --views-only delete only viewslist 👑:
usage: jenkins-jobs list [-h] [-r] [-x EXCLUDE] [-p PATH] [names ...]
positional arguments:
names name(s) of job(s)
options:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-p, --path PATH path to YAML file or directoryAnd finally get-plugins-info 🔌:
usage: jenkins-jobs get-plugins-info [-h] [-o PLUGINS_INFO_FILE]
options:
-h, --help show this help message and exit
-o, --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 theXDG_CACHE_HOMEenvironment 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. no literally, whatever way, it's your world 🌈
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. cute and efficient. 🦋
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. stay with me bestie, we're going in order. ⭐
Job 💼
The most straightforward way to create a job is simply to define a Job in YAML. It looks like this:
- job:
name: job-nameThat's lowkey not enough tho — you're gonna want to add some actions like Builders <#builders>, and maybe Publishers <#publishers> too. Those ones get their own spotlight later, promise. 🫶
These next things are the job parameters that are common to every type of Jenkins job. Like, the universal vibe. ✨
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: -1Job Parameters
project-type— defaults to"freestyle", but you can also drop"maven","multijob","flow","pipeline"or"externaljob"in there. Pick your fighter. 💅defaults— picks which set of Defaults this job uses, and it defaults toglobal. If you've got values that all your jobs share, make one global Defaults object to hold them and boom, no more configuring every single job by hand. If some jobs should NOT touch the global defaults, use this field to point them at a different set. 🌈description— the lil description for the job. By default it gets!-- Managed by Jenkins Job Builderslapped on it.disabled— a boolean for whether this job is disabled in Jenkins or not. Defaults tofalse(so yeah, the job runs — it's enabled, bestie). 💖display-name— an optional name shown for the project all over the Jenkins web GUI instead of the real job name. Heads up tho: thejenkins_jobstool cannot fully remove this trait once it's set, so be careful setting it. Setting it to the same string as the job's name is an effective un-set workaround. Or yk, you can clear it manually from the Jenkins web interface. 🙈concurrent— boolean for whether Jenkins is allowed to run this job concurrently. Defaults tofalse.workspace— path for a custom workspace. Defaults to the Jenkins default configuration.folder— this attribute is the alternative to using'<path>/<name>'as the job name to say which Jenkins folder the job should be uploaded to. Needs the Jenkins CloudBees Folders Plugin <https://plugins.jenkins.io/cloudbees-folder> tho. 🎀child-workspace— path for a child custom workspace. Defaults to the Jenkins default configuration. This one is only valid for matrix type jobs, fyi.quiet-period— number of seconds to wait between consecutive runs of this job. Defaults to0.block-downstream— boolean for whether this job must block while downstream jobs are running. Downstream jobs are figured out transitively. Defaults tofalse.block-upstream— boolean for whether this job must block while upstream jobs are running. Upstream jobs are figured out transitively too. Defaults tofalse.auth-token— an authentication token that lets new builds get triggered by hitting a special predefined URL. Only the people who know the token can trigger builds remotely. Secret lil handshake. 🤫retry-count— if a build fails to checkout from the repository, Jenkins retries this many times before it gives up entirely.node— restricts where this job can run. If there's a group of machines the job can build on, you can name that label as the node to tie onto, which makes Jenkins build the job on any of the machines rockin' that label. For matrix projects, this one only restricts where the parent job runs. 👑logrotate— the Logrotate section lets you automatically yeet old build history. It adds thelogrotateattribute to the Job definition. All the logrotate attributes default to"-1"(aka keep forever). Deprecated on jenkins>=1.637: use thebuild-discarderproperty instead. ⚠️jdk— the name of the jdk to use.raw— if present, this section should hold a singlexmlentry. That XML gets inserted at the top-level of the Job definition. 🪄
Job Template
Okay so if you need a bunch of jobs that are like, nearly identical — maybe they only differ in their names, SCP targets, whatever — then you can use a Job Template to lay out the particulars of the job, and then a Project to actually realize that job with the right variable substitution. Any variables you don't specify at the project level get inherited from the Defaults. Inheritance, but make it slay. 💖
A Job Template has the same syntax as a Job, but plot twist: you can add variables anywhere in the definition. Variables are marked by wrapping them in braces, so {name} will substitute the variable name. When you're using a variable inside a string field, it's good practice to wrap the whole string in quotes — even if YAML syntax doesn't strictly need it — because the value of the variable might need quotes after substitution. And in that rare situation where you gotta encode braces inside literals inside a template (like a shell function definition in a builder), doubling the braces stops them from being read as a template variable. 🧚
You must include a variable in the name field of a Job Template, otherwise every instance would end up with the same name. Like:
- job-template:
name: '{name}-unit-tests'That won't create any job in Jenkins by itself, but it will define a template you can use to create jobs with a Project definition. Its name will depend on what you feed the Project. ✨
If you use the variable {template-name}, the name of the template itself (like {name}-unit-tests in the example above) gets substituted in. Super handy when you need to trace a job back to its template. 🔍
Sometimes it's useful to keep the same job name format even when the template contents might vary. Ids give you a mechanism to support those kinds of use cases, plus they make referencing templates way easier when the name contains the more complex substitution with default values. 👑
Default Values for Template Variables
To make templates with tons of substitutes reusable — where in most cases you need the same value or no value at all — you can specify defaults for the variables right inside the templates themselves. 💅
There are 2 ways JJB lets us define defaults for a parameter in a job-template.
- 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's 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's not passed in by a project using the template.
And you can do the same thing in Macro definitions too. 🎀
- Using
{var|default}
In this method we can define the default right with the definition of the variable. For example:
- job-template:
name: '{project-name}-verify'
parameters:
- string:
name: BRANCH
default: '{branch|master}'However, this method falls apart if we need to use the same JJB variable in more than one place, because then we'd 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}'You 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}"Using a default value for a variable used in the name would be uncommon — unless it was in addition to another variable. But you can use Ids to simplify those kinds of use cases. ✨
Project
The whole 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 can be specified, and they'll be available for variable substitution in the job template. Any job templates listed under jobs: get 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, like this:
If a variable is a list, bestie, the job template gets realized once for every value in that list. And if you've got multiple lists? Oh we're getting ✨math✨ — the template gets realized with the cartesian product of those values. No cap. Like this:
- project:
name: project-name
pyver:
- 26
- 27
jobs:
- '{name}-{pyver}'Now, if there are templates being realized that differ only in the variable used for their name (so, not a use case for job-specific substitutions, okurrr), you can spec additional variables for project variables. Watch:
- 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 combos to exclude from the matrix with the exclude keyword, so you just don't generate jobs for those combos. You can specify all the variables of the combo or only a subset — and if you do a subset, any value of the omitted variable will match. It's giving flexibility 💅
- 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}"That example above will omit these jobs:
build-axe1val1-axe2val1-axe3val2build-axe1val1-axe2val2-axe3val1build-axe1val2-axe2val2-axe3val1
To get the same result without the exclude tag, you'd have to do something a lil more complicated — and it gets more complicated for each dimension in the combination 😭 For that 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 👯
So if you've got 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'd normally use a Job Template, and all the Job Templates inside it get realized. Bestie, look:
- 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'That would cause the jobs project-name-unit-tests and project-name-perf-tests to be created in Jenkins. Iconic ✨
👀 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. Looks like this:
- view:
name: view-name
view-type: listHeads up bestie: Views are processed differently than Jobs, so they will not work inside a Project or a Job Template. Periodt. 💀
🦋 View Template 🦋
This lets views also be configured via templates, just like job-templates. Super useful when you've got multiple views defined with basically the same config 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 — think 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 right now to show off how Macros work. This snippet tells Jenkins to execute make test as part of the job:
- job:
name: foo-test
builders:
- shell: 'make test'Now if you wanted to define a macro (which, ngl, won't save much typing in this case, but could still be useful to centralize the definition of a commonly repeated task), the config would look like:
- builder:
name: make-test
builders:
- shell: 'make test'
- job:
name: foo-test
builders:
- make-testThis lets you create complex actions (and even sequences of actions!) in YAML that look like first-class Jenkins Job Builder actions. But listen: not every attribute supports Macros — check the documentation for the action before you try to use a Macro for it. No cap, fr fr.
Macros can take parameters too, so you can define a generic macro and more specific ones without duplicating 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"Then the <builders /> section of the generated job shows 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>
</builders>So as you can see, the specialized macro addtwo reused the definition from the generic macro add. Reuse queen 👑
📁 Folders 📁
Jenkins supports organising jobs, views, and slaves using a folder hierarchy. This allows for easier separation of access, plus credentials and resources which can be assigned to only be available for a specific folder. It's giving organization ✨
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
folderattribute on a job definition, via a template, or through Defaults.
Supporting both an attribute and use of it directly in job names lets teams have all jobs using their defaults automatically use a top-level folder — while still allowing them to additionally nest jobs for their own preferences 🫶
Job Name Example:
- job:
name: python-jobs/tox-py27
builders:
- shell: |
tox -e py27Folder Attribute Example:
# 'folders' attribute from defaults should be used (combined with job name) for jobs.
- 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 for when you wish to use the same naming format for multiple templates. This lets you 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 it possible to change the template output name without impacting references. Obsessed 😍
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 🌈 (yes, the unhinged one)
okay so. it is possible — but not recommended — to use raw inside a module to inject raw xml straight into your job configs. 💀
When is that even a thing? When there's no appropriate module for a Jenkins plugin, or when the module just doesn't behave the way you expect it to. (we've all been there.)
For example:
wrappers:
- raw:
xml: |
<hudson.plugins.xvnc.Xvnc>
<takeScreenshot>true</takeScreenshot>
<useXauthority>false</useXauthority>
</hudson.plugins.xvnc.Xvnc>That right there is the raw way of adding support for the xvnc wrapper. slay, but also, careful.
To get the appropriate xml to use, you'd need to create/edit a job in Jenkins and grab the relevant raw xml segment from the config.xml. (yes, manual labour. i know. 😭)
The xml string can refer to variables just like anything else, and as such it can be parameterized like anything else. flexible.
You can use raw in most locations — the following example shows them all, 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 userawplease consider submitting a patch to add or fix the module that will remove your need to useraw. 🫶 yes bestie, the manpage itself is asking you to go fix the module. main character behaviour fr fr.
Defaults 🎀
Defaults collect job attributes (including actions) and will supply those values when the job is created — unless a value in the Job definition supersedes them. If a set of Defaults is specified with the name global, that one gets used by all Job, Job Template and Macro definitions... unless they specify a different Default object with the defaults attribute. okay? 💅
For example:
- defaults:
name: global
description: 'Do not edit this job through the web!'That will set the job description for every job created. one little block, all the jobs. iconic.
You can also 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. ✨ two jobs, zero extra typing.
And in job templates, you can also reference a variable {template-name} in any value, and it will be substituted by the name of the current job template being processed. that's your little self-referential moment, go off. 🦋
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. That triggers the use of code that retains the original object type. (so it doesn't get flattened into a sad little string. thank u.)
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. 🧚 nested vibes.
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 behaviour 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 = TrueWill prevent JJB from failing if there are any non-initialized variables used, and replace them with the empty string instead. no more crash-out. 🫶
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 users of job-templates can override variables defined in the job-template. the drama of precedence, let's go.
Variable priorities for each definition type are as follows:
job-groupprojectjob-templatedefaults
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 — because it has the lowest precedence when JJB is deciding where to pull from. 💀 lowest on the totem pole, bestie.
On the other side of the spectrum, job-groups has the highest precedence. Which unfortunately means that 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 override it as follows:
- project:
name: foo
jobs:
- '{project-name}-merge'
- '{project-name}-verify'
branch: masterThis is the standard way that most folks use, and it will set branch: master for every job-template in the list. the classic. 🎀
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: masterIn this case the verify job will get the value master, but the merge job will instead get the branch value production. specificity wins, always.
Yaml Anchors & Aliases 🦋
The yaml specification supports anchors and aliases (https://yaml.org/spec/1.2.2/#3222-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:
- myjobThe anchors and aliases (https://yaml.org/spec/1.2.2/#3222-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. ⚠️ same name twice = chaos, no cap.
A simple example can be seen in the specs full length example (https://yaml.org/spec/1.2.2/#25-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_defaultsWhich 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 ✨
ok so plot twist bestie: you can make your own application-specific yaml tags 💖. They're there to add lil enhancements when the yaml config gets read in. no cap.
Action Tags
these ones are the glow-up tags 🦋. They let you keep your data in one layout in the source yaml (because it's convenient and/or clearer to look at), and then have it flipped into a different format before your target module ever sees it. The whole point? So we don't have to make every single module in JJB able to support a million input formats. that's a lot of work and nobody has the time 💅.
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 then it hands back a single string to be consumed by whatever module option asked for it.
Why do we love this? Because it lets you keep chunks of data in a nice tidy list structure for easy reviewing and maintenance ✨, while the yaml parser does the converting to a string for you so it can be consumed as any argument for modules. The main use case they're expecting is letting generic plugin data — stuff like shell properties — get populated from a list construct, which the yaml parser turns into one single string. Otherwise you'd have to support that inside the module code itself, which would mean building a whole templating engine, Jinja-style. and that's just a lot. 🙈
Generic Example:
- job:
name: sample-job
builders:
- shell:
- string-with-comma: !join:
- ','
-
- item1
- item2
- item3
- string-with-space: !join:
- ' '
-
- item1
- item2
- item3Environment 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}}"ok so real talk: you could also use this mechanism on items where the module already supports delimiters — but consider that a bug 💀. The existing code should totally be able to handle being handed a list plus a delimiter and just do the conversion for you. So if you find a module that takes arguments with delimiters and the current JJB codebase won't accept a list for it, you can use !join: as a temporary workaround instead of writing out strings that are so long they scroll into next week 🌈. no cap.
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: fooInclusion Tags
these are the bring-your-own-file tags 🎀. They let you pull in arbitrary files as a way of keeping big blocks of data managed separately from your yaml job configs. A specific use case is inlining scripts that live in their own separate files — but honestly you can also use these tags to make using macros or job templates way simpler ✨.
The tag !include: will treat the following string as a file, and that file should be parsed as yaml configuration data 📄.
Example:
- job:
name: test-job-1
builders:
!include: include001.yaml.inc
contents of include001.yaml.inc:
- copyartifact: ©tarball
project: foo
filter: "*.tar.gz"
target: /home/foo
which-build: last-successful
optional: true
flatten: true
do-not-fingerprint: true
parameter-filters: PUBLISH=true
- copyartifact:
<<: *copytarball
project: bar
which-build: specific-build
build-number: 123
- copyartifact:
<<: *copytarball
project: baz
which-build: upstream-buildThe tag !include-raw-expand: will treat the given string — or list of strings — as filenames to be opened as one or more data blob 🫶. That blob gets read straight into the calling yaml construct with no further parsing. And heads up: any data in a file included through this tag will be treated as string data.
It will expand variables inside the file. so if your file has curly braces in it, you should double them 🙈. Or — plot twist — you can just use the tag !include-raw-verbatim: instead, which does not substitute variables. iconic.
Examples:
- job-template:
name: test-include-raw-verbatim-job-{num}
builders:
- shell:
!include-raw-verbatim: include-raw-hello-world.sh
- shell:
!include-raw-verbatim: include-raw-vars.sh
- project:
name: test-job-template-1
num: 1
jobs:
- 'test-include-raw-verbatim-job-{num}'
contents of include-raw-hello-world.sh:
#!/bin/bash
#
# Sample script showing how the yaml !include-raw-verbatim: 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-raw-vars.sh:
#!/bin/bash
#
# sample script to check that variables aren't expanded
# when using the !include-raw-verbatim: application yaml tag VAR1="hello"
VAR2="world"
VAR3="${VAR1} ${VAR2}"
[[ -n "${VAR3}" ]] && {
# this next section is executed as one
echo "${VAR3}"
exit 0
}And if you'd rather hand it a whole list of files instead of one? say less. Using a list of files:
- job-template:
name: test-job-include-raw-{num}
builders:
- shell:
!include-raw-verbatim:
- include-raw-hello-world.sh
- include-raw-vars.sh
- project:
name: test-job-template-1
num: 1
jobs:
- 'test-job-include-raw-{num}'Bestie, real talk: for all the multi file includes, the files are simply appended using a newline character. That's it. That's the whole vibe. no merging, no remixing, just stacking them one after another 💅
You can also use variables in included file paths. ✨ 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-verbatim: echo_vars_{version}.shand with variable substitution inside included files (the plot thickens fr):
# Variables should be substituted in included raw files
# when their path themselves contains variables.
- job-template:
name: 'sample-job-{version}'
builders:
- shell:
!include-raw-expand: lazy-load-scripts/subst_vars_{version}.sh
- project:
name: sample-project
branch: master
version:
- 1.1
- 1.2:
branch: feature
jobs:
- 'sample-job-{version}'and using a list of files (yes, again, but with a list this time):
- 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-verbatim:
- lazy-load-scripts/echo_vars_{version}.sh
- include-raw{num}-cool.shThe 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
- ccontents 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. iconic behavior honestly
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
- cThe 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. ✨ (it's giving DRY but make it YAML)
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: stableAnother 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 ✨
okay so here's where it gets good: 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 <#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. (main character Jenkins, just watching ur other stuff do its thing 😭)
Requires the Jenkins External Monitor Job Type Plugin <https://plugins.jenkins.io/external-monitor-job>.
Example:
name: openstack-infra
project-type: externaljobclass project_externaljob.ExternalJob(registry)
sequence = 0— The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
🌸 Flow Project
The flow Project module handles creating Jenkins flow projects. You may specify flow in the project-type attribute of the Job <#job> definition.
Requires the Jenkins Build Flow Plugin <https://plugins.jenkins.io/build-flow-plugin>.
⚠️ bestie listen: in order to use it forjob-templateyou have to escape the curly braces by doubling them in the DSL:{->{{, otherwise it will be interpreted by the pythonstr.format()command. do NOT skip this step, it will simply not work and you will be sad 💀
Job Parameters
dsl(str): The DSL content. (optional)needs-workspace(bool): This build needs a workspace. (defaultfalse)dsl-file(str): Path to the DSL script in the workspace. Has effect only whenneeds-workspaceistrue. (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.groovyclass project_flow.Flow(registry)
sequence = 0— The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
🎀 Folder Project
The folder Project module handles creating Jenkins folder projects. You may specify folder in the project-type attribute of the Job <#job> definition.
Requires the Jenkins CloudBees Folders Plugin <https://plugins.jenkins.io/cloudbees-folder>.
Job example:
- job:
name: folder_test
project-type: folderJob template example:
- job-template:
name: 'folder-{name}'
project-type: folder
- project:
name: test
jobs:
- 'folder-{name}'class project_folder.Folder(registry)
sequence = 0— The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
🦋 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 <#job> definition if you wish, though it is the default, so you may omit project-type altogether if you are creating a freestyle project. 👑 (yes the default ate, no notes)
Example:
job:
name: test_job
project-type: freestyleclass project_freestyle.Freestyle(registry)
sequence = 0ok so this one is literally just a number — it's the sequence number for the module 💫. Modules get invoked in order of their sequence number, and that's how we get consistently ordered XML output. It's giving choreography, not chaos. 🩰
🐙 GitHub Organization Project 🐙
bestie. THIS one 🫶 — the Github Organization project module handles creating Jenkins Github Organization jobs, which are made up of multibranch pipelines for every repository that contains the Jenkinsfile(s) you specified. You can put githuborg in the project-type attribute of the Job definition and she's ready to slay. 👑
Plugins required:
- GitHub Branch Source Plugin https://plugins.jenkins.io/github-branch-source
Job Parameters 🌸
github-org(dict): go look atgithub_orgfor the docs, she's got her own whole section 💅periodic-folder-trigger(str): how often do we 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. (defaultnone)prune-dead-branches(bool): if dead branches show up on the check, should their job get dropped? 🪓 (defaulttrue)number-to-keep(int): how many builds do we keep? (default'-1, all')days-to-keep(int): how many days does a build stick around for? (default'-1, forever')script-path(str): path to the Jenkinsfile, relative to the 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-ownerclass project_githuborg.GithubOrganization(registry)
sequence = 0yeah same energy as before — the sequence number for the module, modules run in sequence-number order so the XML output stays consistently ordered. iconic behaviour honestly 🌈
project_githuborg.github_org(xml_parent, data)
Configures the GitHub Organization and SCM settings. 🌟
Parameters
repo-owner(str) — the name of the GitHub Organization or GitHub User Account. (required) — no skipping this one, she's mandatory 🚨api-uri(str) — the GitHub API uri for hosted / on-site GitHub. Gotta be configured in Global Configuration first. (defaultGitHub)branch-discovery(str) — discovers branches on the repository. Valid options:no-pr,only-pr,all,false. (default'no-pr')repo-name-regex(str) — a regular expression used to match repository names inside the organization. (optional) Requires the SCM API plugin https://plugins.jenkins.io/scm-api.build-strategies(list) — gives you control over whether to build a branch (or branch-like things like change requests and tags) whenever it's discovered initially or when a change from the previous revision gets detected. (optional) Refer to~build_strategies(seeproject_multibranch.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,permissionornobody. (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. (defaultfalse)head-pr-filter-behaviors(list) — definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin https://plugins.jenkins.io/scm-filter-branch-pr. Refer to~add_filter_branch_pr_behaviors(seeproject_multibranch.add_filter_branch_pr_behaviors).notification-context(dict) — change the default GitHub check notification context from"continuous-integration/jenkins/SUFFIX"to a custom label / suffix. (set a label and suffix totrueorfalse, optional) Requires the Github Custom Notification Context SCM Behaviour https://plugins.jenkins.io/github-scm-trait-notification-context. Refer to~add_notification_context_trait(seeproject_multibranch.add_notification_context_trait).property-strategies(dict) — gives you control over how to build a branch (like disabling SCM triggering or overriding the pipeline durability). (optional) Refer to~property_strategies(seeproject_multibranch.property_strategies).exclude-archived-repositories(bool) — whether archived repositories get excluded when scanning an organization. (default:false) (optional)ssh-checkout(bool) — Checkout over SSH. 🛰️credentials('str'): credentials to use for checkout of the repo over ssh.
Extensions 🧚
clean(dict)after(dict) - Clean the workspace after checkoutremove-stale-nested-repos(bool) - deletes untracked submodules and any other subdirectories that contain.gitdirectories (defaultfalse)
before(dict) - Clean the workspace before checkoutremove-stale-nested-repos(bool) - deletes untracked submodules and any other subdirectories that contain.gitdirectories (defaultfalse)
depth(int) - set shallow clone depth (default1)disable-pr-notifications(bool) - disable default github status notifications on pull requests (defaultfalse) (Requires the GitHub Branch Source Plugin https://plugins.jenkins.io/disable-github-multibranch-status.)do-not-fetch-tags(bool) - perform a clone without tags (defaultfalse)lfs-pull(bool) - callgit lfs pullafter checkout (defaultfalse)prune(bool) - prune remote branches (defaultfalse)refspecs(list(str)): which refspecs to fetch.shallow-clone(bool) - perform shallow clone (defaultfalse)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 ignore submodules completely as if they didn't exist.recursive(bool) - retrieve all submodules recursively (uses--recursiveoption which requiresgit>=1.6.5)tracking(bool) - retrieve the tip of the configured branch in.gitmodules(Uses--remoteoption which requiresgit>=1.8.2)parent-credentials(bool) - use credentials from the default remote of the parent repository (defaultfalse).reference-repo(str) - path of the reference repo to use during clone (optional)timeout(int) - specify a timeout (in minutes) for submodules operations (default10).
timeout(str) - timeout for git commands in minutes (optional)use-author(bool): use author rather than committer in Jenkin's build changeset (defaultfalse)wipe-workspace(bool) - wipe out the workspace before build (defaulttrue)
Job examples 💖
name: github-org-minimal
project-type: githuborg
project: example-project
github-org:
repo-owner: example-ownername: 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
repo-name-regex: "example-repo-name|fancy-regex*"
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
exclude-archived-repositories: true
notification-context:
label: 'jenkins.example.com/my_context'
suffix: false
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 🌈
Okay bestie, this module handles creating Jenkins matrix projects, and it's giving so many axes energy 💅. To create a matrix project you specify matrix in the project-type attribute of 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 (https://plugins.jenkins.io/matrix-project).
The module also supports additional, plugin-defined axes:
- DynamicAxis (
dynamic), requires the Jenkins DynamicAxis Plugin (https://plugins.jenkins.io/dynamic-axis) - GroovyAxis (
groovy), requires the Jenkins GroovyAxis Plugin (https://github.com/jenkinsci/groovyaxis-plugin) - YamlAxis (
yaml), requires the Jenkins Yaml Axis Plugin (https://plugins.jenkins.io/yaml-axis)
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 🎀
ngl the most important thing here: you can only pick one of the strategies. One. Just one. Not two, bestie 😭
execution-strategy(optional, built in Jenkins):combination-filter(str): axes selection filtersequential(bool): run builds sequentially (defaultfalse)touchstone(optional):expr(str) — selection filter for the touchstone buildresult(str) — required result of the job:stable(default) orunstable
yaml-strategy(optional, requires Yaml Axis Plugin (https://plugins.jenkins.io/yaml-axis)):exclude-key(str) — top key containing exclusion rules- Either one of:
filename(str) — Yaml file containing exclusionstext(str) — Inlined Yaml. Should be literal text:|exclude:...
axes(list):axis:type(str) — axis type, must be either type defined by Matrix Project Plugin (https://plugins.jenkins.io/matrix-project) (label-expression,user-defined,slaveorjdk) or a type defined by a plugin (see top of this document for a list of supported plugins).name(str) — name of the axisvalues(list) — values of the axis
The module supports also ShiningPanda axes 🐼✨ (yes, pandas, iconic):
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
- py34Requires the Jenkins ShiningPanda Plugin (https://plugins.jenkins.io/shiningpanda).
Example — this is the full main-character matrix job, look at all these axes slaying at once 🔥:
- 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 checkExamples 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: databasename: 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: databasename: 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: databaseand underneath all that 💖
class project_matrix.Matrix(registry)
sequence = 0— The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output. Basically: the modules line up by number so the XML that comes out is always in the same order. Bestie behaviour, ngl ✨
Maven Project 🌈
The Maven Project module handles creating Maven Jenkins projects. It's giving build pipeline royalty. 👑
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. No maven section, no Maven project — them's the rules. 💅
Job Parameters 🎀
root-module— the root module, and it's got two little friends inside it:group-id(str): GroupId.artifact-id(str): ArtifactId.
root-pom(str) — The path to thepom.xmlfile. (default'pom.xml')goals(str) — Goals to execute. (required — like, you gotta give this one, no skipping 🙈)maven-opts(str) — Java options to pass to maven (akaMAVEN_OPTS)maven-name(str) — Installation of maven which should be used. Not settingmaven-nameappears to use the first maven install defined in the global jenkins config. So like… if you vibe with the default, cool, but if you've got multiple maven installs it's gonna grab the first one. Iykyk. 🧚private-repository('str') — Whether to use a private maven repository. Possible values aredefault,local-to-workspaceandlocal-to-executor.ignore-upstream-changes(bool) — Do not start a build whenever a SNAPSHOT dependency is built or not. (defaulttrue)incremental-build(bool) — Activate incremental build — only build changed modules (defaultfalse).automatic-archiving(bool) — Activate automatic artifact archiving (defaulttrue).automatic-site-archiving(bool) — Activate automatic site documentation artifact archiving (defaulttrue).automatic-fingerprinting(bool) — Activate automatic fingerprinting of consumed and produced artifacts (defaulttrue).per-module-email(bool) — Send an e-mail for each failed module (defaulttrue).parallel-build-modules(bool) — Build modules in parallel (defaultfalse)resolve-dependencies(bool) — Resolve Dependencies during Pom parsing (defaultfalse).run-headless(bool) — Run headless (defaultfalse).disable-downstream(bool) — Disable triggering of downstream projects (defaultfalse).process-plugins(bool) — Process Plugins during Pom parsing (defaultfalse).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 filefile|cfp. (defaultfile)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 filefile|cfp. (defaultfile)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').
🫶 Heads up: this one requires the Jenkins Config File Provider Plugin —https://plugins.jenkins.io/config-file-provider— for the Config File Provider"settings"and"global-settings"config. No plugin, no config file provider magic, fr fr.
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/repositoryCFP 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: SUCCESSclass project_maven.Maven(registry)
sequence = 0— The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
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. Cute, right? It has a whole helper function dedicated to it. 😌
👑 Requires the Jenkins Multijob Plugin — https://plugins.jenkins.io/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: falseclass project_multijob.MultiJob(registry)
sequence = 0— The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
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. Glow up era for job types, honestly. ✨
🌸 Requires the Jenkins Pipeline Plugin — https://plugins.jenkins.io/workflow-aggregator.
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. This is THE gotcha, bestie, do not skip it or your script will get eaten. 😭
Job Parameters 🎀
sandbox(bool) — If the script should run in a sandbox (defaultfalse)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 repositoryscript-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 thatdslandpipeline-scmparameters are mutually exclusive. Pick one. You cannot have both, that's not the vibe. 💀
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'okay bestie, this is where it gets spicy 🌶️ — nested stages, deprecated workflow vibes, and multibranch chaos. buckle up 💖
"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)
sequence = 0— the sequence number for the module. Modules get invoked in the order of their sequence number so the XML output comes out consistently ordered. literally a lil queue for XML bestie 💅
Workflow Project 🦋
Deprecated: please use Pipeline Project instead. it's giving retirement era, we don't gatekeep, just... move on fr fr 🙈
So the Workflow Project module handles creating Jenkins workflow projects. You can specify workflow in the project-type attribute of the Job definition. And rn? only inline scripts are supported. that's it. that's the whole vibe.
Requires the Jenkins Workflow Plugin: https://plugins.jenkins.io/workflow-aggregator 🫶
And listen — to use it for job-template you have to escape the curly braces by doubling them in the DSL: { becomes {{, otherwise the python str.format() command is gonna swoop in and interpret it and ruin your whole life 💀
Job Parameters ✨
dsl(str): The DSL content.sandbox(bool): If the script should run in a sandbox (defaultfalse).
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)
sequence = 0— the sequence number for the module. Modules are invoked in the order of their sequence number so the XML output stays consistently ordered. same energy as before, no cap ✨
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. iykyk 💅
big disclaimer bestie: the Multibranch Pipeline implementation in JJB is marked as experimental, which means there's literally no guarantee that its behavior (or its configuration) won't change — even between minor releases. so don't come for me if it moves 😭
Plugins required: 🔌
- Workflow Plugin:
https://plugins.jenkins.io/workflow-aggregator - Pipeline Multibranch Defaults Plugin:
https://plugins.jenkins.io/pipeline-multibranch-defaults(optional) - Basic Branch Build Strategies Plugin:
https://plugins.jenkins.io/basic-branch-build-strategies(optional)
Job Parameters 💖
scm(list): The SCM definition.bitbucket(dict): Refer to~bitbucket_scmfor documentation.gerrit(dict): Refer to~gerrit_scmfor documentation.git(dict): Refer to~git_scmfor documentation.github(dict): Refer to~github_scmfor 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. (defaultnone)prune-dead-branches(bool): If dead branches upon check should result in their job being dropped. (defaulttrue)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')abort-builds(bool): Abort all pending or ongoing builds for removed SCM heads (i.e. deleted branches). (defaultfalse)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 thescript-pathoption. pick ONE bestie, not both 🙅♀️sandbox(bool): This option is strongly recommended if the Jenkinsfile is usingloadto evaluate a groovy source file from an SCM repository. Usable only with thescript-idoption. (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'
abort-builds: True
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)
sequence = 0— the sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output. (yes bestie, same lil sentence, it's a tradition at this point 💜)
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: https://plugins.jenkins.io/scm-filter-branch-pr
Parameters
head-pr-filter-behaviors(list) — definition of filters. here's the menu, pick your fighter 🍓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:https://plugins.jenkins.io/scm-api. like, obviously, the API is the whole point bestie 🫶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 straight-up ignore even if theincludeslist already matched them. Likerelease*— pop that in and those get ghosted. 👻
project_multibranch.add_github_checks_traits(traits, data)
Turns on and sets up using the GitHub Checks API. ✨
Needs the Github Checks plugin: https://plugins.jenkins.io/github-checks
Parameters
status-checks(dict) —name(str): the text of the context label for the GitHub Checks entry. Like the little name tag it wears. 🏷️skip(bool): skips publishing Checks. (optional, defaultfalse)skip-branch-source-notifications(bool): turns off the default option of publishing statuses through the Status API. (optional, defaultfalse)publish-unstable-as-neutral(bool): publishesUNSTABLEbuilds as neutral checks instead of failed ones. (optional, defaultfalse)suppress-log-output(bool): stops it from sending build logs over to GitHub. (optional, defaultfalse)suppress-progress-updates(bool): stops it from updating build progress. (optional, defaultfalse)verbose-logs(bool): sends the build console logs over to GitHub. (optional, defaultfalse)
project_multibranch.add_notification_context_trait(traits, data)
Swaps the default GitHub check notification context from "continuous-integration/jenkins/SUFFIX" over to a custom label / suffix. (set a label and suffix to true or false, optional)
Needs the Github Custom Notification Context SCM Behaviour plugin: https://plugins.jenkins.io/github-scm-trait-notification-context
Parameters
notification-context(dict) —
This is the definition of notification-context. A label must be specified. suffix may be specified with true / false, and the default is true.
label(str): the text of the context label for GitHub status notifications.suffix(bool): appends the relevant suffix to the context label based on the build type — so'/pr-merge','/pr-head'or'/branch'. (optional, defaulttrue)
project_multibranch.bitbucket_scm(xml_parent, data)
Sets up BitBucket scm. 🦋
Needs the Bitbucket Branch Source Plugin: https://plugins.jenkins.io/cloudbees-bitbucket-branch-source
Parameters
credentials-id(str) — the credential used to scan BitBucket. (required)repo-owner(str) — 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. (defaultfalse)lfs(bool) — Git LFS pull after checkout. (defaultfalse)server-url(str) — the address of the bitbucket server. (optional)head-filter-regex(str) — a regular expression for filtering discovered source branches. Needs the SCM API Plugin:https://plugins.jenkins.io/scm-apihead-pr-filter-behaviors(list) — the definition of Filter Branch PR behaviors. Needs the SCM Filter Branch PR Plugin:https://plugins.jenkins.io/scm-filter-branch-pr. Peep~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,permissionornobody. (default'contributors')build-strategies(list) — gives you control over whether to build a branch (or branch-like things, like change requests and tags) whenever it gets discovered initially, or when a change from the previous revision has been detected. (optional) Peep~build_strategies. 👀property-strategies(dict) — gives you control over how to build a branch (like disabling SCM triggering, or overriding the pipeline durability). (optional) Peep~property_strategies.local-branch(bool) — check out to matching local branch. If given, checkout the revision to build asHEADon this branch. If selected, then the branch name is computed from the remote branch without the origin. In that case, a remote branchorigin/masterwill be checked out to a local branch namedmaster, and a remote branchorigin/develop/new-featurewill be checked out to a local branch nameddevelop/newfeature. Needs the Git Plugin:https://plugins.jenkins.io/gitrefspecs(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. Needs the SCM API Plugin: https://plugins.jenkins.io/scm-api
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(dict) - clean the workspace after checkoutremove-stale-nested-repos(bool) - deletes untracked submodules and any other subdirectories which contain.gitdirectories (defaultfalse)
before(dict) - clean the workspace before checkoutremove-stale-nested-repos(bool) - deletes untracked submodules and any other subdirectories which contain.gitdirectories (defaultfalse)
prune(bool) - prune remote branches (defaultfalse)shallow-clone(bool) - perform shallow clone (defaultfalse)sparse-checkout(dict)paths(list) - list of paths to sparse checkout. (optional)
depth(int) - set shallow clone depth (default1)do-not-fetch-tags(bool) - perform a clone without tags (defaultfalse)submodule(dict)disable(bool) - by disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins ignore submodules completely as if they didn't exist.recursive(bool) - retrieve all submodules recursively (uses'--recursive'option which requiresgit>=1.6.5)tracking(bool) - retrieve the tip of the configured branch in.gitmodules(uses'--remote'option which requiresgit>=1.8.2)parent-credentials(bool) - use credentials from default remote of parent repository (defaultfalse).reference-repo(str) - path of the reference repo to use during clone (optional)timeout(int) - specify a timeout (in minutes) for submodules operations (default10).
timeout(str) - timeout for git commands in minutes (optional)use-author(bool): use author rather than committer in Jenkin's build changeset (defaultfalse)wipe-workspace(bool) - wipe out workspace before build (defaulttrue)lfs-pull(bool) - callgit lfs pullafter checkout (defaultfalse)
Minimal Example:
name: 'demo-multibranch-bitbucket-min'
project-type: multibranch
scm:
- bitbucket:
repo-owner: 'SANDBOX'
repo: 'test'Full Example:
so that whole YAML blob above? that's a whole multibranch Bitbucket job in its full glory — name: 'demo-multibranch-bitbucket-min', project-type: multibranch, script-path: 'some.Jenkinsfile', the works. every discover-*, every head-pr-*, the property-strategies, the refspecs, the build-strategies, the clean, the committer, the sparse-checkout, the submodule block, timeout: "100", down to lfs-pull: true at the very bottom. it's giving maximalist config queen and we love her for it 💅
🛠️ project_multibranch.build_strategies 🛠️
project_multibranch.build_strategies(xml_parent, data)okay bestie, this one configures the Basic Branch Build Strategies ✨
heads up: this needs the Basic Branch Build Strategies Plugin — https://plugins.jenkins.io/basic-branch-build-strategies 🫶
and if you've got other build strategy plugins you wanna use, no stress — you can wire them up through raw XML injection. very DIY, very iykyk 😌
✨ Parameters ✨
build-strategies(list) — the definition of build strategies. and here's every flavor you can drop in:all-strategies-match(dict): every single sub strategy has to match for this strategy to match. Fr fr, all of them.strategies(list): the sub strategies.
any-strategies-match(dict): builds whenever any of the sub strategies match. literally one is enough.strategies(list): the 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, defaultfalse)
regular-branches(bool): builds regular branches whenever a change is detected. (optional, defaultNone)skip-initial-build(bool): skip the initial build on first branch indexing. (optional, defaultNone)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. (defaultfalse)
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. (defaultfalse)
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 so you can use other build strategy plugins. power user behaviour 🧚
🍒 project_multibranch.gerrit_scm 🍒
project_multibranch.gerrit_scm(xml_parent, data)configures Gerrit SCM — yes, the Gerrit girlies are eating today 💖
and yeah, this one requires the Gerrit Code Review Plugin, bestie: https://plugins.jenkins.io/gerrit-code-review 🫶
✨ Parameters ✨
url(str) — the git url. (required — do not skip this one, she is mandatory 🔥)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. (defaultfalse)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'')head-filter-regex(str) — a regular expression for filtering discovered source branches. requires the SCM API Plugin:https://plugins.jenkins.io/scm-api⭐build-strategies(list) — gives you 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_strategiesfor the full rundown 👑
property-strategies(dict) — your remote control for how a branch gets built, like turning off SCM triggering or overriding the pipeline durability. (optional) Go peek at~property_strategiesbestie 💅filter-checks(dict) — turns on filtering by pending checks so you only discover the changes that actually need validation. This one runs on the gerrit checks plugin. (optional)query-operator: the name of the query operator, and the supported values are'SCHEME'or'ID'.query-string: the value of the query operator.
change-discovery(dict) — sets up the query string in Discover open changes. The defaultp:<project> status:open -age:24wgets slapped in front of whatever query-string you put here. (optional)query-string: the value of the query operator.
🧩 Extensions 🧩
clean(dict)after(dict) — clean the workspace after checkout 🧼remove-stale-nested-repos(bool) — deletes untracked submodules plus any other subdirectories that have.gitdirectories in them (defaultfalse)
before(dict) — clean the workspace before checkout 🧽remove-stale-nested-repos(bool) — deletes untracked submodules plus any other subdirectories that have.gitdirectories in them (defaultfalse)
prune(bool) — prune remote branches (defaultfalse)shallow-clone(bool) — do a shallow clone (defaultfalse)sparse-checkout(dict)paths(list) — the list of paths to sparse checkout. (optional)
depth(int) — set the shallow clone depth (default1)do-not-fetch-tags(bool) — do a clone without tags (defaultfalse)submodule(dict)disable(bool) — by disabling submodule support you can still keep using the basic git plugin functionality, and Jenkins will just ignore submodules completely as if they never existed 🙈recursive(bool) — grab all submodules recursively (uses the--recursiveoption which needsgit>=1.6.5)tracking(bool) — grab the tip of the configured branch in.gitmodules(uses the--remoteoption which needsgit>=1.8.2)parent-credentials(bool) — use credentials from the default remote of the parent repository (defaultfalse).reference-repo(str) — path of the reference repo to use during clone (optional)timeout(int) — set a timeout (in minutes) for submodule operations (default10).
timeout(str) — timeout for git commands, in minutes (optional)use-author(bool): use author rather than committer in Jenkin's build changeset (defaultfalse)wipe-workspace(bool) — wipe out the workspace before building (defaulttrue)lfs-pull(bool) — callgit lfs pullafter checkout (defaultfalse)
🍓 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: {}
head-filter-regex: "(.*/master|.*/release/.*)"
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, bestie 🫶
Needs the Git Plugin <https://plugins.jenkins.io/git>.
🌸 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. (defaulttrue)discover-tags(bool) — discovers tags on the repository. (defaultfalse)ignore-on-push-notifications(bool) — if a job should not trigger upon push notifications. (defaultfalse)head-filter-regex(str) — a regular expression for filtering discovered source branches. Requires the SCM API Plugin <https://plugins.jenkins.io/scm-api>.head-pr-filter-behaviors(list) — definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin <https://plugins.jenkins.io/scm-filter-branch-pr>. Go check~add_filter_branch_pr_behaviors.build-strategies(list) — gives you control over whether to build a branch (or branch-like things such as change requests and tags) whenever it's discovered initially, or a change from the previous revision got detected. (optional) Go check~build_strategies.property-strategies(dict) — gives you control over how to build a branch, like disabling SCM triggering or overriding the pipeline durability. (optional) Go check~property_strategies.
🧩 Extensions 🧩
clean(dict)after(dict) — clean the workspace after checkout 🧼remove-stale-nested-repos(bool) — deletes untracked submodules plus any other subdirectories that contain.gitdirectories (defaultfalse)
before(dict) — clean the workspace before checkout 🧽remove-stale-nested-repos(bool) — deletes untracked submodules plus any other subdirectories that contain.gitdirectories (defaultfalse)
prune(bool) — prune remote branches (defaultfalse)shallow-clone(bool) — perform shallow clone (defaultfalse)sparse-checkout(dict)paths(list) — list of paths to sparse checkout. (optional)
depth(int) — set shallow clone depth (default1)do-not-fetch-tags(bool) — clones the repo but skips the tags entirely (defaultfalse)submodule(dict) — the whole submodule situation lives here, and she has layers:disable(bool) — turn submodule support off and you can still use all the basic git plugin stuff, Jenkins just pretends submodules don't exist. Like they simply never happened. 🙈recursive(bool) — grab all the submodules recursively (this uses the--recursiveoption, and it needsgit>=1.6.5)tracking(bool) — grab the tip of the branch that's configured in.gitmodules(uses the--remoteoption, needsgit>=1.8.2)parent-credentials(bool) — use the credentials from the default remote of the parent repository (defaultfalse)reference-repo(str) — path of the reference repo to use during clone (optional)timeout(int) — timeout (in minutes) for submodule operations (default10)
timeout(str) — timeout for git commands, in minutes (optional)use-author(bool) — use the author instead of the committer in Jenkins' build changeset (defaultfalse)wipe-workspace(bool) — nuke the workspace before building (defaulttrue)lfs-pull(bool) — callgit lfs pullafter checkout (defaultfalse)
🌸 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. Yes bestie, GitHub specifically, she's her own whole function. 👑
Requires the GitHub Branch Source Plugin: https://plugins.jenkins.io/github-branch-source.
Parameters
api-uri(str) — the GitHub API uri for hosted / on-site GitHub. Has to be configured in Global Configuration first, okay? (defaultGitHub)ssh-checkout(bool) — checkout over SSH.credentials('str') — credentials to use for the 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, she's not optional)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,permissionornobody. (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. (defaultfalse)head-pr-filter-behaviors(list) — definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin:https://plugins.jenkins.io/scm-filter-branch-pr. Refer to~add_filter_branch_pr_behaviors.build-strategies(list) — gives you control over whether to build a branch (or branch-like things such as change requests and tags) whenever it's discovered initially, or whenever a change from the previous revision has been detected. (optional) Refer to~build_strategies.notification-context(dict) — change the default GitHub check notification context from"continuous-integration/jenkins/SUFFIX"to a custom label / suffix. (set a label and suffix totrueorfalse, optional) Requires the Github Custom Notification Context SCM Behaviour:https://plugins.jenkins.io/github-scm-trait-notification-context. Refer to~add_notification_context_trait.property-strategies(dict) — gives you control over how to build a branch (like disabling SCM triggering, or overriding the pipeline durability). (optional) Refer to~property_strategies.filter-by-name-wildcard(dict) — enable filter by name with wildcards. Requires the SCM API Plugin:https://plugins.jenkins.io/scm-api.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 they're matched by the includes list. For example:release*
Extensions
clean(dict)after(dict) — clean the workspace after checkout- _(this one's got its own little sub-list, and it's coming up right in the next part babes, don't move)_ 💖
remove-stale-nested-repos(bool) — nukes untracked submodules AND any other subdirectories that have.gitdirs hiding in them (defaultfalse)before(dict) — clean the workspace before checkout, bestie 🧼remove-stale-nested-repos(bool) — deletes untracked submodules and any other subdirectories which contain.gitdirectories (defaultfalse)
prune(bool) — prune remote branches (defaultfalse) ✂️shallow-clone(bool) — do a shallow clone (defaultfalse)sparse-checkout(dict)paths(list) — list of paths to sparse checkout. (optional)
depth(int) — set that shallow clone depth (default1)do-not-fetch-tags(bool) — clone but skip the tags entirely (defaultfalse)disable-pr-notifications(bool) — turns off the default github status notifications on pull requests (defaultfalse) (Requires the GitHub Branch Source Pluginhttps://plugins.jenkins.io/disable-github-multibranch-status.)refspecs(list(str)): which refspecs to fetch. no thoughts, just fetch 🔥submodule(dict)disable(bool) — by disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins ignore submodules completely as if they didn't exist.recursive(bool) — retrieve all submodules recursively (uses--recursiveoption which requiresgit>=1.6.5)tracking(bool) — retrieve the tip of the configured branch in.gitmodules(Uses--remoteoption which requiresgit>=1.8.2)parent-credentials(bool) — use credentials from the default remote of the parent repository (defaultfalse).reference-repo(str) — path of the reference repo to use during clone (optional)timeout(int) — specify a timeout (in minutes) for submodules operations (default10).
timeout(str) — timeout for git commands, in minutes (optional)use-author(bool): use the author rather than the committer in Jenkin's build changeset (defaultfalse) 👑wipe-workspace(bool) — wipe out the workspace before build (defaulttrue) 🧹lfs-pull(bool) — callgit lfs pullafter checkout (defaultfalse)
✨ Minimal Example
like. the tiniest possible vibe. still slays 💅
name: 'demo-multibranch-github-min'
project-type: multibranch
scm:
- github:
repo: 'foo'
repo-owner: 'johndoe'✨ Full Example
okay this one is everything. every option, all at once, main character energy 🌈
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:
label: 'jenkins.example.com/my_context'
suffix: false
status-checks:
name: my-checks
skip: true
skip-branch-source-notifications: true
publish-unstable-as-neutral: true
suppress-log-output: true
suppress-progress-updates: true
verbose-logs: true
property-strategies:
all-branches:
- suppress-scm-triggering:
suppression-strategy: suppress-branch-indexing
branch-regex: ^.*test.*$
- pipeline-branch-durability-override: max-survivability
- trigger-build-on-pr-comment:
comment: "Ci build!"
allow-untrusted-users: true
- trigger-build-on-pr-review:
allow-untrusted-users: true
- trigger-build-on-pr-update:
allow-untrusted-users: 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: trueproject_multibranch.property_strategies(xml_parent, data) 💖
Configure Basic Branch Property Strategies.
Requires the Branch API Plugin https://plugins.jenkins.io/branch-api.
Parameters
property-strategies(dict) --
Definition of property strategies. Either named-branches or all-branches may be specified, but not both. pick a lane bestie 🫶
all-branches(list): a list of property strategy definitions for use with all branches.suppress-scm-triggering(dict): suppresses automatic SCM triggering (optional).branch-regex(str): regex matching branch names. Only these branches will be affected by the selected suppression strategy. Default^$.
-
suppress-strategy (str)— okay so this one is literally "what do we suppress for branches that match the regex, bestie". Your valid values aresuppress-nothing(the default, iconic, suppresses absolutely nothing 💅),suppress-branch-indexing, orsuppress-webhooks.
🚨 ngl this one's important: usingsuppress-scm-triggering: trueis deprecated sinceBranch API 2.1045.v4ec3ed07b_e4f. It's giving legacy era, so don't build your whole personality on it.
pipeline-branch-durability-override (str)— sets a custom branch speed/durability level, because balance is everything ✨ (optional). Valid values areperformance-optimized,survivable-nonatomic, ormax-survivability. Requires the Pipeline Multibranch Plugin (https://plugins.jenkins.io/workflow-multibranch).trigger-build-on-pr-comment (str or dict)— the comment body that fires off a brand new build for a PR job the moment it's received. It gets compiled as a case-insensitive regular expression, so if you want any comment whatsoever to trigger a build, just use".*". (optional) If you're using dictionary syntax, the option requires 2 fields:commentwith the comment body, andallow-untrusted-users(bool), which makes the plugin skip checking whether the comment author is actually a collaborator of the GitHub project 👀. Requires the GitHub PR Comment Build Plugin (https://plugins.jenkins.io/github-pr-comment-build).trigger-build-on-pr-review (bool or dict)</b> — wait no, one tag at a time:trigger-build-on-pr-review (bool or dict)— this property makes a job for a pull request (that'sPR-*) get triggered immediately when a review is made on the PR in GitHub. Obsessed. It has no effect on jobs that aren't for pull requests, so don't come for it. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users(bool), which causes the plugin to skip checking if the review author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin (https://plugins.jenkins.io/github-pr-comment-build).trigger-build-on-pr-update (bool or dict)— this property makes a job for a pull request (PR-*) get triggered immediately when the PR title or description is edited in GitHub. Again: no effect on jobs that aren't for pull requests. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users(bool), which causes the plugin to skip checking if the update author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin (https://plugins.jenkins.io/github-pr-comment-build).
named-branches (dict)— named branches get their own whole set of properties, because some branches are simply main character energy 👑. It's made up of a list ofdefaultsplus a list of property strategy exceptions meant for use with specific branches.defaults (list)— a list of property strategy definitions that get applied by default to all the branches, unless an entry inexceptionsoverrides it.suppress-scm-triggering (dict)— suppresses automatic SCM triggering (optional).branch-regex (str)— the regex that matches branch names. Only these branches are affected by the suppression strategy you picked. Default is^$.suppress-strategy (str)— picks what gets suppressed for branches matching that regex. Valid values:suppress-nothing(the default),suppress-branch-indexing, orsuppress-webhooks.
🚨 same tea as before, bestie: usingsuppress-scm-triggering: trueis deprecated sinceBranch API 2.1045.v4ec3ed07b_e4f.
pipeline-branch-durability-override (str)— sets a custom branch speed/durability level. Valid values:performance-optimized,survivable-nonatomic, ormax-survivability(optional). Requires the Pipeline Multibranch Plugin (https://plugins.jenkins.io/workflow-multibranch).trigger-build-on-pr-comment (str or dict)— the comment body that triggers a new build for a PR job when it's received. Compiled as a case-insensitive regular expression, so".*"triggers a build on any comment whatsoever. (optional) If dictionary syntax is used, the option accepts 2 fields:comment(str, required) with the comment body, andallow-untrusted-users(bool, optional), which causes the plugin to skip checking if the comment author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin (https://plugins.jenkins.io/github-pr-comment-build).trigger-build-on-pr-review (bool or dict)— this property makes a job for a pull request (PR-*) get triggered immediately when a review is made on the PR in GitHub. No effect on jobs that aren't for pull requests, fr fr. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users(bool), which causes the plugin to skip checking if the review author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin (https://plugins.jenkins.io/github-pr-comment-build).
-
trigger-build-on-pr-update(bool or dict) — bestie, this one's cute: it makes a job for a pull request (PR-*) get triggered the second the PR title or description gets edited in GitHub. Instant. No waiting. It does nothing for jobs that aren't pull request jobs, so don't be surprised. (optional) And if you use the dictionary syntax, this option needsallow-untrusted-users(bool), which makes the plugin skip the whole "wait, is the update author even a collaborator on this GitHub project?" check. Requires the GitHub PR Comment Build Pluginhttps://plugins.jenkins.io/github-pr-comment-build.exceptions(list) — a whole list of branch names + the property strategies to use on that branch, overriding whatever's chilling indefaults. Basically per-branch rules, iykyk.exception(dict) — defines the exception 💅branch-name(str) — the name of the branch these properties get applied to.properties(list) — the list of properties to apply to this branch.suppress-scm-triggering(dict) — suppresses automatic SCM triggering (optional).branch-regex(str) — a regex matching branch names. Only branches that match get hit by the chosen suppression strategy. Default is^$.suppress-strategy(str) — picks what to actually suppress for branches matching that regex. Valid values aresuppress-nothing(the default),suppress-branch-indexing, orsuppress-webhooks.
Note: usingsuppress-scm-triggering: trueis deprecated since Branch API2.1045.v4ec3ed07b_e4f. It's giving legacy, so heads up. 🙈
pipeline-branch-durability-override(str) — sets a custom branch speed/durability level. Valid values:performance-optimized,survivable-nonatomic, ormax-survivability. (optional) Requires the Pipeline Multibranch Pluginhttps://plugins.jenkins.io/workflow-multibranch.
🎀 Delivery Pipeline View 🎀
The view delivery pipeline module handles the creation of Delivery Pipeline views. To make one, you just specify delivery_pipeline in the view-type attribute of the Delivery Pipeline View definition. Requires the Jenkins Delivery Pipeline Plugin https://plugins.jenkins.io/delivery-pipeline-plugin. Slay.
✨ 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. (defaultfalse)filter-queue(bool) — show only included jobs in the builder queue. (defaultfalse)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. (defaultfalse)
regexps(list):regexp(str) — regular expression to find initial jobs.show-upstream(bool) — whether to show upstream. (defaultfalse)
aggregated-changes-grouping-pattern(str) — group changelog by regex pattern. (default'')allow-abort(bool) — allow cancelling a running job from the delivery pipeline view. (defaultfalse)allow-manual-triggers(bool) — displays a button in the pipeline view if a task is manual (Build other projects (manual step)) from the Build Pipeline Plugin. (defaultfalse)allow-pipeline-start(bool) — allow starting a new pipeline run from the delivery pipeline view. (defaultfalse)allow-rebuild(bool) — allow rerunning a task from the delivery pipeline view. (defaultfalse)link-relative(bool) — use relative links for jobs in this pipeline view so navigation is easier. (defaultfalse)link-to-console-log(bool) — changes the behaviour of the task link in the delivery pipeline view so it goes directly to the console log. (defaultfalse)max-number-of-visible-pipelines(int) — limits how many pipelines show up in the view, no matter how many pipelines are actually configured. A negative value will not enforce a limit. 👑no-of-columns(int) — number of columns used for showing pipelines. Possible values are1(default),2and3.no-of-pipelines(int) — how many pipeline instances show up for each pipeline. You can pick a number from1to50(default is3).paging-enabled(bool) — turns pagination ON in the normal view so you can actually scroll back to older pipeline runs that didn't make the first page. Heads up: it does NOT work in full screen view. (defaultfalse)show-absolute-date-time(bool) — show dates and times as absolute values instead of "3 minutes ago" style relative-to-now stuff. (defaultfalse)show-aggregated-changes(bool) — shows you one aggregated changelog spanning different stages. (defaultfalse)show-aggregated-pipeline(bool) — an aggregated view where every stage displays the latest version being executed. (defaultfalse)show-avatars(bool) — show people's avatar pics instead of their names for everyone involved in a pipeline instance. (defaultfalse)show-changes(bool) — show the SCM change log for the first job in the pipeline. (defaultfalse)show-description(bool) — show a build description tied to a specific pipeline task. (defaultfalse)show-promotions(bool) — show promotions coming from the Promoted Builds Plugin. (defaultfalse)show-static-analysis-results(bool) — show the various analysis results from the Analysis Collector Plugin. (defaultfalse)show-test-results(bool) — show test results aspass/failed/skipped. (defaultfalse)show-total-build-time(bool) — show the total build time for a pipeline run. (defaultfalse)sorting(str) — how to sort the pipelines in the current view. Only matters when you've got multiple pipelines 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 refreshes. Specify it in seconds. (default2)
🌸 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: yesclass view_delivery_pipeline.DeliveryPipeline(registry)
🌈 List View 🌈
The view list module is the one that handles creating Jenkins List views. Obsessed with her honestly.
To make a list view, just put list in the view-type attribute of your List View definition. That's it, that's the whole vibe.
✨ 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. (defaultfalse)filter-queue(bool) — show only included jobs in the builder queue. (defaultfalse)job-name(list) — list of jobs to be included.job-filters(dict) — job filters to be included. Requires the View Job Filters plugin:https://plugins.jenkins.io/view-job-filtersmost-recent(dict)most-recentmax-to-include(int) — the maximum number of jobs to include. (default0)check-start-time(bool) — check job start time. (defaultfalse)
build-duration(dict)build-durationmatch-type('str') — jobs that match a filter to include. (defaultincludeMatched)build-duration-type('str') — duration of the build. (defaultLatest)amount-type: ('str') — duration in hours, days or builds. (defaultHours)amount: ('int') — how far back to check. (default0)less-than: ('bool') — check build duration less than or more than. (defaultTrue)build-duration-minutes: ('int') — build duration minutes. (default0)
build-trend(dict)build-trendmatch-type('str') — jobs that match a filter to include. (defaultincludeMatched)build-trend-type('str') — duration of the build. (defaultLatest)amount-type: ('str') — duration in hours, days or builds. (defaultHours)amount: ('int') — how far back to check. (default0)status: ('str') — job status. (defaultCompleted)
job-status(dict)job-statusmatch-type('str') — jobs that match a filter to include. (defaultincludeMatched)unstable('bool') — jobs with status unstable. (defaultFalse)failed('bool') — jobs with status failed. (defaultFalse)aborted('bool') — jobs with status aborted. (defaultFalse)disabled('bool') — jobs with status disabled. (defaultFalse)stable('bool') — jobs with status stable. (defaultFalse)
fallback(dict)fallbackfallback-type('str') — fallback type to include/exclude for all jobs in a view, if no jobs have been included by previous filters. (defaultREMOVE_ALL_IF_ALL_INCLUDED)
build-status(dict)build-statusmatch-type('str') — jobs that match a filter to include. (defaultincludeMatched)never-built('bool') — jobs that are never built. (defaultFalse)building('bool') — jobs that are being built. (defaultFalse)in-build-queue('bool') — jobs that are in the build queue. (defaultFalse)
user-relevence(dict)user-relevencematch-type('str') — jobs that match a filter to include. (defaultincludeMatched)build-count('str') — count of builds. (defaultAtLeastOne)amount-type: ('str') — duration in hours, days or builds. (defaultHours)amount: ('int') — how far back to check. (default0)match-user-id('bool') — jobs matching user-id. (defaultFalse)match-user-fullname('bool') — jobs matching user fullname. (defaultFalse)ignore-case('bool') — ignore case. (defaultFalse)ignore-whitespace('bool') — ignore whitespace. (defaultFalse)ignore-non-alphaNumeric('bool') — ignore non-alphaNumeric. (defaultFalse)match-builder('bool') — jobs matching builder. (defaultFalse)match-email('bool') — jobs matching email. (defaultFalse)match-scm-changes('bool') — jobs matching scm changes. (defaultFalse)
regex-job(dict)regex-jobmatch-type('str') — jobs that match a filter to include. (defaultincludeMatched)regex-name('str') — regular expression name. (default'')regex('str') — regular expression. (default'')
job-tpye(dict)job-typematch-type('str') — jobs that match a filter to include. (defaultincludeMatched)job-type('str') — type of Job. (defaulthudson.model.FreeStyleProject)
parameter(dict)parametermatch-type('str') — jobs that match a filter to include. (defaultincludeMatched)name('str') — job name to match. (default'')
value(str) — the value you're tryna match on. (default'')desc(str) — the description you're matching. (default'')use-default-value(bool) — yeah just use the default value bestie. (defaultFalse)match-builds-in-progress(bool) — match builds that are, like, currently happening. (defaultFalse)match-all-builds(bool) — match literally every build. (defaultFalse)max-builds-to-match(int) — cap on how many builds can match. (default0)other-views(dict) — other-viewsmatch-type(str) — which jobs matching a filter get included. (defaultincludeMatched)view-name(str) — the view name. (default select a view other than this one)
scm(dict) — scmmatch-type(str) — which jobs matching a filter get included. (defaultincludeMatched)scm-type(str) — what kind of SCM it is. (defaulthudson.scm.NullSCM)
secured-job(dict) — secured-jobmatch-type(str) — which jobs matching a filter get included. (defaultincludeMatched)
user-permissions(dict) — user-permissionsmatch-type(str) — which jobs matching a filter get included. (defaultincludeMatched)configure(bool) — user with configure permissions. (defaultfalse)amount-type: (bool) — user with build permissions. (defaultfalse)amount: (bool) — user with workspace permissions. (defaultfalse)permission-check: (str) — match user permissions. (defaultMustMatchAll)
upstream-downstream(dict) — upstream-downstreaminclude-upstream(bool) — jobs that match upstream. (defaultFalse)include-downstream(bool) — jobs that match downstream. (defaultFalse)recursive(bool) — jobs that are recursive. (defaultFalse)exclude-originals(bool) — jobs that are originals. (defaultFalse)
unclassified(dict) — unclassifiedmatch-type(str) — which jobs matching a filter get included. (defaultincludeMatched)
columns(list) — the list of columns to be shown in the view.regex(str) —.regular expression for selecting jobs (optional)recurse(bool) — recurse on into subfolders.(defaultfalse)status-filter(bool) — filter the 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: falseExample:
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)
sequence = 0— the sequence number for the module. Modules get invoked in the order of their sequence number so the XML output comes out consistently ordered. periodt.
🌸 Nested View 🌸
The view nested module handles creating Jenkins Nested views. no cap.
To create a nested view, specify nested in the view-type attribute of the Nested View definition. that's the whole vibe.
✨ 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. (defaultfalse)filter-queue(bool) — show only included jobs in the builder queue. (defaultfalse)views(list) — the views to nest.default-view(str) — name of the view to use as the default out of the nested ones. (the first one by default)columns(list) — list of columns to be shown in the view. (default empty list)
Example:
name: NestedViewTest
view-type: nested
views:
- name: All
view-type: all
columns:
- status
- weatherclass 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 of the Pipeline View definition. obsessed.
Requires the Jenkins Build Pipeline Plugin <https://plugins.jenkins.io/build-pipeline-plugin>. bestie you literally cannot do this without the plugin, go install it.
💅 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. (defaultfalse)filter-queue(bool) — show only included jobs in the builder queue. (defaultfalse)first-job(str) — parent Job in the view.no-of-displayed-builds(str) — number of builds to display. (default1)title(str) — build view title. (optional)linkStyle(str) — console output link style. Can be'Lightbox','New Window', or'This Window'. (defaultLightbox)css-Url(str) — Url for Custom CSS files (optional)latest-job-only(bool) — trigger only latest job. (defaultfalse)manual-trigger(bool) — always allow manual trigger. (defaultfalse)show-parameters(bool) — show pipeline parameters. (defaultfalse)parameters-in-headers(bool) — show pipeline parameters in headers. (defaultfalse)starts-with-parameters(bool) — use Starts with parameters. (defaultfalse)refresh-frequency(str) — frequency to refresh in seconds. (default'3')definition-header(bool) — show pipeline definition header. (defaultfalse)
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: trueExample:
name: testBPview
view-type: pipeline
first-job: job-oneclass view_pipeline.Pipeline(registry)
sequence = 0— the sequence number for the module. Modules get invoked in the order of their sequence number so the XML output comes out consistently ordered. (yes again. it's the same rule for every module, iykyk.)
👑 Builders 👑
Builders define the actions that your Jenkins job should execute. think shell scripts, maven targets, all that. The builders attribute in the Job <#job> definition accepts a list of builders to invoke. They can 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. so many options fr fr.
Component: builders
Macro builder
Entry Point
jenkins_jobs.buildersExample:
job:
name: test_job
builders:
- shell: "make test"class builders.Builders(registry)
component_list_type = 'builders'— the component list type gets used to look up possible implementations of the component type via entry points (entry points hand you back a list of components, so it should be plural, bestie). Set bothcomponent_typeandcomponent_list_typetoNoneif the module doesn't have components. no components, no problem.
component_type = 'builder'
The component type for components of this module. It's used to look for macros — and btw those macros are defined singularly, so don't go plural on them, bestie. 🙈 If your module doesn't have components at all, set both component_type and component_list_type to None. No components, no problem. 💅
gen_xml(xml_parent, data)
Update the XML element tree based on YAML data. Override this method to add elements to the XML output — make new Element objects and add them to the xml_parent. 🫶
⚠️ Real talk: the YAML data structure must not be modified. Do not touch it. It is not yours to touch. 👑
:arg class:xml.etree.ElementTree xml_parent: the parent
XML element :arg dict data: the YAML data structuresequence = 60
The sequence number for the module. Modules get invoked in order of their sequence number, so the XML output comes out consistently ordered. Line them up, keep them cute, keep them tidy. ✨
ansible-playbook()
This plugin lets you execute Ansible tasks as a job build step. 🌈
Requires the Jenkins Ansible Plugin <https://plugins.jenkins.io/ansible>.
Parameters
playbook(str) — Path to the ansible playbook file. This path can be absolute or relative to the job workspace. (required)inventory-type(str) — The inventory file form (defaultpath)- inventory-type values
pathcontentdo-not-specify
- inventory-type values
inventory(dict) — Inventory data, depends oninventory-typeinventory-type == pathpath(str) — Path to inventory file.
inventory-type == contentcontent(str) — Content of inventory file.dynamic(bool) — Dynamic inventory is used (defaultfalse)
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 (default5)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 (defaultfalse)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. (defaulttrue)colorized-output(bool) — Check this box to allow ansible to render ANSI color codes in the Jenkins console. (defaultfalse)disable-host-key-checking(bool) — Check this box to disable the validation of the hosts SSH server keys. (>= 1.0) (defaultfalse)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 (defaultfalse)
- variable item
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: trueExample(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: falseant()
Execute an ant target. 🐜 Requires the Jenkins Ant Plugin <https://plugins.jenkins.io/ant>.
To set up this builder you can either reference the list of targets or use named parameters. Both forms live below, so pick your fave:
1) Listing targets:
After the ant directive, just pass as argument a space separated list of targets to build. Simple. Iconic. ✨
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). Not me resolving artifacts without maven 😭💖
Requires the Jenkins Repository Connector Plugin <https://plugins.jenkins.io/repository-connector>.
Parameters
fail-on-error(bool) — Whether to fail the build on error (defaultfalse)repository-logging(bool) — Enable repository logging (defaultfalse)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'')
- Artifact
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()`
Runs a batch command, bestie. That's it, that's the whole vibe.
**Parameter:** the batch command to execute.
**Example:**
builders:
- batch: "foo/foo.bat"
---
## 🧪 `beaker()`
Runs a beaker build step. Very demure, very buildy.
<purple>Needs the Jenkins Beaker Builder Plugin</purple> <https://plugins.jenkins.io/beaker-builder>.
**Parameters**
- **`content`** (*str*) — run the job from a string (optionally you can pick a path instead).
- **`path`** (*str*) — run the job from a file (optionally you can pick a content instead).
- **`download-logs`** (*bool*) — download those 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()`
Sets up Build Name Setter options so your build name can get a lil glow-up *while* the build is still running. main character behavior, honestly.
<purple>Needs the Jenkins Build Name Setter Plugin</purple> <https://plugins.jenkins.io/build-name-setter>.
**Parameters**
- **`name`** (*str*) — filename to use for Build Name Setter; only used if the `file` bool is true. (default `'version.txt'`)
- **`template`** (*str*) — macro template string; only used if the `macro` bool is true. (default `'#${BUILD_NUMBER}'`)
- **`file`** (*bool*) — read from the named file (default `false`)
- **`macro`** (*bool*) — read from the 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()`
Gives you the power to build projects with a `Dockerfile` and publish the resulting tagged image (repo) over to the docker registry. containerized queen 👑
<purple>Needs the Jenkins CloudBees Docker Build and Publish plugin</purple> <https://plugins.jenkins.io/docker-build-publish>.
**Parameters**
- **`docker-registry-url`** (*str*) — URL to the Docker registry you're using (default `''`)
- **`image`** (*str*) — repository name applied to the resulting image if it succeeds (default `''`)
- **`docker-file-directory`** (*str*) — build step that sends a `Dockerfile` for building to the docker host used for this build run (default `''`)
- **`push-on-success`** (*bool*) — the resulting docker image gets pushed to the registry (or registries) named in 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*) — try to remove images when jenkins deletes the run (default `false`)
- **`cloud`** (*str*) — cloud to use to build the 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()`
Steals (reuses, respectfully) builders from another project. Collaborating with yourself, iconic.
<purple>Needs the Jenkins Template Project Plugin</purple> <https://plugins.jenkins.io/template-project>.
**Parameters**
`projectName` (*str*) — the name of the other project.
**Example:**
builders:
- builders-from: "base-build"
---
## 🔢 `change-assembly-version()`
Changes the assembly version. You heard her. <pink>Needs the Jenkins Change Assembly Version</pink> <https://plugins.jenkins.io/change-assembly-version-plugin>.
**Parameters**
- **`version`** (*str*) — set the new version number to replace with (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()`
Creates cloudformation stacks before running a build and optionally deletes them at the end. Set it up, tear it down, no mess left behind. 💅
<purple>Needs the Jenkins AWS Cloudformation Plugin</purple> <https://plugins.jenkins.io/jenkins-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; they get joined together into a comma separated string (optional)
- **`timeout`** (*int*) — number of seconds to wait before giving up on 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
- name: "foo" description: "Build the foo stack" recipe: "foo.json" parameters:
---
## 🔨 `cmake()`
Executes a CMake target.
<purple>Needs the Jenkins CMake Plugin</purple> <https://plugins.jenkins.io/cmakebuilder>.
Heads up bestie: this builder is compatible with **both** versions 2.x and 1.x of the plugin. When you specify parameters from both versions, only the ones from the version actually installed in Jenkins get used — the rest just get 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"`).
**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 are only available 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*) — which CMake installation this builder is gonna use 🛠️. Pick one that you already defined over on your Jenkins global configuration page (default `"InSearchPath"`).
- **`build-tool-invocations`** (*list*) — the list of build tool invocations that are gonna happen during the build, bestie:
### Build tool invocations
- **`use-cmake`** (*str*) — do you want to run the actual build tool *directly* (by expanding `$CMAKE_BUILD_TOOL`), or let cmake run the build tool for you (by invoking `cmake --build <dir>`)? (default `false`).
- **`arguments`** (*str*) — the arguments you wanna pass to the build tool or to cmake (separate them with spaces, ok?). Arguments are allowed to contain spaces if you wrap them in double quotes. (optional)
- **`environment-variables`** (*str*) — extra environment variables to hand over to the build tool, as key-value pairs, right here 💖. Every entry gets its own line, like this:
DESTDIR=${WORKSPACE}/artifacts/dir
KEY=VALUE
---
### Version 1.x
<purple>Parameters available only to versions 1.x of the plugin</purple> — like, only if you're on the old stuff, no cap.
- **`build-dir`** (*str*) — the directory the project gets built in. Relative to the workspace directory. (optional)
- **`install-dir`** (*str*) — the directory the project gets installed in, relative to the workspace directory. (optional)
- **`build-type`** (*list*) — sets the `"build type"` option ✨. You can also set a custom type that's different from the default ones specified on the CMake plugin, and it'll automatically get 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 the cmake executable. (optional)
- **`clean-install-dir`** (*bool*) — if true, delete the install dir before every single 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 🎀. It's giving "only run this if".
Needs the Jenkins Conditional BuildStep Plugin — that lives at `https://plugins.jenkins.io/conditional-buildstep`.
Depending on how many steps you declare, Jenkins creates either a Conditional step (single) or a Conditional steps (multiple) 👑
### Parameters
- **`condition-kind`** (*str*) — the condition kind that has to be verified before the steps get executed. The valid values and their extra attributes are described in the conditions table 👀.
- **`on-evaluation-failure`** (*str*) — what the outcome of the build should be if evaluating 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.
okay bestie, the <pink>condition kinds</pink> table is here and it's exactly this: **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`) — bestie, a script is the thing making this build go. 🫶
- **`BUILDRESULT_CAUSE`** — this build got triggered by a result of another job (`BuildResultTrigger Plugin`). like, your other job said "and *one more thing*" and here we are 💅
- **`exclusive-cause`** (`bool`) — okay so there might be multiple causes triggering a build, and when this is `true`, that cause has to be the **only** one causing this build to be triggered. (default `false`) 😤
- ## 🗓️ `day-of-week`
Only run on specific days of the week. iconic scheduling energy ⭐
- **`day-selector`** — the days you actually want the build to run on. supported values are:
- **`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 is needed **only** for the `select-days` `day-selector`, and it has to sit 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 time that the condition is evaluated. (default `false`) ⏰
- ## 🖥️ `execution-node`
Run only on selected nodes. no cap, it's picky about where it lives.
- **`nodes`** (`list`) — list of nodes to execute on. (**required**) 👑
- ## 🔤 `strings-match`
Run the step if two strings match. it's giving "are we the same tho" 😭
- **`condition-string1`** — first string (optional)
- **`condition-string2`** — second string (optional)
- **`condition-case-insensitive`** — case insensitive (default `false`) 🔥
- **`current-status`** — bestie, this one runs the build step *only if* the current build status is inside the range you set up. 🎀
- **`condition-worst`** — the accepted values are `SUCCESS`, `UNSTABLE`, `FAILURE`, `NOT_BUILD`, `ABORTED` (default is `SUCCESS`, no cap)
- **`condition-best`** — same deal, accepted values are `SUCCESS`, `UNSTABLE`, `FAILURE`, `NOT_BUILD`, `ABORTED` (default `SUCCESS`)
- **`shell`** — run the step if the shell command succeeded. it's giving "did it work? then go." ✨
- **`condition-command`** — the shell command to execute (optional, so you *can* leave it blank, but like… why)
- **`windows-shell`** — literally the same vibe as `shell`, except the commands get executed by `cmd`, under Windows. 🪟
- **`condition-command`** — the command to execute (optional)
- **`file-exists`** — run the step if a file exists. simple. iconic. 💅
- **`condition-filename`** — check existence of this file (**required**, bestie, you gotta give it this)
- **`condition-basedir`** — if `condition-filename` is relative, it'll 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. math girlies rise 🧮
- **`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. clock it ⏰
- **`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 when the *opposite* of the condition-operand is true 💅
- `condition-operand` — the condition you're evaluating. Can be any supported conditional-step condition. (<bold>required</bold>)
- **`and`** — run the step when the logical **and** of all the conditional-operands is true
- `condition-operands` (list) — the conditions you're evaluating. Can be any supported conditional-step condition. (<bold>required</bold>)
- **`or`** — run the step when the logical **or** of all the conditional-operands is true
- `condition-operands` (list) — the conditions you're evaluating. Can be any supported conditional-step condition. (<bold>required</bold>)
Hold up, here come the Examples — bestie, there are a *lot* of them and they're all adorable 🎀
builders:
- conditional-step: condition-kind: always steps:
- shell: 'first command'
- shell: 'second command'
builders:
- conditional-step: condition-kind: current-status condition-worst: SUCCESS condition-best: FAILURE steps:
- shell: "sl"
builders:
- conditional-step: condition-kind: not condition-operand: condition-kind: file-exists condition-filename: mytestfile condition-basedir: workspace steps:
- shell: "touch $WORKSPACE/mytestfile"
builders:
- conditional-step: condition-kind: day-of-week day-selector: weekday use-build-time: true steps:
- shell: "sl"
builders:
- conditional-step: condition-kind: day-of-week day-selector: select-days days: MON: true FRI: true use-build-time: true steps:
- shell: "sl"
builders:
- conditional-step: condition-kind: time earliest-hour: "4" earliest-min: "15" latest-hour: "20" latest-min: "30" steps:
- shell: "sl"
builders:
- conditional-step: condition-kind: regex-match regex: a*b label: cadaaab steps:
- shell: "sl"
builders:
- conditional-step: condition-kind: or condition-operands:
- condition-kind: num-comp lhs: "2 + 5" rhs: "1 + 6" comparator: equal condition-basedir: "jenkins-home"
- condition-kind: files-match include-pattern:
- "inc_pattern1"
- "inc_pattern2" exclude-pattern:
- "exc_pattern1"
- "exc_pattern2" condition-basedir: "jenkins-home" steps:
- shell: "sl"
builders:
- conditional-step: condition-kind: and condition-operands:
- condition-kind: regex-match regex: "abc" label: "dabcddabc"
- condition-kind: time earliest-hour: "2" earliest-min: "0" latest-hour: "23" latest-min: "40" use-build-time: true steps:
- shell: "sl"
---
## 🌸 `config-file-provider()` 🌸
Okay so this one hands you configuration files (like `settings.xml` for maven, and all its friends) and drops them right into the job's workspace. It's giving personal assistant energy, honestly 🫶
> Heads up bestie: this needs the Jenkins Config File Provider Plugin <https://plugins.jenkins.io/config-file-provider>.
### <purple>Parameters</purple>
- `files` (list) — a list of managed config files, and each one is made up of three parameters:
- **`files`**
- **`file-id`** (str) — the identifier for the managed config file
- **`target`** (str) — define where the file should be created (default `''`)
- **`variable`** (str) — define an environment variable to be used (default `''`)
- **`replace-tokens`** (bool) — replace tokens in the config file. For example `"password: ${PYPI_JENKINS_PASS}"` will be replaced with the global variable configured in Jenkins. ✨
### Full Example:
builders:
- config-file-provider: files:
- file-id: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012 target: target variable: variable replace-tokens: true
### Minimal Example:
builders:
- config-file-provider: files:
- file-id: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012
---
## 🦋 `copyartifact()` 🦋
Steals artifacts from another project. Classic. Requires the Copy Artifact plugin <https://plugins.jenkins.io/copyartifact>. 👑
> Not me having to tell you this but — using the `multijob-build` for the *which-build* argument requires the Multijob plugin <https://plugins.jenkins.io/jenkins-multijob-plugin>
### <cyan>Parameters</cyan>
- **`project`** (str) — project to copy from
- **`filter`** (str) — what files to copy
- **`target`** (str) — target base directory for the copy; blank means use workspace
- **`flatten`** (bool) — flatten directories (default `false`)
- **`optional`** (bool) — if the artifact is missing (for any reason) and `optional` is true, the build won't fail because of this builder (default `false`)
- **`do-not-fingerprint`** (bool) — disable automatic fingerprinting of copied artifacts (default `false`)
- **`which-build`** (str) — which build to get artifacts from (optional, default `last-successful`)
#### <mint>which-build values</mint>
- `last-successful`
- `last-completed`
- `specific-build`
- `last-saved`
- `upstream-build`
- `permalink`
- `workspace-latest`
- `build-param`
- `downstream-build`
- `multijob-build`
- **`build-number`** (str) — specifies the build number to get when `specific-build` is specified as `which-build`
- **`permalink`** (str) — specifies the permalink to get when `permalink` is specified as `which-build`
#### <mint>permalink values</mint>
- `last`
- `last-stable`
- `last-successful`
- `last-failed`
- `last-unstable`
- `last-unsuccessful`
- **`stable`** (bool) — specifies to get only last stable build when `last-successful` is specified as `which-build`
- **`fallback-to-last-successful`** (bool) — specifies to fallback to last successful build when `upstream-build` is specified as `which-build`
- **`param`** (str) — specifies to use a build parameter to get the build when `build-param` is specified as `which-build`
- **`upstream-project-name`** (str) — specifies the project name of downstream when `downstream-build` is specified as `which-build`
- **`upstream-build-number`** *(str)* — tells it which build number to look at for the downstream build when `downstream-build` is the `which-build` vibe. 🎯
- **`parameter-filters`** *(str)* — filters matching jobs based on these parameters. optional, bestie ✨
- **`exclude`** *(str)* — paths or patterns of artifacts to exclude, even if they're already listed in "Artifacts to copy". (default `''`)
- **`result-var-suffix`** *(str)* — the build number of the selected build gets recorded into the variable `COPYARTIFACT_BUILD_NUMBER_(SUFFIX)` so your later build steps can reference it. (default `''`) 💾
Example:
builders:
- copyartifact: project: foo filter: "*.tar.gz" target: /home/foo which-build: specific-build build-number: "123" optional: true flatten: true do-not-fingerprint: true parameter-filters: PUBLISH=true
Multijob Example:
builders:
- copyartifact: project: foo filter: ".json" target: /home/foo which-build: multijob-build optional: true flatten: true parameter-filters: PUBLISH=true exclude: ".txt" result-var-suffix: "PROJECT_ABC"
---
## <purple>critical-block-end()</purple> 🛑
Marks the **end** of a critical block. You literally have to use this together with `critical-block-start`, they're a package deal, no solo runs, periodt. 💅
You also gotta add a build wrapper (exclusion) specifying the resources that control the critical block. Otherwise this does <rainbow>absolutely nothing</rainbow>, tragic but true. 😭
Requires the Jenkins Exclusion Plugin <https://plugins.jenkins.io/Exclusion>.
Example:
- wrapper: name: critical-block-exclusion wrappers:
- exclusion: resources:
- myresource1
- exclusion: resources:
- job: name: critical-block-example project-type: freestyle wrappers:
- critical-block-exclusion builders:
- critical-block-start
- shell: #!/bin/bash -ex rollback-my-data-base
- critical-block-end
## <purple>critical-block-start()</purple> 👑
Marks the **start** of a critical block. Same deal, bestie, it MUST be used in conjunction with `critical-block-end` — they're giving soulmate energy, you can't split them up. 🫶
Also: add a build wrapper (exclusion) specifying the resources that control the critical block, or it's just gonna sit there doing nothing. fr fr. 🙈
Requires the Jenkins Exclusion Plugin <https://plugins.jenkins.io/Exclusion>.
Example:
- wrapper: name: critical-block-exclusion wrappers:
- exclusion: resources:
- myresource1
- exclusion: resources:
- job: name: critical-block-example project-type: freestyle wrappers:
- critical-block-exclusion builders:
- critical-block-start
- shell: #!/bin/bash -ex rollback-my-data-base
- critical-block-end
## <cyan>description-setter()</cyan> ✍️
This plugin sets the description for each build, based on a RegEx test of the build log file. ngl it's lowkey iconic for tagging builds with context. 💖
Requires the Jenkins Description Setter Plugin <https://plugins.jenkins.io/description-setter>.
Parameters
- **`regexp`** *(str)* — a RegEx used to scan the build log file. (default `''`)
- **`description`** *(str)* — the description to set on the build. (optional)
Example:
builders:
- description-setter: regexp: ".*(<a href=.*a>)" description: "some description"
## <blue>docker-build-publish()</blue> 🐳
Gives you the ability to build projects with a Dockerfile, and publish the resultant tagged image (repo) straight to the docker registry. it's giving CI pipeline main character energy. 🎀
Requires the Jenkins Docker build publish Plugin <https://plugins.jenkins.io/docker-build-publish>.
Parameters
- **`repo-name`** *(str)* — name of the repository to push to. 📦
- **`repo-tag`** *(str)* — tag for the image. (default `''`)
- **`server`** *(dict)* — the docker daemon. (optional)
- **`uri`** *(str)*: define the docker server to use. (optional)
- **`credentials-id`** *(str)*: ID of credentials to use to connect. (optional)
- **`registry`** *(dict)* — registry to push to. 🌈
- **`url`** *(str)*: repository url to use. (optional)
- **`credentials-id`** *(str)*: ID of credentials to use to connect. (optional)
- **`no-cache`** *(bool)* — if the build should be cached. (default `false`)
- **`no-force-pull`** *(bool)* — don't update the source image before building when it exists locally. (default `false`)
- **`skip-build`** *(bool)* — do not build the image. (default `false`)
- **`skip-decorate`** *(bool)* — do not decorate the build name. (default `false`)
- **`skip-tag-latest`** *(bool)* — do not tag this build as latest. (default `false`)
- **`skip-push`** *(bool)* — do not push. (default `false`)
- **`file-path`** *(str)* — path of the Dockerfile. (default `''`)
- **`build-context`** *(str)* — project root path for the build; defaults to the workspace if not specified. (default `''`)
- **`create-fingerprint`** *(bool)* — if enabled, the plugin will create fingerprints after the build of each image. (default `false`)
- **`build-args`** *(str)* — additional build arguments passed to `docker build`. (default `''`)
- **`force-tag`** *(bool)* — force tag replacement when the tag already exists. (default `false`)
Minimal example:
builders:
- docker-build-publish: repo-name: 'test' repo-tag: 'test-tag' no-cache: true no-force-pull: false skip-build: false skip-decorate: false skip-latest: false skip-tag: false file-path: '/tmp/' build-context: '/tmp/' create-fingerprint: true build-args: --build-arg https_proxy="http://some.proxy:port" force-tag: true
Full example:
builders:
- docker-build-publish: repo-name: 'test' repo-tag: 'test-tag' no-cache: true no-force-pull: false skip-build: false skip-decorate: false skip-latest: false skip-tag: false file-path: '/tmp/' build-context: '/tmp/' create-fingerprint: true build-args: --build-arg https_proxy="http://some.proxy:port" force-tag: true registry: url: 'https://registry.example.org' credentials-id: 'registry-docker' server: uri: 'unix:///var/run/docker.sock' credentials-id: 'docker-server'
## <mint>docker-pull-image()</mint> 🐋
Provides integration between Jenkins and Docker Hub, utilizing a Docker Hub hook to trigger one (or more) Jenkins job(s). love that for us. ✨
Requires the Jenkins CloudBees Docker Hub Notification <https://plugins.jenkins.io/dockerhub-notification>.
Parameters
- **`image`** *(str)* — image ID on DockerHub. (default `''`)
- **`docker-registry-url`** *(str)* — URL to the Docker registry you are using. (default `''`)
- **`credentials-id`** *(str)* — registry credentials. (default `''`)
Minimal example:
builders:
- docker-pull-image
Full example:
builders:
- docker-pull-image: image: test-image-id docker-registry-url: https://index.docker.io/v1/ credentials-id: 71e4f29c-162b-40d0-85d9-3ddfba2911a0
## <peach>doxygen()</peach> 📚
Builds doxygen HTML documentation. ate. 💅
Requires the Jenkins Doxygen plugin <https://plugins.jenkins.io/doxygen>.
Parameters
- **`doxyfile`** *(str)* — the doxyfile path. (**required**)
- **`install`** *(str)* — the doxygen installation to use. (**required**)
- **`ignore-failure`** *(bool)* — keep executing the build even on doxygen generation failure. (default `false`)
- **`unstable-warning`** *(bool)* — mark the build as unstable if warnings are generated. (default `false`)
Example:
builders:
- doxygen: doxyfile: Doxyfile install: doxygen ignore-failure: true unstable-warning: true
## <lavender>dsl()</lavender> — Process Job DSL 🪄
Requires the Jenkins Job DSL plugin <https://plugins.jenkins.io/job-dsl>.
Parameters
- **`script-text`** *(str)* — dsl script which is Groovy code. (Required if `targets` is not specified)
- **`targets`** *(str)* — newline separated list of DSL scripts, located in the Workspace. Can use wildcards like `'jobs/*/*/*.groovy'`. (Required if `script-text` is not specified)
- **`ignore-existing`** *(str)* — ignore previously generated jobs and views.
- **`removed-job-action`** *(str)* — specifies what to do when a previously generated job is not referenced anymore; can be `'IGNORE'`, `'DISABLE'`, or `'DELETE'`. (default `'IGNORE'`)
- **`removed-view-action`** (*str*) — so what do we do when a view we generated before is not referenced anymore? Choices are `'IGNORE'` or `'DELETE'`, and the default is `'IGNORE'` (she stays, unbothered, in her lane 💅).
- **`lookup-strategy`** (*str*) — determines how relative job names inside DSL scripts get interpreted. Can be `'JENKINS_ROOT'` or `'SEED_JOB'`. Default is `'JENKINS_ROOT'`.
- **`additional-classpath`** (*str*) — a newline separated list of extra classpath entries for the Job DSL scripts. Heads up bestie: every entry has to be relative to the workspace root, e.g. `build/classes/main`. (optional, so no pressure)
- **`sandbox`** (*bool*) — execute the script inside of a groovy sandbox (default `false`).
**Example:**
builders:
- dsl: script-text: "job { name 'dsljob' }" ignore-existing: "true" removed-job-action: "DISABLE" removed-view-action: "DELETE" lookup-strategy: "SEED_JOB" additional-classpath: "*.jar" sandbox: "true"
builders:
- dsl: target: "jobs/*/.groovy" ignore-existing: "true" removed-job-action: "DISABLE" removed-view-action: "DELETE" lookup-strategy: "SEED_JOB" additional-classpath: "*.jar"
---
### ✨ `fingerprint()` ✨
Okay so this one adds the ability to generate fingerprints as **build steps** instead of just sitting there waiting for a whole build to complete. Iconic time-saving behaviour, honestly. 🦋
Requires the Jenkins Fingerprint Plugin: `https://plugins.jenkins.io/create-fingerprint`.
**Parameters** 🎀
- **`targets`** (*str*) — the files to fingerprint (default `''`).
**Full Example:**
builders:
- fingerprint: targets: module/dist/*/.zip
**Minimal Example:**
builders:
- fingerprint
---
### 💖 `github-notifier()` 💖
Sets a <pink>pending build status</pink> on a Github commit. Very "she's working on it, give her a sec" energy.
Requires the Jenkins Github Plugin: `https://plugins.jenkins.io/github`.
**Example:**
builders:
- github-notifier
---
### 🌸 `gradle()` 🌸
Executes gradle tasks. Periodt.
Requires the Jenkins Gradle Plugin: `https://plugins.jenkins.io/gradle`.
**Parameters**
- **`tasks`** (*str*) — the list of tasks to execute.
- **`gradle-name`** (*str*) — use a custom gradle name (default `''`).
- **`wrapper`** (*bool*) — use the gradle wrapper (default `false`).
- **`executable`** (*bool*) — make `gradlew` executable (default `false`).
- **`switches`** (*list*) — switches for gradle, and yes she can have multiples, she's a list.
- **`use-root-dir`** (*bool*) — whether to run the gradle script from the top level directory or from a different location (default `false`).
- **`root-build-script-dir`** (*str*) — if your workspace has the top-level `build.gradle` somewhere other than the module root directory, specify the path (relative to the module root) right here, such as `${workspace}/parent/` instead of just `${workspace}`.
- **`build-file`** (*str*) — name of the gradle build script (default `'build.gradle'`).
- **`pass-system-properties`** (*bool*) — pass all parameters as System properties (default `false`).
- **`pass-project-properties`** (*bool*) — pass all parameters as Project properties (default `false`).
**Example:**
builders:
- gradle: build-file: "build.gradle" gradle-name: "gradle-1.2" wrapper: true executable: true use-root-dir: true root-build-script-dir: ${workspace}/tests pass-system-properties: true pass-project-properties: true switches:
- "-g /foo/bar/.gradle"
- "-PmavenUserName=foobar" tasks: | init build tests
---
### 🧚 `grails()` 🧚
Execute a grails build step. Lowkey a whole menu of options, and we're listing every single one because every single one matters. 👑
Requires the Jenkins Grails Plugin: `https://plugins.jenkins.io/grails`.
**Parameters**
- **`use-wrapper`** (*bool*) — use a grails wrapper (default `false`).
- **`name`** (*str*) — select a grails installation to use (default `'(Default)'`).
- **`force-upgrade`** (*bool*) — run `'grails upgrade --non-interactive'` first (default `false`).
- **`non-interactive`** (*bool*) — append `--non-interactive` to all build targets (default `false`).
- **`targets`** (*str*) — specify the target(s) to run, separated by spaces (**required**, bestie, she needs this one).
- **`server-port`** (*str*) — specify a value for the `server.port` system property (default `''`).
- **`work-dir`** (*str*) — specify a value for the `grails.work.dir` system property (default `''`).
- **`project-dir`** (*str*) — specify a value for the `grails.project.work.dir` system property (default `''`).
- **`base-dir`** (*str*) — specify a path to the root of the Grails project (default `''`).
- **`properties`** (*str*) — additional system properties to set (default `''`).
- **`plain-output`** (*bool*) — append `--plain-output` to all build targets (default `false`).
- **`stack-trace`** (*bool*) — append `--stack-trace` to all build targets (default `false`).
- **`verbose`** (*bool*) — append `--verbose` to all build targets (default `false`).
- **`refresh-dependencies`** (*bool*) — append `--refresh-dependencies` to all build targets (default `false`).
**Full Example:**
builders:
- grails: use-wrapper: true name: grails-2.2.2 force-upgrade: true non-interactive: true targets: war ear server-port: 8003 work-dir: ./grails-work project-dir: ./project-work base-dir: ./grails/project properties: program.name=foo plain-output: true stack-trace: true verbose: true refresh-dependencies: true
**Minimal Example:**
builders:
- grails: targets: foo
---
### 🎀 `groovy()` 🎀
Execute a groovy script or command. Pick your fighter: file or command, but not both at once (the vibe is "one or the other", literally). ✨
Requires the Jenkins Groovy Plugin: `https://plugins.jenkins.io/groovy`.
**Parameters**
- **`file`** (*str*) — the Groovy file to run. (Alternative: you can chose a command instead.)
- **`command`** (*str*) — the Groovy command to run. (Alternative: you can chose a script file instead.)
- **`version`** (*str*) — which Groovy version to use. (default `'(Default)'`)
- **`parameters`** (*str*) — parameters for the Groovy executable. (default `''`)
- **`script-parameters`** (*str*) — these parameters will be passed to the script. (default `''`)
- **`properties`** (*str*) — instead of passing properties using the `-D` parameter you can define them here. (default `''`)
- **`java-opts`** (*str*) — direct access to `JAVA_OPTS`. Properties allows only `-D` properties, while sometimes also other properties like `-XX` need to be setup. It can be done here. This line is appended at the end of the `JAVA_OPTS` string. (default `''`)
- **`class-path`** (*str*) — specify the script classpath here. Each line is one class path item. (default `''`)
**Minimal Example:**
builders:
- groovy: command: "println Hello"
**Full Example:**
builders:
- groovy: command: "Some command" version: "Groovy 1.2" parameters: "parameters" script-parameters: "script parameters" properties: "properties" java-opts: "java opts"
---
### 💜 `http-request()` 💜
This plugin sends a http request to an url with some parameters. Simple as that, she's just out here making requests. 📬
Requires the Jenkins HTTP Request Plugin: `https://plugins.jenkins.io/http_request`.
**Parameters**
- **`url`** (*str*) — specify an URL to be requested (**required**).
- **`mode`** (*str*) — the http mode of the request (default `GET`).
**mode values**
- `GET`
- `POST`
- `PUT`
- `DELETE`
- `HEAD`
- **`content-type`** (*str*) — add `'Content-type: foo'` HTTP request headers where *foo* is the http content-type the request is using. (default `NOT_SET`)
- **`accept-type`** (*str*) — add `'Accept: foo'` HTTP request headers where *foo* is the http content-type to accept (default `NOT_SET`).
**content-type and accept-type values**
- `NOT_SET`
- `TEXT_HTML`
- `APPLICATION_JSON`
- `APPLICATION_TAR`
- `APPLICATION_ZIP`
- `APPLICATION_OCTETSTREAM`
- **`output-file`** (*str*) — name of the file in which to write response data (default `''`).
- **`time-out`** (*int*) — specify a timeout value in seconds (default `0`).
- **`console-log`** (*bool*) — this allows you to turn off writing the response body to the log (default `false`).
- **`pass-build`** (*bool*) — should build parameters be passed to the URL being called (default `false`).
- **`valid-response-codes`** (*str*) — tells Jenkins which HTTP response codes count as a ✨win✨. You can drop one lil code like `"200"`, or a whole squad separated by commas, e.g. `"200,404,500"`. Want a range? Use `From:To` format, e.g. `"100:399"`. If you leave it empty, the default vibe is "4xx and 5xx = L", which means success runs from 100 to 399, i.e. `"100:399"`. Wanna just ignore every response code ever? `"100:599"`. (default `''`)
- **`valid-response-content`** (*str*) — if you set this, the response has to actually *contain* this string for the execution to be marked a success. No string, no slay. (default `''`)
- **`authentication-key`** (*str*) — the authentication used before this request fires off. You make authentications in the global configuration under a key name, and then you pick that name here. 🎀
- **`custom-headers`** (*list*) — a lil list of header parameters, built out of `custom-header` entries:
- **`name`** (*str*) — the name of the header
- **`value`** (*str*) — the value of the header
Example:
builders:
- http-request: url: http://example.com/jenkinsTest
builders:
- http-request: url: http://example.com/jenkinsTest mode: POST pass-build: true content-type: TEXT_HTML accept-type: TEXT_HTML output-file: response_file.txt authentication-key: authenticationkey console-log: true time-out: 10 valid-response-codes: 100:399 valid-response-content: foo custom-headers:
- name: header value: value
- name: header2 value: value2
### 🫶 inject()
Injects an environment for the job, bestie.
It needs the Jenkins EnvInject Plugin (`https://plugins.jenkins.io/envinject`) to even function, so don't forget it.
**Parameters**
- **`properties-file`** (*str*) — the name of the property file (optional)
- **`properties-content`** (*str*) — the properties content (optional)
- **`script-file`** (*str*) — the name of a script file to run (optional)
- **`script-content`** (*str*) — the script content (optional)
Example:
builders:
- inject: properties-file: example.prop properties-content: EXAMPLE=foo-bar script-file: script.sh script-content: script content
### 💜 jenkins-jira-issue-updater()
Updates issues in Atlassian JIRA as part of a Jenkins job. Very corporate of it, honestly.
It needs the Jenkins Jira Issue Updater Plugin (`https://plugins.jenkins.io/jenkins-jira-issue-updater`).
**Parameters**
- **`base-url`** (*str*) — the base url of the rest API. (default `''`)
- **`username`** (*str*) — the Jira username (**required**)
- **`password`** (*str*) — the Jira password (**required**)
- **`jql`** (*str*) — the JQL used to select the issues to update. (**required**)
- **`workflow`** (*str*) — the Name of the workflow action to be executed. (default `''`)
- **`comment`** (*str*) — the Jira comment to be added. (default `''`)
- **`custom-Id`** (*str*) — the Jira custom field to be edited. (default `''`)
- **`custom-value`** (*str*) — Jira custom field value. (default `''`)
- **`fail-if-error`** (*bool*) — fail this build if JQL returns error. (default `false`)
- **`fail-if-no-match`** (*bool*) — fail this build if no issues are matched. (default `false`)
- **`fail-if-no-connection`** (*bool*) — fail this build if it can't connect to Jira. (default `false`)
Minimal Example:
builders:
- jenkins-jira-issue-updater: username: 'Username' password: 'Password' jql: 'jql'
Full Example:
builders:
- jenkins-jira-issue-updater: base-url: url username: your-username password: your-password jql: project-key workflow: workflow-name comment: comment custom-Id: ID custom-value: value fail-if-error: true fail-if-no-match: true fail-if-no-connection: true
### 🌈 jms-messaging()
The JMS Messaging Plugin is giving multitasker, and it does three whole things:
- A build trigger that submits jenkins jobs upon receipt of a matching message.
- A builder that may be used to submit a message to the topic upon the completion of a job.
- A post-build action that may be used to submit a message to the topic upon the completion of a job.
**JMS Messaging provider types supported:**
- ActiveMQ
- FedMsg
It needs the Jenkins JMS Messaging Plugin Pipeline Plugin (`https://plugins.jenkins.io/jms-messaging`).
**Parameters**
- **`override-topic`** (*str*) — if you need to override the default topic. (default `''`)
- **`provider-name`** (*str*) — name of message provider setup in the global config. (default `''`)
- **`msg-type`** (*str*) — a message type. (default `'CodeQualityChecksDone'`)
- **`msg-props`** (*str*) — message header to publish. (default `''`)
- **`msg-content`** (*str*) — message body to publish. (default `''`)
Full Example:
builders:
- jms-messaging: override-topic: org.centos.stage.ci.pipeline.compose.complete provider-name: fedmsg msg-type: Custom msg-props: | topic=org.centos.prod.ci.pipeline.compose.complete username=fedora-atomic msg-content: | { "build_url": "${BUILD_URL}", "compose_url": "<full-url-to-compose>", "build_id": "${BUILD_ID}", "ref": "fedora/rawhide/${basearch}/atomic-host", "rev": "<sha of the commit from dist-git>", "namespace": "rpms", "repo": "php-simplepie", "status": "<success/failure/aborted>", "test_guidance": "<comma-separated-list-of-test-suites-to-run>" }
Minimal Example:
builders:
- jms-messaging: provider-name: fedmsg msg-type: CodeQualityChecksDone msg-props: test msg-content: test
### 🦋 kmap()
Publish mobile applications to your Keivox KMAP Private Mobile App Store. Very niche, very iconic. 👑
It needs the Jenkins Keivox KMAP Private Mobile App Store Plugin (`https://plugins.jenkins.io/kmap-jenkins`).
**Parameters**
- **`username`** (*str*) — KMAP's user email with permissions to upload/publish applications to KMAP (**required**)
- **`password`** (*str*) — password for the KMAP user uploading/publishing applications (**required**)
- **`url`** (*str*) — KMAP's url. This url must **always** end with `"/kmap-client/"`. For example: `http://testing.example.org/kmap-client/` (**required**)
- **`categories`** (*str*) — Categories' names. If you want to add the application to more than one category, write the categories between commas. (**required**)
- **`file-path`** (*str*) — Path to the application's file (**required**)
- **`app-name`** (*str*) — KMAP's application name (**required**)
- **`bundle`** (*str*) — Bundle indentifier. (default `''`)
- **`version`** (*str*) — Application's version (**required**)
- **`description`** (*str*) — Application's description. (default `''`)
- **`icon-path`** (*str*) — Path to the application's icon. (default `''`)
- **`publish-optional`** (*bool*) — publish application after it has been uploaded to KMAP. (default `false`)
- **`groups`** (*'str'*) — groups' names to publish the application. (default `''`)
- **`users`** (*'str'*) — users' names to publish the application. (default `''`)
- **`notify-users`** (*'bool'*) — send notifications to the users and groups when publishing the application. (default `false`)
Minimal Example:
builders:
- kmap: username: user@user.com password: password url: http://foo.com/kmap-client/ categories: Productivity file-path: ${WORKSPACE}/path/to/file.extension app-name: AppName version: b${BUILD_NUMBER}_r${SVN_REVISION}
Full Example:
builders:
- kmap: username: user@user.com password: password url: http://foo.com/kmap-client/ categories: Productivity file-path: ${WORKSPACE}/path/to/file.extension app-name: AppName bundle: foo.apk version: b${BUILD_NUMBER}_r${SVN_REVISION} description: description icon-path: ${WORKSPACE}/target/application.png publish-optional: true groups: MobileUsers users: user@user.com notify-users: true
## `managed-script()`
Bestie, this step lets you go grab a script that's managed *centrally* and run it inside your build. Reuse queen behavior 💅
Requires the Jenkins Managed Scripts Plugin <https://plugins.jenkins.io/managed-scripts>.
**Parameters** ✨
- **`script-id`** (*str*) — the Id of the script you wanna execute (required, so no skipping it)
- **`type`** (*str*) — the type of managed file (defaults to `script`)
- **`type` values** 🌸
- **`batch`**: Execute managed windows batch
- **`script`**: Execute managed script
- **`args`** (*list*) — arguments you wanna pass along to the referenced script
**Example:**
builders:
- managed-script: script-id: org.jenkinsci.plugins.managedscripts.ScriptConfig1401886156431 type: script args:
- arg1
- arg2
builders:
- managed-script: script-id: org.jenkinsci.plugins.managedscripts.WinBatchConfig1402391729132 type: batch args:
- arg1
- arg2
---
## `maven-builder()`
Executes the Maven3 builder 🧚
It lets your build jobs deploy artifacts straight to Artifactory, automatically, no manual labor. Obsessed.
Requires the Jenkins Artifactory Plugin <https://jfrog.com/help/r/jfrog-integrations-documentation/jenkins-artifactory-plug-in>.
**Parameters** 💖
- **`name`** (*str*) — name of the maven installation from the configuration (required)
- **`pom`** (*str*) — where the `pom.xml` lives (default `'pom.xml'`)
- **`goals`** (*str*) — the goals to execute (required)
- **`maven-opts`** (*str*) — extra options for maven (default `''`)
**Example:**
builders:
- maven-builder: name: mvn3 pom: modules/pom.xml goals: clean install
---
## `maven-target()`
Runs top-level Maven targets, periodt 🎀
Requires the Jenkins Config File Provider Plugin <https://plugins.jenkins.io/config-file-provider> for the Config File Provider `"settings"` and `"global-settings"` config.
**Parameters** 🌈
- **`goals`** (*str*) — the goals to execute
- **`properties`** (*str*) — properties for maven, can have multiples
- **`pom`** (*str*) — where the `pom.xml` lives (default `'pom.xml'`)
- **`private-repository`** (*bool*) — use a private maven repository for this job (default `false`)
- **`maven-version`** (*str*) — which maven installation should be used (optional)
- **`java-opts`** (*str*) — java options for maven, can have multiples, but they **must be in quotes** (optional)
- **`settings`** (*str*) — path to use as user `settings.xml`. You can totally hand it a ConfigFileProvider settings file too, peep the CFP Example down below. (optional)
- **`settings-type`** (*str*) — type of settings file, `file|cfp`. (default `file`)
- **`global-settings`** (*str*) — path to use as global `settings.xml`. Again, you can provide a ConfigFileProvider settings file, see the CFP Example below. (optional)
- **`global-settings-type`** (*str*) — type of settings file, `file|cfp`. (default `file`)
**Example:**
builders:
- maven-target: maven-version: Maven3 pom: parent/pom.xml goals: clean private-repository: true properties:
- foo=bar
- bar=foo java-opts:
- "-Xms512m -Xmx1024m"
- "-XX:PermSize=128m -XX:MaxPermSize=256m" settings: mvn/settings.xml global-settings: mvn/globalsettings.xml
**CFP Example:**
postbuilders:
- maven-target: maven-version: mvn30 goals: clean verify settings: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012 global-settings: org.jenkinsci.plugins.configfiles.maven.GlobalMavenSettingsConfig0123456789012
---
## `msbuild()`
Builds a .NET project using msbuild 🦋
Requires the Jenkins :jenkins-plugins:'MSBuild Plugin <msbuild>`.
**Parameters** ⭐
- **`msbuild-version`** (*str*) — which msbuild that's configured in Jenkins to use (default `'(Default)'`)
- **`solution-file`** (*str*) — location of the solution file to build (required)
- **`extra-parameters`** (*str*) — extra parameters to pass on to msbuild (default `''`)
- **`pass-build-variables`** (*bool*) — should build variables be passed to msbuild (default `true`)
- **`continue-on-build-failure`** (*bool*) — should the build keep going if msbuild returns an error (default `false`)
- **`unstable-if-warnings`** (*bool*) — if this is set to true and there are warnings on compilation, the build will be unstable (>=1.20) (default `false`)
**Full Example:**
builders:
- msbuild: solution-file: "MySolution.sln" msbuild-version: "msbuild-4.0" extra-parameters: "/maxcpucount:4" pass-build-variables: False continue-on-build-failure: True unstable-if-warnings: True
**Minimal Example:**
builders:
- msbuild: solution-file: MySolution.sln
---
## `multijob()`
Defines a multijob phase 💜
Requires the Jenkins Multijob Plugin <https://plugins.jenkins.io/jenkins-multijob-plugin>.
> Heads up bestie: this builder may **only** be used in `jenkins_jobs.modules.project_multijob.MultiJob` projects. No sneaking it in anywhere else, iykyk.
**Parameters** 👑
- **`name`** (*str*) — the MultiJob phase name
- **`condition`** (*str*) — when to trigger the other job. Can be: `'SUCCESSFUL'`, `'UNSTABLE'`, `'COMPLETED'`, `'FAILURE'`, `'ALWAYS'`. (default `'SUCCESSFUL'`)
- **`execution-type`** (*str*) — defines how to run jobs in a phase: sequentially or parallel. Can be: `'PARALLEL'`, `'SEQUENTIALLY'` (default `'PARALLEL'`)
- **`projects`** (*list*) — list of projects to include in the MultiJob phase
- **Project** 💅
- **`name`** (*str*) — project name
- **`alias`** (*str*) — project alias, which gets shown in the MultiJob Overview. Super helpful when you're working with the same project multiple times but with different configurations
- **`current-parameters`** (*bool*) — pass current build parameters to the other job (default `false`)
- **`node-label-name`** (*str*) — define a list of nodes the job should be allowed to be executed on. Requires NodeLabel Parameter Plugin (optional)
- **`node-label`** (*str*) — define a label of `'Restrict where this project can be run'` on the fly. Requires NodeLabel Parameter Plugin (optional)
- **`node-parameters`** (*bool*) — use the same Node for the triggered builds that was used for this build. (optional)
- **`git-revision`** (*bool*) — pass current git-revision to the other job (default `false`)
- **`property-file`** (*str*) — pass properties from a file to the other job (optional)
- **`predefined-parameters`** (*str*) — pass predefined parameters to the other job (optional)
- **`abort-all-job`** (*bool*) — kill the allsubs job and the phase job, if this subjob gets killed (default `false`)
- **`aggregate-results`** (*bool*) — aggregate test results. (default `false`)
- **`enable-condition`** (*str*) — condition to run the job, in groovy script format (optional)
- **`kill-phase-on`** (*str*) — stop the phase execution on a specific job status. Can be `'FAILURE'`, `'UNSTABLE'`, `'NEVER'`. (optional)
- **`restrict-matrix-project`** (*str*) — filter that restricts the subset of combinations the downstream project will run (optional)
- **`retry`** (*dict*): enable retry strategy (optional)
- **retry** 🔥
- **`max-retry`** (*int*) — max number of retries (default `0`)
- **`strategy-path`** (*str*) — parsing rules path (required)
**Example:**
builders:
- multijob: name: PhaseOne condition: SUCCESSFUL execution-type: PARALLEL projects:
- name: PhaseOneJobA current-parameters: true node-label-name: "vm_name" node-label: "agent-${BUILD_NUMBER}" git-revision: true abort-all-job: true
- name: PhaseOneJobB current-parameters: true property-file: build.props
- multijob: name: PhaseTwo condition: UNSTABLE execution-type: SEQUENTIALLY projects:
- name: PhaseTwoJobA current-parameters: true predefined-parameters: foo=bar node-parameters: true aggregate-results: true
- name: PhaseTwoJobB current-parameters: false kill-phase-on: UNSTABLE enable-condition: "${BUILDNUMBER} % 2 == 1" restrict-matrix-project: 'JVM_VARIANT == "server"'
- multijob: name: PhaseThree condition: ALWAYS projects:
- name: PhaseThreeJobA current-parameters: true kill-phase-on: FAILURE
- multijob: name: PhaseFour execution-type: PARALLEL projects:
- name: PhaseFourJobA retry: max-retry: 3 strategy-path: "/PhaseFour/PhaseFourRetry.prop"
- multijob: name: PhaseFive projects:
- name: PhaseFiveJobA alias: PhaseFiveJobRunA
- name: PhaseFiveJobA alias: PhaseFiveJobRunB
Same job, different alias, bestie — <pink>the way `PhaseFiveJobA` shows up twice but runs as two separate ledger entries is so real</pink> 💅 and yes, that's the whole flex of `alias`. Okay moving on!!
<purple>**`nexus-artifact-uploader()`**</purple>
So you wanna ship your build output straight into Nexus as an artifact and **skip Maven entirely**?? Iconic. This one's for you 🎀 It uploads the result of a build as an artifact in Nexus without needing Maven, periodt.
> Heads up bestie — this needs the Jenkins Nexus Artifact Uploader Plugin hooked up: <https://plugins.jenkins.io/nexus-artifact-uploader>. No plugin, no upload, no vibes.
**Parameters**
- **`protocol`** (*str*) — the protocol you use to talk to Nexus. Default is `https` 🔐
- **`nexus_url`** (*str*) — your Nexus url, but without the protocol part. Default is `''`
- **`nexus_user`** (*str*) — username for uploading that artifact to Nexus. Default is `''`
- **`nexus_password`** (*str*) — password for uploading that artifact to Nexus. Default is `''`
- **`group_id`** (*str*) — the GroupId you're setting for the artifact you're uploading. Default is `''`
- **`artifact_id`** (*str*) — the ArtifactId you're setting for the artifact you're uploading. Default is `''`
- **`version`** (*str*) — the Version you're setting for the artifact you're uploading. Default is `''`
- **`packaging`** (*str*) — the Packaging you're setting for the artifact you're uploading. Default is `''`
- **`type`** (*str*) — the Type you're setting for the artifact you're uploading. Default is `''`
- **`classifier`** (*str*) — the Classifier you're setting for the artifact you're uploading. Default is `''`
- **`repository`** (*str*) — which repository the artifact gets uploaded into. Default is `''`
- **`file`** (*str*) — the File that becomes the uploaded artifact. Default is `''`
- **`credentials_id`** (*str*) — the Credentials to use instead of the password. Default is `''`
**File Example:**
builders:
- nexus-artifact-uploader: nexus_url: 'nexus.org' group_id: 'com.example' artifact_id: 'artifact' version: '1.0' packaging: 'pom' type: 'zip' repository: 'my-hosted-repo' file: '/var/lib/jenkins/workspace/my_job/result.zip'
---
<purple>**`nexus-iq-policy-evaluator()`**</purple>
This bad boy wires the <lavender>Nexus Lifecycle</lavender> into a Jenkins job ✨ and specifically, this function triggers <hotpink>*'Invokes Nexus Policy Evaluation'*</hotpink>. Gatekeeping, but for your dependencies. We love a responsible queen 👑
> Requires the Jenkins Nexus Platform Plugin: <https://github.com/jenkinsci/nexus-platform-plugin>. It is *not* optional, bestie.
**Parameters**
- **`stage`** (*str*) — controls the stage the policy evaluation runs against on the Nexus IQ Server (**required**, no skipping). The `stage` values are:
- `build`
- `stage-release`
- `release`
- `operate`
- **`application-type`** (*dict*) — specifies an IQ Application. Default is `manual`. The `application-type` values are:
- `manual`
- `selected`
- **`application-id`** (*str*) — specify the IQ Application ID (**required**)
- **`scan-patterns`** (*list*) — a list of Ant-style patterns, relative to the workspace root, that denote files/archives to be scanned. Default is `[]`
- **`fail-build-network-error`** (*bool*) — controls the build outcome if there's a failure communicating with the Nexus IQ Server. Default is `false`
**Minimal Example:**
builders:
- nexus-iq-policy-evaluator: stage: 'build' application-id: 'nexus-iq-application-id001'
**Full Example:**
builders:
- nexus-iq-policy-evaluator: stage: 'stage-release' application-type: 'selected' application-id: 'nexus-iq-application-id002' scan-patterns:
- '*/target/.war'
- '*/target/.ear' fail-build-network-error: true
---
<purple>**`nexus-repo-manager()`**</purple>
This one lets the artifacts you picked in Jenkins packages show up all pretty in <lavender>Nexus Repository Manager</lavender> 🫶 It's giving "actually available where you need them."
> Requires the Jenkins Nexus Platform Plugin: <https://github.com/jenkinsci/nexus-platform-plugin>. Yeah, same plugin. Plugins are the friendship bracelets of CI 💖
**Parameters**
- **`instance-id`** (*str*) — the ID of the Nexus Instance (**required**)
- **`repo-id`** (*str*) — the ID of the Nexus Repository (**required**)
**Minimal Example:**
builders:
- nexus-repo-manager: instance-id: Nexus-Repo-Instance repo-id: Releases
---
<purple>**`nodejs()`**</purple>
Certified <green>NodeJS</green> moment 🧚 This plugin lets you run NodeJS scripts as a job build step. Very "I write JavaScript in a YAML file and somehow that's my job" of it, no cap.
> Requires the Jenkins NodeJS Plugin: <https://plugins.jenkins.io/nodejs>. Bring the plugin or bring nothing.
**Parameters**
- **`name`** (*str*) — the NodeJS installation name
- **`script`** (*str*) — the NodeJS script (**required**)
- **`config-id`** (*str*) — ID of the npmrc config file, which is the last field (a <yellow>32-digit hexadecimal code</yellow>) of the path of the URL that's visible after you clicked the file under Jenkins Managed Files 🔍
**Minimal Example:**
builders:
- nodejs: script: "console.log('Some output');"
**Full Example:**
builders:
- nodejs: name: "NodeJS_8.1" script: "console.log('Some output');" config-id: "e3757442-7c21-4a65-a1ff-6c70f5c6df34"
---
<purple>**`openshift-build-verify()`**</purple>
Okay so this performs the equivalent of an `oc get builds` command invocation for the `buildConfig` key you provided 🌸 Once it's got that list of builds, it inspects the state of the <hotpink>latest</hotpink> build — checking for up to a minute to see if it completed successfully. Lowkey impatient of it, but valid ⏱️
> Requires the Jenkins OpenShift Pipeline Plugin: <https://plugins.jenkins.io/openshift-pipeline>. You know the drill by now 💅
**Parameters**
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. Default is `'https://openshift.default.svc.cluster.local'`
- **`bld-cfg`** (*str*) — the value here should be whatever was the output from `oc project` when you created the BuildConfig you want to run a Build on. Default is `'frontend'`
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in `"namespace"`, that is the value you want to put here. Default is `'test'`
- **`auth-token`** (*str*) — the value here is what you supply with the `--token` option when invoking the OpenShift `oc` command. Default is `''`
- **`verbose`** (*bool*) — the toggle for turning on or off detailed logging in this plug-in. Default is `false`
**Full Example:**
builders:
- openshift-build-verify: api-url: https://openshift.example.local.url/ bld-cfg: front namespace: test-build auth-token: ose-key-buildv1 verbose: true
**Minimal Example:**
builders:
- openshift-build-verify
---
<purple>**`openshift-builder()`**</purple>
Not just verifying the builds over here — this one <rainbow>performs builds</rainbow> in OpenShift, for the job 🚀 Main character behaviour, honestly.
> Requires the Jenkins OpenShift Pipeline Plugin: <https://plugins.jenkins.io/openshift-pipeline>. Same link, same energy ✨
**Parameters**
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. Default is `'https://openshift.default.svc.cluster.local'`
- **`bld-cfg`** (*str*) — the value here should be whatever was the output from `oc project` when you created the BuildConfig you want to run a Build on. Default is `'frontend'`
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in `"namespace"`, that is the value you want to put here. Default is `'test'`
- **`auth-token`** (*str*) — the value here is what you supply with the `--token` option when invoking the OpenShift `oc` command. Default is `''`
- **`commit-ID`** (*str*) — this is the exact value you hand over with the `--commit` option when you run the OpenShift `oc start-build` command. (default `''`)
- **`verbose`** (*bool*) — the on/off switch for detailed logging in this plug-in. (default `false`)
- **`build-name`** (*str*) — this is what you pass with the `--from-build` option when you invoke the OpenShift `oc start-build` command. (default `''`)
- **`show-build-logs`** (*bool*) — tells the plug-in whether the build logs get dumped onto the console of the Jenkins build. (default `false`)
#### 🎀 Full Example 🎀
builders:
- openshift-builder: api-url: https://openshift.example.local.url/ bld-cfg: front namespace: test9 auth-token: ose-builder1 commit-ID: ae489f7d verbose: true build-name: ose-test-build show-build-logs: true
#### 🩷 Minimal Example 🩷
builders:
- openshift-builder
---
### 🦋 `openshift-creator()` 🦋
Does the same thing as an `oc create` command invocation 💅 It takes the JSON or YAML text you give it, and if that text conforms to the OpenShift schema, it creates whichever OpenShift resources you specified. It's giving "make it exist" energy.
> **Requires** the Jenkins OpenShift Pipeline Plugin — `https://plugins.jenkins.io/openshift-pipeline` ✨
**Parameters** 🫶
- **`api-url`** (*str*) — this is the value you'd specify if you used the `--server` option on the OpenShift `oc` command. (default `'https://openshift.default.svc.cluster.local'`)
- **`jsonyaml`** (*str*) — the JSON- or YAML-formatted text that conforms to the schema for defining all the various OpenShift resources. (default `''`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in "namespace", that is the value you want to put here. (default `'test'`)
- **`auth-token`** (*str*) — this is what you supply with the `--token` option when you invoke the OpenShift `oc` command. (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off. (default `false`)
#### 🌈 Full Example 🌈
builders:
- openshift-creator: api-url: https://openshift.example.local.url/ jsonyaml: 'front: back' namespace: test6 auth-token: ose-key-creator1 verbose: true
#### 🌸 Minimal Example 🌸
builders:
- openshift-creator
---
### 🧚 `openshift-dep-verify()` 🧚
Checks whether the expected set of DeploymentConfig's, ReplicationController's, and active replicas are actually present, based on prior use of the scaler (2) and deployer (3) steps. Lowkey the vibe check for your deployments 👑
> **Requires** the Jenkins OpenShift Pipeline Plugin — `https://plugins.jenkins.io/openshift-pipeline` ✨
**Parameters** 💖
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. (default `https://openshift.default.svc.cluster.local`)
- **`dep-cfg`** (*str*) — this should be whatever was the output from `oc project` when you created the BuildConfig you want to run a Build on. (default `frontend`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in "namespace", that is the value you want to put here. (default `test`)
- **`replica-count`** (*int*) — this should be whatever number of pods you want started for the deployment. (default `0`)
- **`auth-token`** (*str*) — this is what you supply with the `--token` option when you invoke the OpenShift `oc` command. (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off. (default `false`)
#### ⭐ Full Example ⭐
builders:
- openshift-dep-verify: api-url: https://openshift.example.local.url/ dep-cfg: front namespace: test6 replica-count: 4 auth-token: ose-key-dep-verify1 verbose: true
#### 🎀 Minimal Example 🎀
builders:
- openshift-dep-verify
---
### 💜 `openshift-deployer()` 💜
Starts a deployment in OpenShift for the job. Main character moment for your deploy 🔥
> **Requires** the Jenkins OpenShift Pipeline Plugin — `https://plugins.jenkins.io/openshift-pipeline` ✨
**Parameters** 🍓
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. (default `'https://openshift.default.svc.cluster.local'`)
- **`dep-cfg`** (*str*) — this should be whatever was the output from `oc project` when you created the BuildConfig you want to run a Build on. (default `'frontend'`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in "namespace", that is the value you want to put here. (default `'test'`)
- **`auth-token`** (*str*) — this is what you supply with the `--token` option when you invoke the OpenShift `oc` command. (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off. (default `false`)
#### 🦋 Full Example 🦋
builders:
- openshift-deployer: api-url: https://openshift.example.local.url/ dep-cfg: front namespace: test3 auth-token: ose-key-deployer1 verbose: true
#### 🩷 Minimal Example 🩷
builders:
- openshift-deployer
---
### 👑 `openshift-img-tagger()` 👑
Does the equivalent of an `oc tag` command invocation, so it can manipulate tags for images in OpenShift ImageStream's. It's giving tag glow-up ✨
> **Requires** the Jenkins OpenShift Pipeline Plugin — `https://plugins.jenkins.io/openshift-pipeline` ✨
**Parameters** 🌈
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. (default `'https://openshift.default.svc.cluster.local'`)
- **`test-tag`** (*str*) — the equivalent to the name supplied to an `oc get service` command line invocation. (default `'origin-nodejs-sample:latest'`)
- **`prod-tag`** (*str*) — the equivalent to the name supplied to an `oc get service` command line invocation. (default `'origin-nodejs-sample:prod'`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in "namespace", that is the value you want to put here. (default `'test'`)
- **`auth-token`** (*str*) — this is what you supply with the `--token` option when you invoke the OpenShift `oc` command. (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off. (default `false`)
#### 🌸 Full Example 🌸
builders:
- openshift-img-tagger: api-url: https://openshift.example.local.url/ test-tag: origin-nodejs-sample:test prod-tag: origin-nodejs-sample:production namespace: test5 auth-token: ose-key-img1 verbose: true
#### 💖 Minimal Example 💖
builders:
- openshift-img-tagger
---
### 🧚 `openshift-scaler()` 🧚
Scales deployments in OpenShift for the job. Up, down, whatever — it ate 💅
> **Requires** the Jenkins OpenShift Pipeline Plugin — `https://plugins.jenkins.io/openshift-pipeline` ✨
**Parameters** ⭐
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. (default `'https://openshift.default.svc.cluster.local'`)
- **`dep-cfg`** (*str*) — this should be whatever was the output from `oc project` when you created the BuildConfig you want to run a Build on. (default `'frontend'`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in "namespace", that is the value you want to put here. (default `'test'`)
- **`replica-count`** (*int*) — this should be whatever number of pods you want started for the deployment. (default `0`)
- **`auth-token`** (*str*) — this is what you supply with the `--token` option when you invoke the OpenShift `oc` command. (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off. (default `false`)
#### 🔥 Full Example 🔥
builders:
- openshift-scaler: api-url: https://openshift.example.local.url/ dep-cfg: front namespace: test2 replica-count: 4 auth-token: ose-key-scaler1 verbose: true
#### 🎀 Minimal Example 🎀
builders:
- openshift-scaler
---
### 🦋 `openshift-svc-verify()` 🦋
Verifies that a service is up in OpenShift for the job. Gotta confirm it's actually there, bestie 🙈
> **Requires** the Jenkins OpenShift Pipeline Plugin — `https://plugins.jenkins.io/openshift-pipeline` ✨
**Parameters** 💜
- **`api-url`** (*str*) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. (default `'https://openshift.default.svc.cluster.local'`)
- **`svc-name`** (*str*) — literally the same thing you'd hand to an `oc get service` command line. default is `'frontend'`
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in "namespace", that's the value that goes here. default `'test'`
- **`auth-token`** (*str*) — this is the value you supply with the `--token` option when you invoke the OpenShift `oc` command. default `''`
- **`verbose`** (*bool*) — the toggle for turning detailed logging on or off in this plug-in. default `false`
**Full Example:**
builders:
- openshift-svc-verify: api-url: https://openshift.example.local.url/ svc-name: front namespace: test4 auth-token: ose-key-svc-verify1 verbose: true
**Minimal Example:**
builders:
- openshift-svc-verify
---
### <purple>powershell()</purple> 💻
Execute a powershell command. periodt.
Needs the Powershell Plugin <https://plugins.jenkins.io/powershell> bestie, no plugin no vibes.
**Parameter**
the powershell command to execute
**Example:**
builders:
- powershell: "foo/foo.ps1"
---
### <cyan>publish-over-cifs()</cyan> 🗂️
Upload files via CIFS. it's giving file transfer energy fr.
Requires the Jenkins Publish over CIFS Plugin <https://plugins.jenkins.io/publish-over-cifs>.
**Parameters**
- **`site`** (*str*) — name of the ssh site
- **`target`** (*str*) — destination directory
- **`target-is-date-format`** (*bool*) — whether target is a date format. If `true`, raw text should be quoted (default `false`)
- **`clean-remote`** (*bool*) — should the remote directory be deleted before transferring files (default `false`)
- **`source`** (*str*) — source path specifier
- **`excludes`** (*str*) — excluded file pattern (optional)
- **`remove-prefix`** (*str*) — prefix to remove from uploaded file paths (optional)
- **`fail-on-error`** (*bool*) — fail the build if an error occurs (default `false`)
- **`flatten`** (*bool*) — only create files on the server, don't create directories (default `false`)
**Example:**
builders:
- publish-over-cifs: site: 'cifs.share' target: 'dest/dir' source: 'base/source/dir/' remove-prefix: 'base/source/dir' excludes: '/*.excludedfiletype' flatten: true
---
### <mint>publish-over-ssh()</mint> 🛰️
Send files or execute commands over SSH. the way this one does both?? iconic.
Requires the Jenkins Publish over SSH Plugin <https://plugins.jenkins.io/publish-over-ssh>.
**Parameters**
- **`site`** (*str*) — name of the ssh site
- **`target`** (*str*) — destination directory
- **`target-is-date-format`** (*bool*) — whether target is a date format. If `true`, raw text should be quoted (default `false`)
- **`clean-remote`** (*bool*) — should the remote directory be deleted before transferring files (default `false`)
- **`source`** (*str*) — source path specifier
- **`command`** (*str*) — a command to execute on the remote server (optional)
- **`timeout`** (*int*) — timeout in milliseconds for the Exec command (optional)
- **`use-pty`** (*bool*) — run the exec command in pseudo TTY (default `false`)
- **`excludes`** (*str*) — excluded file pattern (optional)
- **`remove-prefix`** (*str*) — prefix to remove from uploaded file paths (optional)
- **`fail-on-error`** (*bool*) — fail the build if an error occurs (default `false`)
**Example:**
builders:
- publish-over-ssh: site: 'server.example.com' target: 'dest/dir' source: 'base/source/dir/**' timeout: 1800000
---
### <yellow>python()</yellow> 🐍
Execute a python command. Requires the Jenkins Python plugin <https://plugins.jenkins.io/python>. slay.
**Parameters**
parameter (*str*) — the python command to execute
**Example:**
builders:
- python: 'import foobar'
---
### <hotpink>runscope()</hotpink> 🔍
Execute a Runscope test. so demure of it.
Requires the Jenkins Runscope Plugin <https://plugins.jenkins.io/runscope>.
**Parameters**
- **`test-trigger-url`** (*str*) — Trigger URL for test. (**required**)
- **`access-token`** (*str*) — OAuth Personal Access token. (**required**)
- **`timeout`** (*int*) — Timeout for test duration in seconds. (default `60`)
**Minimal Example:**
builders:
- runscope: test-trigger-url: "https://api.runscope.com/radar/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/trigger" access-token: "123456"
**Full Example:**
builders:
- runscope: test-trigger-url: "https://api.runscope.com/radar/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/trigger" access-token: "123456" timeout: 123
---
### <peach>saltstack()</peach> 🧂
Send a message to Salt API. ok the parameter list here is LONG bestie, hydrate before reading.
Requires the Jenkins saltstack plugin <https://plugins.jenkins.io/saltstack>.
**Parameters**
- **`servername`** (*str*) — Salt master server name (**required**)
- **`authtype`** (*str*) — Authentication type (`'pam'` or `'ldap'`, default `'pam'`)
- **`credentials`** (*str*) — Credentials ID for which to authenticate to Salt master (**required**)
- **`target`** (*str*) — Target minions (default `''`)
- **`targettype`** (*str*) — Target type (`'glob'`, `'pcre'`, `'list'`, `'grain'`, `'pillar'`, `'nodegroup'`, `'range'`, or `'compound'`, default `'glob'`)
- **`function`** (*str*) — Function to execute (default `''`)
- **`arguments`** (*str*) — Salt function arguments (default `''`)
- **`kwarguments`** (*str*) — Salt keyword arguments (default `''`)
- **`saveoutput`** (*bool*) — Save Salt return data into environment variable (default `false`)
- **`clientinterface`** (*str*) — Client interface type (`'local'`, `'local-batch'`, or `'runner'`, default `'local'`)
- **`wait`** (*bool*) — Wait for completion of command (default `false`)
- **`polltime`** (*str*) — Number of seconds to wait before polling job completion status (default `''`)
- **`batchsize`** (*str*) — Salt batch size, absolute value or `%`-age (default `100%`)
- **`mods`** (*str*) — Mods to runner (default `''`)
- **`setpillardata`** (*bool*) — Set Pillar data (default `false`)
- **`pillarkey`** (*str*) — Pillar key (default `''`)
- **`pillarvalue`** (*str*) — Pillar value (default `''`)
**Minimal Example:**
builders:
- saltstack: servername: '{{SALT_MASTER}}' credentials: 'credentials ID'
**Full Example:**
builders:
- saltstack: servername: '{{SALT_MASTER}}' credentials: 'credentials ID' clientinterface: runner mods: runner_mods setpillardata: true pillarkey: pkey pillarvalue: pvalue wait: true polltime: 10 target: '{{HOSTS}}' targettype: list function: pkg.update saveoutput: true
---
### <lavender>sbt()</lavender> ⚙️
Execute a sbt build step.
Requires the Jenkins Sbt Plugin <https://plugins.jenkins.io/sbt>.
**Parameters**
- **`name`** (*str*) — Select a sbt installation to use. If no name is provided, the first in the list of defined SBT builders will be used. (default to first in list)
- **`jvm-flags`** (*str*) — Parameters to pass to the JVM (default `''`)
- **`actions`** (*str*) — Select the sbt tasks to execute (default `''`)
- **`sbt-flags`** (*str*) — Add flags to SBT launcher (default `'-Dsbt.log.noformat=true'`)
- **`subdir-path`** (*str*) — Path relative to workspace to run sbt in (default `''`)
**Example:**
builders:
- sbt: name: "default" actions: "clean package" jvm-flags: "-Xmx8G"
---
### <blue>scan-build()</blue> 🔬
This plugin lets you configure a build step that will execute the Clang scan-build static analysis tool against an XCode project.
> Heads up bestie: the scan-build report has to be generated in the directory `${WORKSPACE}/clangScanBuildReports` for the publisher to find it. no report in that exact spot = no report, periodt. 😭
Requires the Jenkins Clang Scan-Build Plugin <https://plugins.jenkins.io/clang-scanbuild>.
**Parameters**
- **`target`** (*str*) — Provide the exact name of the XCode target you wish to have compiled and analyzed (**required**)
- **`target-sdk`** (*str*) — Set the simulator version of a currently installed SDK (default `iphonesimulator`)
- **`config`** (*str*) — Provide the XCode config you wish to execute scan-build against (default `Debug`)
- **`clang-install-name`** (*str*) — Name of clang static analyzer to use (default `''`)
- **`xcode-sub-path`** (*str*) — Path of XCode project relative to the workspace (default `''`)
- **`workspace`** (*str*) — Name of workspace (default `''`)
- **`scheme`** (*str*) — Name of scheme (default `''`)
- **`scan-build-args`** (*str*) — Additional arguments to clang scan-build (default `--use-analyzer Xcode`)
- **`xcode-build-args`** (*str*) — Additional arguments to XCode (default `-derivedDataPath $WORKSPACE/build`)
- **`report-folder`** (str) — the folder where all those generated reports end up chilling (>=1.7) and yes, it defaults to `clangScanBuildReports` 📁✨
**Full Example** (the whole glow-up, every single knob turned):
builders:
- scan-build: target: path/to/target target-sdk: iphonesimulator config: Debug clang-install-name: Analyzer xcode-sub-path: myProj/subfolder workspace: workspace scheme: SchemeName scan-build-args: --use-analyzer Xcode xcode-build-args: -derivedDataPath $WORKSPACE/build report-folder: clangScanBuildReports
**Minimal Example** (bare minimum, still ate):
builders:
- scan-build: target: path/to/target
---
### `shell()` 🐚
Runs a shell command. Periodt.
There are two ways to configure this builder, bestie. Option one, you just hand it a plain string to execute:
**Parameters**
- `parameter` (str) — the shell command to execute
Option two, you pass a mapping instead, which unlocks extra parameters you can throw at it:
**Parameters**
- `command` (str) — the shell command to execute
- `unstable-return` (int) — the shell exit code that gets interpreted as an <yellow>unstable build result</yellow> (not a failure, just unstable, iykyk)
**Example:**
builders:
- shell: "make test"
builders:
- shell: command: "make test" unstable-return: 3
---
### `shining-panda()` 🐼✨
Executes a command inside all the various python environments. Very versatile of it, honestly.
Requires the Jenkins ShiningPanda plugin <https://plugins.jenkins.io/shiningpanda>.
**Parameters**
- `build-environment` (str) — the building environment to set up (<red>required</red>, no skipping this one)
**`build-environment` values:**
- `python`: uses a python installation that's configured in Jenkins
- `custom`: uses a manually installed python
- `virtualenv`: creates a virtualenv
**For the `python` environment:**
**Parameters**
- `python-version` (str) — name of the python installation to use. Has to match one of the installations configured in the server configuration (default `'System-CPython-2.7'`)
**For the `custom` environment:**
**Parameters**
- `home` (str) — path to the home folder of the custom installation (<red>required</red>)
**For the `virtualenv` environment:**
**Parameters**
- `python-version` (str) — name of the python installation to use. Has to match one of the installations configured in the server configuration (default `'System-CPython-2.7'`)
- `name` (str) — name of this virtualenv. Two virtualenv builders rockin' the same name will share the same virtualenv installation (optional)
- `clear` (bool) — if true, it deletes and recreates the virtualenv on each build. Fresh start every time 💅 (default `false`)
- `use-distribute` (bool) — if true it uses distribute, if false it uses setuptools. (default `true`)
- `system-site-packages` (bool) — if true, the virtualenv gets access to the global site-packages directory. (default `false`)
**Common to all environments:**
**Parameters**
- `nature` (str) — the nature of the command field. (default `shell`)
**`nature` values:**
- `shell`: executes the Command contents with the default shell
- `xshell`: like shell, but it performs a platform conversion first
- `python`: executes the Command contents with the Python executable
- `command` (str) — the command to execute
- `ignore-exit-code` (bool) — marks the build as a failure if any of the commands exits with a non-zero exit code. (default `false`)
**Examples:**
builders:
- shining-panda: build-environment: python python-version: System-CPython-2.7 nature: python command: setup.py build ignore-exit-code: false
builders:
- shining-panda: build-environment: custom home: /usr/local/lib/custom-python-27 nature: xshell command: | cd $HOME/build python setup.py build ignore-exit-code: true
builders:
- shining-panda: build-environment: virtualenv python-version: System-CPython-2.7 nature: shell command: python setup.py build name: virtvenv1 clear: true use-distribute: true system-site-packages: true ignore-exit-code: true
---
### `sonar()` 🔊
Invokes standalone Sonar analysis.
Requires the Jenkins Sonar Plugin <https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/jenkins-extension-sonarqube/>.
**Parameters**
- `sonar-name` (str) — name of the Sonar installation
- `sonar-scanner` (str) — name of the Sonar Scanner
- `task` (str) — task to run. (default `''`)
- `project` (str) — path to the Sonar project properties file. (default `''`)
- `properties` (str) — Sonar configuration properties. (default `''`)
- `java-opts` (str) — Java options for Sonnar Runner. (default `''`)
- `additional-arguments` (str) — additional command line arguments. (default `''`)
- `jdk` (str) — JDK to use (it inherits from the job if you omit it). (optional)
**Example:**
builders:
- sonar: sonar-name: Sonar scanner-name: scanner-3.x task: views project: sonar-project.properties properties: sonar.views.list=myview1,myview2 java-opts: -Xmx512m additional-arguments: -X
---
### `sonatype-clm()` 📋
Requires the Jenkins Sonatype CLM Plugin.
> <red>WARNING:</red> this plugin appears to be **deprecated**, bestie. There does not seem to be any place where it is actually available for download. 😭
Try the `nexus-artifact-uploader` plugin instead.
**Parameters**
- `value` (str) — select a CLM application from the list of available CLM applications, or specify a CLM Application ID. (default `list`)
- `application-name` (str) — determines the policy elements to associate with this build. (<red>required</red>)
- `username` (str) — username on the Sonatype CLM server. Leave it empty to use the username configured at the global level. (default `''`)
- `password` (str) — password on the Sonatype CLM server. Leave it empty to use the password configured at the global level. (default `''`)
- `fail-on-clm-server-failure` (bool) — controls the build outcome if there's a failure communicating with the CLM server. (default `false`)
- `stage` (str) — controls which stage the policy evaluation runs against on the CLM server. Valid stages: `build`, `stage-release`, `release`, `operate`. (default `'build'`)
- `scan-targets` (str) — pattern of files to include for scanning. (default `''`)
- `module-excludes` (str) — pattern of files to exclude. (default `''`)
- `advanced-options` (str) — options to be set on a case-by-case basis, as advised by Sonatype Support. (default `''`)
**Minimal Example:**
builders:
- sonatype-clm: application-name: jenkins-job-builder
**Full Example:**
builders:
- sonatype-clm: value: manual application-name: jenkins-job-builder fail-on-clm-server-failure: true stage: release scan-targets: '/*.jar' module-excludes: '/my-module/target/**' advanced-options: 'test' username: bar password: 06XQY39LHGACt3r3kzSULg==
---
### `ssh-builder()` 🔐
Executes a command on a remote host. Long distance relationship with your build server, iconic.
Requires the Jenkins SSH plugin <https://plugins.jenkins.io/ssh>.
**Parameters**
- `ssh-user-ip` (str) — `<user@ip>:ssh_port` of the machine defined in jenkins according to the SSH plugin instructions
- `command` (str) — the command to run on the remote server
**Example:**
builders:
- ssh-builder: ssh-user-ip: foo@bar:22 command: echo foo
---
### `system-groovy()` 🪄
Executes a system groovy script or command. Main character energy, honestly.
Requires the Jenkins Groovy Plugin <https://plugins.jenkins.io/groovy>.
**Parameters**
- `file` (str) — Groovy file to run. (Alternative: you can choose a command instead)
- `command` (str) — Groovy command to run. (Alternative: you can choose a script file instead)
- `sandbox` (bool) — executes the script inside of the groovy sandbox (>=2.0) (default `false`)
- `bindings` (str) — defines variable bindings (in the properties file format). The specified variables can be addressed from the script. (optional)
- `class-path` (list) — list of script class paths. (optional)
**Examples:**
builders:
- system-groovy: file: "test.groovy"
builders:
- system-groovy: command: "println 'Hello'" bindings: "EXAMPLE=foo-bar" class-path: "file:/home/user/example.jar" sandbox: true
---
## 🌸 `tox()` 🌸
okay so this one lets you use <pink>tox</pink> to build a multi-configuration project 💖
<purple>Requires the Jenkins ShiningPanda plugin</purple> `https://plugins.jenkins.io/shiningpanda`.
**Parameters** ✨
- **`ini`** (<italic>str</italic>) — the TOX config file path, bestie. default is `tox.ini`
- **`recreate`** (<italic>str</italic>... jk it's <italic>bool</italic>) — if it's true, you make a brand new environment every single time (default `false`)
- **`toxenv-pattern`** (<italic>str</italic>) — the pattern that builds the `TOXENV` environment variable (optional)
**Example:** 🫶
builders:
- tox: recreate: True
---
## 🔥 `trigger-builds()` 🔥
this is the one that <hotpink>triggers builds of OTHER jobs</hotpink>, like a little build matchmaker 🎀
<purple>Requires the Jenkins Parameterized Trigger Plugin</purple> `https://plugins.jenkins.io/parameterized-trigger`.
**Parameters** 💅
- **`project`** (<italic>list</italic>) — the Jenkins project to trigger
- **`predefined-parameters`** (<italic>str</italic>) — key/value pairs to be passed to the job (optional)
- **`bool-parameters`** (<italic>list</italic>) — a Bool 🦋
- **`name`** (<italic>str</italic>) — Parameter name
- **`value`** (<italic>bool</italic>) — Value to set (default `false`)
- **`property-file`** (<italic>str</italic>) — Pass properties from file to the other job (optional)
- **`property-file-fail-on-missing`** (<italic>bool</italic>) — Don't trigger if any files are missing (default `true`)
- **`current-parameters`** (<italic>bool</italic>) — Whether to include the parameters passed to the current build to the triggered job (default `false`)
- **`node-label-name`** (<italic>str</italic>) — Define a name for the NodeLabel parameter to be set. Used in conjunction with `node-label`. Requires NodeLabel Parameter Plugin (optional)
- **`node-label`** (<italic>str</italic>) — Label of the nodes where build should be triggered. Used in conjunction with `node-label-name`. Requires NodeLabel Parameter Plugin (optional)
- **`restrict-matrix-project`** (<italic>str</italic>) — Filter that restricts the subset of the combinations that the triggered job will run (optional)
- **`svn-revision`** (<italic>bool</italic>) — Whether to pass the svn revision to the triggered job (optional)
- **`git-revision`** (<italic>dict</italic>) — Passes git revision to the triggered job (optional). 💜
- **`combine-queued-commits`** (<italic>bool</italic>): Whether to combine queued git hashes or not (default `false`)
- **`block`** (<italic>bool</italic>) — whether to wait for the triggered jobs to finish or not (default `false`)
- **`block-thresholds`** (<italic>dict</italic>) — Fail builds and/or mark as failed or unstable based on thresholds. Only apply if `block` parameter is `true` (optional)
**`block-thresholds`** 👑
- **`build-step-failure-threshold`** (<italic>str</italic>) - build step failure threshold, valid values are `'never'`, `'SUCCESS'`, `'UNSTABLE'`, or `'FAILURE'`. (default `'FAILURE'`)
- **`unstable-threshold`** (<italic>str</italic>) - unstable threshold, valid values are `'never'`, `'SUCCESS'`, `'UNSTABLE'`, or `'FAILURE'`. (default `'UNSTABLE'`)
- **`failure-threshold`** (<italic>str</italic>) - overall failure threshold, valid values are `'never'`, `'SUCCESS'`, `'UNSTABLE'`, or `'FAILURE'`. (default `'FAILURE'`)
- **`same-node`** (<italic>bool</italic>) — Use the same node for the triggered builds that was used for this build (optional)
- **`parameter-factories`** (<italic>list</italic>) — list of parameter factories 🌈
**Factory** 🧚
- **`factory`** (<italic>str</italic>) `filebuild` -- For every property file, invoke one build
- **`file-pattern`** (<italic>str</italic>) -- File wildcard pattern
- **`no-files-found-action`** (<italic>str</italic>) -- Action to perform when no files found. Valid values `'FAIL'`, `'SKIP'`, or `'NOPARMS'`. (default `'SKIP'`)
**Factory** 🧚
- **`factory`** (<italic>str</italic>) `binaryfile` -- For every matching file, invoke one build
- **`file-pattern`** (<italic>str</italic>) -- Artifact ID of the artifact
- **`no-files-found-action`** (<italic>str</italic>) -- Action to perform when no files found. Valid values `'FAIL'`, `'SKIP'`, or `'NOPARMS'`. (default `'SKIP'`)
**Factory** 🧚
- **`factory`** (<italic>str</italic>) `counterbuild` -- Invoke i=0...N builds
- **`from`** (<italic>int</italic>) -- Artifact ID of the artifact
- **`to`** (<italic>int</italic>) -- Version of the artifact
- **`step`** (<italic>int</italic>) -- Classifier of the artifact
- **`parameters`** (<italic>str</italic>) -- `KEY=value` pairs, one per line (default `''`)
- **`validation-fail`** (<italic>str</italic>) -- Action to perform when stepping validation fails. Valid values `'FAIL'`, `'SKIP'`, or `'NOPARMS'`. (default `'FAIL'`)
**Factory** 🧚
- **`factory`** (<italic>str</italic>) `allnodesforlabel` -- Trigger a build on all nodes having specific label. Requires NodeLabel Parameter Plugin (optional)
- **`name`** (<italic>str</italic>) -- Name of the parameter to set (optional)
- **`node-label`** (<italic>str</italic>) -- Label of the nodes where build should be triggered
- **`ignore-offline-nodes`** (<italic>bool</italic>) -- Don't trigger build on offline nodes (default `true`)
**Factory** 🧚
- **`factory`** (<italic>str</italic>) `allonlinenodes` -- Trigger a build on every online node. Requires NodeLabel Parameter Plugin (optional)
### ✨ Examples ✨
**Basic usage with yaml list of projects.** 🎀
builders:
- trigger-builds:
- project:
- "foo"
- "bar"
- "baz" current-parameters: true
- project:
**Basic usage with passing svn revision through.** 💖
builders:
- trigger-builds:
- project: "build_started" predefined-parameters: FOO="bar" current-parameters: true svn-revision: true block: true
**Basic usage with passing git revision through.** 🦋
builders:
- trigger-builds:
- project: "build_started" predefined-parameters: FOO="bar" current-parameters: true node-label-name: NODE node-label: testnodes git-revision: true block: true
**Example with all supported parameter factories.** ⭐
builders:
- trigger-builds:
- project: "build_started" predefined-parameters: FOO="bar" current-parameters: true svn-revision: true parameter-factories:
- factory: filebuild file-pattern: propfile*.txt
- factory: binaryfile parameter-name: filename file-pattern: otherpropfile*.txt
- factory: counterbuild from: 0 to: 5 step: 1
- factory: allnodesforlabel name: parametername node-label: labelname ignore-offline-nodes: false
- factory: allonlinenodes block: true
- project: "build_started" predefined-parameters: FOO="bar" current-parameters: true svn-revision: true parameter-factories:
---
## 💜 `trigger-remote()` 💜
this one triggers a build of a job on a <hotpink>remote Jenkins instance</hotpink>. long distance relationship vibes fr fr 😭
<purple>Requires the Jenkins Parameterized Remote Trigger Plugin</purple> `https://plugins.jenkins.io/Parameterized-Remote-Trigger`
> okay bestie listen up, this is important 👑 Please note that this plugin requires system configuration on the Jenkins Master that is unavailable from individual job views; specifically, one must add remote jenkins servers whose `'Display Name'` field are what make up valid fields on the `remote-jenkins-name` attribute below.
**Parameters** 🌸
- **`remote-jenkins-name`** (<italic>str</italic>) — the remote Jenkins server (**required**)
- **`job`** (<italic>str</italic>) — the Jenkins project to trigger on the remote Jenkins server (**required**)
- **`should-not-fail-build`** (<italic>bool</italic>) — if true, remote job failure will not lead current job to fail (default `false`)
- **`prevent-remote-build-queue`** (<italic>bool</italic>) — if true, wait to trigger remote builds until no other builds (default `false`)
- **`block`** (<italic>bool</italic>) — whether to wait for the trigger jobs to finish or not (default `true`)
- **`poll-interval`** (<italic>str</italic>) — polling interval in seconds for checking statues of triggered remote job, only necessary if current job is configured to block (default `10`)
- **`connection-retry-limit`** (<italic>str</italic>) — number of connection attempts to remote Jenkins server before giving up. (default `5`)
- **`enhanced-logging`** (<italic>bool</italic>) — if this option is enabled, the console output of the remote job is also logged. (default `false`)
- **`predefined-parameters`** (<italic>str</italic>) — predefined parameters to send to the remote job when triggering it (optional)
- **`property-file`** (<italic>str</italic>) — file in workspace of current job containing additional parameters to be set on remote job (optional)
**Example:** 🫶
builders:
- trigger-remote: remote-jenkins-name: "http://example.jenkinsmaster.lan" token: "BLAH" job: "build-things" should-fail-build: True prevent-remote-build-queue: True poll-interval: 5 connection-retry-limit: 5 block: true enhanced-logging: True property-file: '.props' predefined-parameters: | FOO="bar" herp="derp"
---
## 🍓 `xcode()` 🍓
This step allows you to execute an <pink>xcode</pink> build step. ✨
> Requires the Jenkins Xcode Plugin <https://plugins.jenkins.io/xcode-plugin>.
## Parameters 🍎
- **`developer-profile`** (*str*) — the jenkins credential id for a ios developer profile. (optional)
- **`clean-build`** (*bool*) — if true will delete the build directories before invoking the build. (default false)
- **`clean-test-reports`** (*bool*) — UNKNOWN. (default false) <purple>bestie they literally wrote UNKNOWN in the manpage and honestly? relatable, we don't know either 💀</purple>
- **`archive`** (*bool*) — if true will generate an xcarchive of the specified scheme. A workspace and scheme are are also needed for archives. (default false)
- **`configuration`** (*str*) — This is the name of the configuration as defined in the Xcode project. (default `'Release'`)
- **`configuration-directory`** (*str*) — The value to use for `CONFIGURATION_BUILD_DIR` setting. (default `''`)
- **`target`** (*str*) — Leave empty for all targets. (default `''`)
- **`sdk`** (*str*) — Leave empty for default SDK. (default `''`)
- **`symroot`** (*str*) — Leave empty for default `SYMROOT`. (default `''`)
- **`project-path`** (*str*) — Relative path within the workspace that contains the xcode project file(s). (default `''`)
- **`project-file`** (*str*) — Only needed if there is more than one project file in the Xcode Project Directory. (default `''`)
- **`build-arguments`** (*str*) — Extra commandline arguments provided to the xcode builder. (default `''`)
- **`schema`** (*str*) — Only needed if you want to compile for a specific schema instead of a target. (default `''`)
- **`workspace`** (*str*) — Only needed if you want to compile a workspace instead of a project. (default `''`)
- **`profile`** (*str*) — The relative path to the mobileprovision to embed, leave blank for no embedded profile. (default `''`)
- **`codesign-id`** (*str*) — Override the code signing identity specified in the project. (default `''`)
- **`allow-failing`** (*bool*) — if true will prevent this build step from failing if xcodebuild exits with a non-zero return code. (default false)
- **`version-technical`** (*str*) — The value to use for `CFBundleVersion`. Leave blank to use project's technical number. (default `''`)
- **`version-marketing`** (*str*) — The value to use for `CFBundleShortVersionString`. Leave blank to use project's marketing number. (default `''`)
- **`ipa-export-method`** (*str*) — The export method of the `.app` to generate the `.ipa` file. Should be one in `'development'`, `'ad-hoc'`, `'enterprise'`, or `'app-store'`. (default `''`)
- **`ipa-version`** (*str*) — A pattern for the ipa file name. You may use `${VERSION}` and `${BUILD_DATE}` (yyyy.MM.dd) in this string. (default `''`)
- **`ipa-output`** (*str*) — The output directory for the `.ipa` file, relative to the build directory. (default `''`)
- **`compile-bitcode`** (*bool*) — recompile from Bitcode when exporting the application to IPA. (default true)
- **`upload-bitcode`** (*bool*) — include Bitcode when exporting applications to IPA. (default true)
- **`upload-symbols`** (*bool*) — include symbols when exporting applications to IPA. (default true)
- **`development-team-id`** — The ID of the Apple development team to use to sign the IPA (default `''`)
- **`keychain-name`** (*str*) — The globally configured keychain to unlock for this build. (default `''`)
- **`keychain-path`** (*str*) — The path of the keychain to use to sign the IPA. (default `''`)
- **`keychain-password`** (*str*) — The password to use to unlock the keychain. (default `''`)
- **`keychain-unlock`** (*str*) — Unlocks the keychain during use. (default false)
- **`bundle-id`** (*str*) — The bundle identifier (App ID) for this provisioning profile (default `''`)
- **`provisioning-profile-uuid`** (*str*) — The UUID of the provisioning profile associated to this bundle identifier. (default `''`)
### Example ✨
<pink>okay this one's a whole mood, look how much stuff you can stack:</pink>
builders:
- xcode
- xcode: developer-profile: "849b07cd-ac61-4588-89c8-b6606ee84946" clean-build: true clean-test-reports: true configuration: Distribution target: TARGET sdk: iphonesimulator build-arguments: "test ONLY_ACTIVE_ARCH=NO -destination 'platform=iOS Simulator,name=iPhone 6' -derivedDataPath ." schema: "UASDKInternal" workspace: "UA" profile: "PROFILE" codesign-id: "iPhone Distribution: MapMyFitness Inc." allow-failing: true version-technical: "TECHNICAL" version-marketing: "MARKETING" ipa-export-method: ad-hoc ipa-version: "${VERSION}" ipa-output: "/output" compile-bitcode: false upload-bitcode: false upload-symbols: false development-team-id: foo keychain-path: "/Users/jenkins/Library/Keychains/jenkins-uasdk-ios-pre_review" keychain-password: "testpass" keychain-unlock: true provisioning-profiles:
- bundle-id: foo provisioning-profile-uuid: bar
- bundle-id: foo2 provisioning-profile-uuid: bar2
---
## `xunit()` 🧪
Process tests results.
> Requires the Jenkins xUnit Plugin <https://plugins.jenkins.io/xunit>.
### Parameters
- **`thresholdmode`** (*str*) — Whether thresholds represents an absolute number of tests or a percentage. Either `'number'` or `'percent'`. (default `'number'`)
- **`thresholds`** (*list*) —
Thresholds for both `'failed'` and `'skipped'` tests.
**`threshold`** (*dict*)
Threshold values to set, where missing, xUnit should default to an internal value of 0. Each test threshold should contain the following:
- `unstable` (*int*)
- `unstablenew` (*int*)
- `failure` (*int*)
- `failurenew` (*int*)
- **`test-time-margin`** (*int*) — Give the report time margin value in ms, before to fail if not new unless the option `requireupdate` is set for the configured framework. (default 3000)
- **`types`** (*list*) —
Frameworks to configure, and options. Supports the following: `aunit`, `boosttest`, `checktype`, `cpptest`, `cppunit`, `ctest`, `dotnettest`, `embunit`, `fpcunit`, `gtest`, `junit`, `mstest`, `nunit`, `phpunit`, `tusar`, `unittest`, and `valgrind`.
<red>Heads up bestie: the `'custom'` type is NOT supported. 🙅♀️</red>
**`type`** (*dict*)
each type can be configured using the following:
- `pattern` (*str*): An Ant pattern to look for Junit result files, relative to the workspace root (default `''`)
- `requireupdate` (*bool*): fail the build whenever fresh tests results have not been found (default true).
- `deleteoutput` (*bool*): delete temporary JUnit files (default true).
- `skip-if-no-test-files` (*bool*): Skip parsing this xUnit type report if there are no test reports files (default false).
- `stoponerror` (*bool*): Fail the build whenever an error occur during a result file processing (default true).
### Minimal Example 🌸
<pink>the bare minimum, the "just make it work" era:</pink>
builders:
- xunit: types:
- junit: pattern: "junit.xml"
### Full Example 👑
<pink>and here's the full serve, everything turned up:</pink>
builders:
- xunit: thresholdmode: 'percent' thresholds:
- failed: unstable: 0 unstablenew: 0 failure: 0 failurenew: 0
- skipped: unstable: 0 unstablenew: 0 failure: 0 failurenew: 0 test-time-margin: 5000 types:
- phpunit: pattern: "phpunit.log" requireupdate: true deleteoutput: true skip-if-no-test-files: false stoponerror: true
- cppunit: pattern: "cppunit.log" requireupdate: false deleteoutput: false skip-if-no-test-files: true stoponerror: false
- gtest: pattern: "gtest.log"
---
## Hipchat 💬
Enable HipChat notifications of build execution.
<purple>Okay so this is the old-head module — it Supports hipchat plugin versions < 1.9. Will automatically redirect to the publishers module for newer versions, but still recommended that you convert to the newer module. So like, it still works, but it's giving deprecated-adjacent energy. Convert when you can, bestie. 🫶</purple>
### Parameters
- **`enabled`** (*bool*): general cut off switch. If not explicitly set to true, no hipchat parameters are written to XML. For Jenkins HipChat plugin of version prior to 0.1.5, also enables all build results to be reported in HipChat room. For later plugin versions, explicit `notify-*` setting is required (see below).
- **`room`** (*str*) — name of HipChat room to post messages to (default `''`)
> Deprecated since version `1.2.0`: Please use `'rooms'`.
- **`rooms`** (*list*) — list of HipChat rooms to post messages to (default empty)
- **`start-notify`** (*bool*) — post messages about build start event
> Deprecated since version `1.2.0`: use `notify-start` parameter instead
- **`notify-start`** (*bool*) — post messages about build start event (default `false`)
- **`notify-success`** (*bool*) — post messages about successful build event (Jenkins HipChat plugin >= `0.1.5`) (default `false`)
- **`notify-aborted`** (*bool*) — post messages about aborted build event (Jenkins HipChat plugin >= `0.1.5`) (default `false`)
- **`notify-not-built`** (*bool*) — post messages about build set to `NOT_BUILT` status (Jenkins HipChat plugin >= `0.1.5`). This status code is used in a multi-stage build (like `maven2`) where a problem in earlier stage prevented later stages from building. (default `false`)
- **`notify-unstable`** (*bool*) — post messages about unstable build event (Jenkins HipChat plugin >= `0.1.5`) (default `false`)
- **`notify-failure`** (*bool*) — post messages about build failure event (Jenkins HipChat plugin >= `0.1.5`) (default `false`)
- **`notify-back-to-normal`** (*bool*) — post messages about build being back to normal after being unstable or failed (Jenkins HipChat plugin >= `0.1.5`) (default `false`)
Example:
hipchat: enabled: true rooms:
- My Room
- Your Room notify-start: true notify-success: true notify-aborted: true notify-not-built: true notify-unstable: true notify-failure: true notify-back-to-normal: true
`class hipchat_notif.HipChat(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.
:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure
- **`sequence = 80`** — The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
---
## ✨ Metadata ✨
The <pink>Metadata</pink> plugin module enables the ability to add metadata to the projects that can be exposed to job environment. It's giving data-with-a-purpose, bestie.
Requires the Jenkins Metadata Plugin `<https://plugins.jenkins.io/metadata>`.
Component: `metadata`
**Macro** `metadata`
**Entry Point** `jenkins_jobs.metadata`
Example:
metadata:
- string: name: FOO value: bar expose-to-env: true
`class metadata.Metadata(registry)`
- **`component_list_type = 'metadata'`** — 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 = 'metadata'`** — 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.
:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure
- **`sequence = 21`** — The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
### `date()` — A date metadata
Parameters:
- `name` (*str*) — the name of the metadata
- `time` (*str*) — time value in millisec since `1970-01-01 00:00:00 UTC`
- `timezone` (*str*) — time zone of the metadata
- `expose-to-env` (*bool*) — expose to environment (optional)
Example:
metadata:
- date: name: FOO value: 1371708900268 timezone: Australia/Melbourne expose-to-env: true
### `number()` — A number metadata.
Parameters:
- `name` (*str*) — the name of the metadata
- `value` (*str*) — the value of the metadata
- `expose-to-env` (*bool*) — expose to environment (optional)
Example:
metadata:
- number: name: FOO value: 1 expose-to-env: true
### `string()` — A string metadata.
Parameters:
- `name` (*str*) — the name of the metadata
- `value` (*str*) — the value of the metadata
- `expose-to-env` (*bool*) — expose to environment (optional)
Example:
metadata:
- string: name: FOO value: bar expose-to-env: true
---
## 🌈 Notifications 🌈
The <purple>Notifications</purple> module allows you to configure Jenkins to notify other applications about various build phases. It requires the Jenkins notification plugin. So your builds can text their friends, basically.
Component: `notifications`
**Macro** `notification`
**Entry Point** `jenkins_jobs.notifications`
`class notifications.Notifications(registry)`
- **`component_list_type = 'notifications'`** — 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 = 'notification'`** — 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.
:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure
- **`sequence = 22`** — The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
### `http()` — Defines an HTTP notification endpoint.
Requires the Jenkins Notification Plugin `<https://plugins.jenkins.io/notification>`.
Parameters:
- `format` (*str*) — notification payload format, `JSON` (default) or `XML`
- `event` (*str*) — job events that trigger notifications: `started`, `completed`, `finalized` or `all` (default)
- `url` (*str*) — URL of the endpoint
- `timeout` (*int*) — Timeout in milliseconds for sending notification request (30 seconds by default)
- `retries` (*int*) — Nr of times to retry sending notification in case sending notification fails. (0 by default)
- `log` (*int*) — Number lines of log messages to send (0 by default). Use `-1` for all (use with caution).
Example:
notifications:
- http: url: http://example.com/jenkins_endpoint format: xml event: completed timeout: 40000 log: -1 retries: 5
---
## 💅 Parameters 💅
The <hotpink>Parameters</hotpink> module allows you to specify build parameters for a job. Because sometimes your build needs to know things, and that's valid.
Component: `parameters`
**Macro** `parameter`
**Entry Point** `jenkins_jobs.parameters`
Example:
job: name: test_job
parameters:
- string: name: FOO default: bar description: "A parameter named FOO, defaults to 'bar'."
`class parameters.Parameters(registry)`
- **`component_list_type = 'parameters'`** — 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 = 'parameter'`** — 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.
:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure
- **`sequence = 21`** — The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
## 🎀 `active-choices()` — the Active Choices Parameter
Okay bestie, this one **requires** the Jenkins Active Choices Plug-in <https://plugins.jenkins.io/uno-choice> — no plug-in, no vibe. 💅
**Parameters:**
- **`name`** (*str*) — name of the parameter (required, like, you can't skip it).
- **`description`** (*str*) — a lil description of the parameter.
- **`script`** (*list*) — use a Groovy script to define the parameter. Yes we're scripting, periodt.
**Parameter:**
- **`groovy`** (*str*) — Groovy DSL Script
- **`use-groovy-sandbox`** (*bool*) — run this Groovy script in a sandbox with limited abilities (default `True`)
- **`script-additional-classpath`** (*list*) — extra classpath entries the script can reach.
- **`fallback-script`** (*list*) — a Fallback script. If the script up there fails, this fallback gets used instead, like a backup bestie. 🫶
**Parameter:**
- **`groovy`** (*str*) — Groovy DSL Script
- **`use-groovy-sandbox`** (*bool*) — run this Groovy script in a sandbox with limited abilities. (default `True`)
- **`script-additional-classpath`** (*list*) — extra classpath entries the script can reach.
- **`enable-filters`** (*bool*) — if enabled, a text box pops up next to this element and lets the user filter its entries. The list values never get re-evaluated (default `False`).
- **`filter-starts-at`** (*int*) — how many characters someone must type before the filter kicks in (default `1`).
- **`choice-type`** (*str*) — the type of the choices (default `'single-select'`).
**Allowed Values:**
- `single-select`
- `multi-select`
- `radio-buttons`
- `checkboxes`
**Minimal Example:**
- job: name: active-choices-job parameters:
- active-choices: name: lorem
**Full Example:**
- job: name: active-choices-job parameters:
- active-choices: name: lorem description: ipsum script: groovy: |- return [ 'param1', 'param2' ] use-groovy-sandbox: false script-additional-classpath:
- file:/jar-file-path
- file:/jar-file-path2 fallback-script: groovy: |- return [ 'param3', 'param4' ] use-groovy-sandbox: false script-additional-classpath:
- file:/jar-file-path
- file:/jar-file-path2 choice-type: multi-select enable-filters: true filter-starts-at: 1
- active-choices: name: lorem description: ipsum script: groovy: |- return [ 'param1', 'param2' ] use-groovy-sandbox: false script-additional-classpath:
---
## 🌈 `active-choices-reactive()` — the Active Choices Reactive Parameter
Same energy, but *reactive*. ✨ Also **requires** the Jenkins Active Choices Plug-in <https://plugins.jenkins.io/uno-choice>.
**Parameters:**
- **`name`** (*str*) — name of the parameter (required).
- **`description`** (*str*) — a description of the parameter.
- **`script`** (*list*) — use a Groovy script to define the parameter.
**Parameter:**
- **`groovy`** (*str*) — Groovy DSL Script
- **`use-groovy-sandbox`** (*bool*) — run this Groovy script in a sandbox with limited abilities (default `True`)
- **`script-additional-classpath`** (*list*) — extra classpath entries the script can reach.
- **`fallback-script`** (*list*) — a Fallback script. If the script above fails, this one swoops in as the fallback. 🦋
**Parameter:**
- **`groovy`** (*str*) — Groovy DSL Script
- **`use-groovy-sandbox`** (*bool*) — run this Groovy script in a sandbox with limited abilities. (default `True`)
- **`script-additional-classpath`** (*list*) — extra classpath entries the script can reach.
- **`enable-filters`** (*bool*) — if enabled, a text box appears next to this element so the user can filter its entries. The list values never get re-evaluated (default `False`).
- **`filter-starts-at`** (*int*) — how many characters a user must enter before the filter is applied (default `1`).
- **`choice-type`** (*str*) — type of the choices (default `'single-select'`).
**Allowed Values:**
- `single-select`
- `multi-select`
- `radio-buttons`
- `checkboxes`
- **`referenced-parameters`** (*str*) — comma separated list of other job parameters referenced in the uno-choice script.
**Minimal Example:**
- job: name: active-choices-job parameters:
- active-choices-reactive: name: foo
**Full Example:**
- job: name: active-choices-job parameters:
- active-choices-reactive: name: lorem description: ipsum script: groovy: |- return [ 'param1', 'param2' ] use-groovy-sandbox: false script-additional-classpath:
- file:/jar-file-path
- file:/jar-file-path2 fallback-script: groovy: |- return [ 'param3', 'param4' ] use-groovy-sandbox: false script-additional-classpath:
- file:/jar-file-path
- file:/jar-file-path2 choice-type: multi-select enable-filters: true filter-starts-at: 1 referenced-parameters: foo,bar
- active-choices-reactive: name: lorem description: ipsum script: groovy: |- return [ 'param1', 'param2' ] use-groovy-sandbox: false script-additional-classpath:
---
## 💖 `bool()` — a boolean parameter
Just a yes/no moment, bestie. True or false, no in-between. 🙈
**Parameters:**
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter (optional)
- **`description`** (*str*) — a description of the parameter (optional)
**Example:**
parameters:
- bool: name: FOO default: false description: "A parameter named FOO, defaults to 'false'."
---
## 🎀 `choice()` — a single selection parameter
Pick ONE, babes. Only one. 🙅♀️
**Parameters:**
- **`name`** (*str*) — the name of the parameter
- **`choices`** (*list*) — the available choices, first one is the default one.
- **`description`** (*str*) — a description of the parameter (optional)
**Example:**
parameters:
- choice: name: project choices:
- nova
- glance description: "On which project to run?"
---
## 👑 `copyartifact-build-selector()`
This one lets you control, via a build parameter, which build the copyartifact plugin should copy when it's configured to use `'build-param'`. Very niche, very iconic. 💅
**Requires** the Jenkins Copy Artifact plugin <https://plugins.jenkins.io/copyartifact>.
**Parameters:**
- **`name`** (*str*) — name of the build parameter to store the selection in
- **`description`** (*str*) — a description of the parameter (optional)
- **`which-build`** (*str*) — which to provide as the default value in the UI. Peep the `which-build` param of copyartifact <#builders.copyartifact> from the builders module for the available values, plus options that control additional behaviour for the selected value.
**Example:**
parameters:
- copyartifact-build-selector: name: BUILD_SELECTOR which-build: workspace-latest description: 'Which build from upstream to copy artifacts from'
---
## 🦋 `credentials()` — a credentials selection parameter
Locked-in secret vibes only. 🔐 **Requires** the Jenkins Credentials Plugin <https://plugins.jenkins.io/credentials>.
**Parameters:**
- **`name`** (*str*) — the name of the parameter
- **`type`** (*str*) — credential type (optional, default `'any'`)
**Allowed Values:**
- `any` — Any credential type (default)
- `usernamepassword` — Username with password
- `sshkey` — SSH Username with private key
- `secretfile` — Secret file
- `secrettext` — Secret text
- **`certificate`** — Certificate 🔐
- **`required`** (*bool*) — is this parameter a need or a want? (optional, default `false`)
- **`default`** (*str*) — the default credentials ID (optional)
- **`description`** (*str*) — a lil description of the parameter (optional)
Example:
parameters:
- credentials: name: OS_CREDENTIALS type: usernamepassword default: "default-credentials-id" description: "Test credentials"
---
### dynamic-choice()
Dynamic Choice Parameter 🌈
Requires the Jenkins Jenkins Dynamic Parameter Plug-in — `https://plugins.jenkins.io/dynamicparameter`. <pink>bestie you literally need this plugin, no cap.</pink>
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`description`** (*str*) — a description of the parameter (optional)
- **`script`** (*str*) — Groovy expression which generates the potential choices.
- **`remote`** (*bool*) — the script will be executed on the slave where the build is started (default `false`)
- **`classpath`** (*str*) — class path for script (optional)
- **`read-only`** (*bool*) — user can't modify parameter once populated (default `false`)
Example:
parameters:
- dynamic-choice: name: OPTIONS description: "Available options" script: "['optionA', 'optionB']" remote: false read-only: false
---
### dynamic-choice-scriptler()
Dynamic Choice Parameter (Scriptler) 🎀
Requires the Jenkins Jenkins Dynamic Parameter Plug-in — `https://plugins.jenkins.io/dynamicparameter`. <lavender>it's giving scripted energy, periodt.</lavender>
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`description`** (*str*) — a description of the parameter (optional)
- **`script-id`** (*str*) — Groovy script which generates the default value
- **`parameters`** (*list*) —
parameters to corresponding script
**Parameter**
- **`name`** (*str*) Parameter name
- **`value`** (*str*) Parameter value
- **`remote`** (*bool*) — the script will be executed on the slave where the build is started (default `false`)
- **`read-only`** (*bool*) — user can't modify parameter once populated (default `false`)
Example:
parameters:
- dynamic-choice-scriptler: name: OPTIONS description: "Available options" script-id: "scriptid.groovy" parameters:
- name: param1 value: value1
- name: param2 value: value2 remote: false read-only: false
---
### dynamic-reference()
Active Choices Reactive Reference Parameter 💖
Requires the Jenkins Active Choices Plug-in — `https://plugins.jenkins.io/uno-choice`. <hotpink>this one is lowkey iconic, fr fr.</hotpink>
**Parameters**
- **`name`** (*str*) — Name of the parameter (required).
- **`description`** (*str*) — Description of the parameter.
- **`script`** (*list*) —
Use a Groovy script to define the parameter.
**Parameter**
- **`groovy`** (*str*) Groovy DSL Script
- **`use-groovy-sandbox`** (*bool*) To run this Groovy script in a sandbox with limited abilities (default `True`)
- **`script-additional-classpath`** (*list*) Additional classpath entries accessible from the script.
- **`fallback-script`** (*list*) —
Use a Fallback script. If the script (specified above) fails, the fallback script will be used as a fallback.
**Parameter**
- **`groovy`** (*str*) Groovy DSL Script
- **`use-groovy-sandbox`** (*bool*) To run this Groovy script in a sandbox with limited abilities. (default `True`)
- **`script-additional-classpath`** (*list*) Additional classpath entries accessible from the script.
- **`omit-value-field`** (*bool*) — By default Dynamic Reference Parameters always include a hidden input for the value. If your script creates an input HTML element, you can check this option and the value input field will be omitted (default `False`).
- **`referenced-parameters`** (*str*) — Comma separated list of other job parameters referenced in the uno-choice script. When any of the referenced parameters are updated, the Groovy script will re-evaluate the choice list using the updated values of referenced parameters.
- **`choice-type`** (*str*) —
type of the choices. (default `'input-text-box'`)
**Allowed Values**
- `input-text-box`
- `numbered-list`
- `bullet-items-list`
- `formatted-html`
- `formatted-hidden-html`
Minimal Example:
- job: name: dynamic-reference-job parameters:
- dynamic-reference: name: lorem
Full Example:
- job: name: dynamic-reference-job folder: unochoice parameters:
- dynamic-reference: name: lorem description: ipsum script: groovy: |- return [ 'param1', 'param2' ] use-groovy-sandbox: false script-additional-classpath:
- file:/path
- file:/path2 fallback-script: groovy: |- return [ 'param3', 'param4' ] use-groovy-sandbox: false script-additional-classpath:
- file:/path
- file:/path2 choice-type: numbered-list omit-value-field: True referenced-parameters: dolor
- dynamic-reference: name: lorem description: ipsum script: groovy: |- return [ 'param1', 'param2' ] use-groovy-sandbox: false script-additional-classpath:
---
### dynamic-string()
Dynamic Parameter 🧵
Requires the Jenkins Jenkins Dynamic Parameter Plug-in — `https://plugins.jenkins.io/dynamicparameter`. <mint>string theory but make it Jenkins, iykyk.</mint>
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`description`** (*str*) — a description of the parameter (optional)
- **`script`** (*str*) — Groovy expression which generates the potential choices
- **`remote`** (*bool*) — the script will be executed on the slave where the build is started (default `false`)
- **`classpath`** (*str*) — class path for script (optional)
- **`read-only`** (*bool*) — user can't modify parameter once populated (default `false`)
Example:
parameters:
- dynamic-string: name: FOO description: "A parameter named FOO, defaults to 'bar'." script: "bar" remote: false read-only: false
---
### dynamic-string-scriptler()
Dynamic Parameter (Scriptler) 🌟
Requires the Jenkins Jenkins Dynamic Parameter Plug-in — `https://plugins.jenkins.io/dynamicparameter`. <cyan>scriptler? more like slay-er, am I right?</cyan>
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`description`** (*str*) — a description of the parameter (optional)
- **`script-id`** (*str*) — Groovy script which generates the default value
- **`parameters`** (*list*) —
parameters to corresponding script
**Parameter**
- **`name`** (*str*) Parameter name
- **`value`** (*str*) Parameter value
- **`remote`** (*bool*) — the script will be executed on the slave where the build is started (default `false`)
- **`read-only`** (*bool*) — user can't modify parameter once populated (default `false`)
Example:
parameters:
- dynamic-string-scriptler: name: FOO description: "A parameter named FOO, defaults to 'bar'." script-id: "scriptid.groovy" parameters:
- name: param1 value: value1
- name: param2 value: value2 remote: false read-only: false
---
### extended-choice()
Creates an extended choice parameter where values can be read from a file 📂
Requires the Jenkins Extended Choice Parameter Plugin — `https://plugins.jenkins.io/extended-choice-parameter`. <yellow>extended? like my patience for boring parameters? not today, bestie.</yellow>
**Parameters**
- **`name`** (*str*) — name of the parameter
- **`description`** (*str*) — description of the parameter (optional, default `''`)
- **`property-file`** (*str*) — location of property file to read from (optional, default `''`)
- **`property-key`** (*str*) — key for the property-file (optional, default `''`)
- **`quote-value`** (*bool*) — whether to put quotes around the property when passing to Jenkins (optional, default `false`)
- **`visible-items`** (*str*) — number of items to show in the list (optional, default `5`)
- **`type`** (*str*) — what kind of select are we doing?? options are `single-select`, `multi-select`, `multi-level-single-select`, `multi-level-multi-select`, `radio`, `checkbox`, `textbox`, `json` (optional, default `single-select`)
- **`value`** (*str*) — comma separated list of values for the single select or multi-select box (optional, default `''`)
- **`default-value`** (*str*) — sets the initial selection of the single-select or multi-select box bestie, this is the pre-picked one (optional, default `''`)
- **`value-description`** (*str*) — comma separated list of value descriptions for the single select or multi-select box (optional, default `''`)
- **`default-property-file`** (*str*) — location of property file when default value needs to come from a property file (optional, default `''`)
- **`default-property-key`** (*str*) — key for the default property file (optional, default `''`)
- **`description-property-file`** (*str*) — location of property file when value description needs to come from a property file (optional, default `''`)
- **`description-property-key`** (*str*) — key for the value description property file (optional, default `''`)
- **`multi-select-delimiter`** (*str*) — value between selections when the parameter is a multi-select (optional, default `','`)
- **`groovy-script`** (*str*) — the groovy script contents (optional, default `','`)
- **`groovy-script-file`** (*str*) — location of groovy script file to generate parameters (optional, default `''`)
- **`bindings`** (*str*) — variable bindings for the groovy script (optional, default `''`)
- **`classpath`** (*str*) — the classpath for the groovy script (optional, default `','`)
- **`default-groovy-script`** (*str*) — the default groovy script contents (optional, default `''`)
- **`default-groovy-classpath`** (*str*) — the default classpath for the groovy script (optional, default `''`)
- **`description-groovy-script`** (*str*) — location of groovy script when value description needs to come from a groovy script (optional, default `''`)
- **`description-groovy-script-file`** (*str*) — location of groovy script file when value description needs to come from a groovy script (optional, default `''`)
- **`description-groovy-classpath`** (*str*) — classpath for the value description groovy script (optional, default `''`)
- **`javascript`** (*str*) — the javascript script contents (optional, default `''`)
- **`javascript-file`** (*str*) — location of javasript script file to generate parameters (optional, default `''`)
- **`save-json-parameter-to-file`** (*bool*) — if json parameter should be saved to file (optional, default `False`)
### 🌸 Minimal Example:
parameters:
- extended-choice: name: OPTIONS description: "Available options" type: 'PT_CHECKBOX' value: OptionA,OptionB,OptionC
### 👑 Full 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
---
## 🍓 `file()`
A file parameter. yeah it just lets you upload a file, slay.
### Parameters
- **`name`** (*str*) — the target location for the file upload
- **`description`** (*str*) — a description of the parameter (optional)
### Example:
parameters:
- file: name: test.txt description: "Upload test.txt."
---
## 🦋 `git-parameter()`
This parameter lets you pick a git tag, branch or revision number as a parameter in Parametrized builds. iconic behavior tbh.
Requires the Jenkins Git Parameter Plugin <https://plugins.jenkins.io/git-parameter>.
### Parameters
- **`name`** (*str*) — Name of the parameter
- **`description`** (*str*) — Description of the parameter (default `''`)
- **`type`** (*str*) — the type of the list of parameters (default `'PT_TAG'`)
<pink>Allowed Values</pink>
- `PT_TAG` — list of all commit tags in repository — returns Tag Name
- `PT_BRANCH` — list of all branches in repository — returns Branch Name
- `PT_BRANCH_TAG` — list of all commit tags and all branches in repository — returns Tag Name or Branch Name
- `PT_REVISION` — list of all revision sha1 in repository followed by its author and date — returns Tag SHA1
- `PT_PULL_REQUEST`
- **`branch`** (*str*) — Name of branch to look in. Used only if listing revisions. (default `''`)
- **`branchFilter`** (*str*) — Regex used to filter displayed branches. If blank, the filter will default to `.*`. Remote branches will be listed with the remote name first. E.g., `origin/master` (default `'.*'`)
- **`tagFilter`** (*str*) — Regex used to filter displayed branches. If blank, the filter will default to `.*`. Remote branches will be listed with the remote name first. E.g., `origin/master` (default `'*'`)
- **`sortMode`** (*str*) — Mode of sorting. (default `'NONE'`)
<pink>Allowed Values</pink>
- `NONE`
- `DESCENDING`
- `ASCENDING`
- `ASCENDING_SMART`
- `DESCENDING_SMART`
- **`defaultValue`** (*str*) — This value is returned when list is empty. (default `''`)
- **`selectedValue`** (*str*) — Which value is selected, after loaded parameters. If you choose `'default'`, but default value is not present on the list, nothing is selected. (default `'NONE'`)
<pink>Allowed Values</pink>
- `NONE`
- `TOP`
- `DEFAULT`
- **`useRepository`** (*str*) — If in the task is defined multiple repositories parameter specifies which the repository is taken into account. If the parameter is not defined, is taken first defined repository. The parameter is a regular expression which is compared with a URL repository. (default `''`)
- **`quickFilterEnabled`** (*bool*) — When this option is enabled will show a text field. Parameter is filtered on the fly. (default `false`)
### 🌈 Minimal Example:
parameters:
- git-parameter: name: Foo
### 💜 Full Example:
...and here's the rest of that `git-parameter` example, exactly as it lives in your config, no edits, bestie 💖
parameters:
- git-parameter: name: Foo description: Lorem ipsum dolor sit amet. type: PT_BRANCH_TAG branch: baz tagFilter: bam branchFilter: boo sortMode: ASCENDING defaultValue: bor selectedValue: TOP useRepository: buh quickFilterEnabled: true
---
## 🫥 <purple>hidden()</purple>
Okay so this one is <hotpink>lowkey sneaky</hotpink> in the best way — it lets you use parameters that are **hidden from the build-with-parameters page** 🙈. The build can still see them, you just can't see them when you're clicking "Build with Parameters". Secret menu energy fr fr.
> Requires the <blue>Jenkins Hidden Parameter Plugin</blue> — `https://plugins.jenkins.io/hidden-parameter`
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter ✨
- **`default`** (*str*) — the default value of the parameter *(optional)*
- **`description`** (*str*) — a description of the parameter *(optional)*
Example, slay:
parameters:
- hidden: name: FOO default: bar description: A parameter named FOO, defaults to 'bar'
---
## 🏷️ <cyan>label()</cyan>
A node label parameter, periodt 🎀 — this is how you pin jobs to nodes by label.
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter *(optional)*
- **`description`** (*str*) — a description of the parameter *(optional)*
- **`all-nodes`** (*bool*) — to run job on all nodes matching label in parallel (default: `false`) 🔥
- **`matching-label`** (*str*) — to run all nodes matching label `'success'`, `'unstable'` or `'allCases'` *(optional)*
- **`node-eligibility`** (*str*) — all nodes, ignore temporary nodes or ignore temporary offline nodes *(optional, default all nodes)*
Example:
parameters:
- label: name: EXAMPLE LABEL 1 description: "EXAMPLE LABEL DESCRIPTION 1" matching-label: "success" node-eligibility: "all"
---
## 🧩 <mint>matrix-combinations()</mint>
The Matrix combinations parameter — it's giving <rainbow>combinatorial main character energy</rainbow> 💅
> Requires the <blue>Jenkins Matrix Combinations Plugin</blue> — `https://plugins.jenkins.io/matrix-combinations-parameter`
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter
- **`description`** (*str*) — a description of the parameter *(optional)*
- **`filter`** (*str*) — Groovy expression to use filter the combination by default *(optional)*
Example:
parameters:
- matrix-combinations: name: FOO description: "Select matrix combinations" filter: "platform == foo"
---
## 📦 <yellow>maven-metadata()</yellow>
This parameter allows the resolution of maven artifact versions by contacting the repository and reading the `maven-metadata.xml`. So it literally goes and *asks* your repo what versions exist, no cap 🫶.
> Requires the <blue>Jenkins Maven Metadata Plugin</blue> — `https://plugins.jenkins.io/maven-metadata-plugin`
<pink>Parameters:</pink>
- **`name`** (*str*) — Name of the parameter
- **`description`** (*str*) — Description of the parameter *(optional)*
- **`repository-base-url`** (*str*) — URL from where you retrieve your artifacts (default `''`)
- **`repository-username`** (*str*) — Repository's username if authentication is required. (default `''`)
- **`repository-password`** (*str*) — Repository's password if authentication is required. (default `''`)
- **`artifact-group-id`** (*str*) — Unique project identifier (default `''`)
- **`artifact-id`** (*str*) — Name of the artifact without version (default `''`)
- **`packaging`** (*str*) — Artifact packaging option. Could be something such as `jar`, `zip`, `pom`.... (default `''`)
- **`versions-filter`** (*str*) — Specify a regular expression which will be used to filter the versions which are actually displayed when triggering a new build. (default `''`)
- **`default-value`** (*str*) — For features such as SVN polling a default value is required. If job will only be started manually, this field is not necessary. (default `''`)
- **`maximum-versions-to-display`** (*str*) — The maximum number of versions to display in the drop-down. Any non-number value as well as `0` or negative values will default to all. (default `10`)
- **`sorting-order`** (*str*) — ascending or descending (default descending)
Example, look at her go 🦋:
parameters:
- maven-metadata: name: 'maven metadata param' repository-base-url: 'http://nexus.example.com' repository-username: 'username' repository-password: 'password' artifact-group-id: 'com.example' artifact-id: 'example' packaging: 'jar' versions-filter: '[0-9]+' default-value: 'FIRST' maximum-versions-to-display: "5" sorting-order: "Ascending"
---
## 🖥️ <peach>node()</peach>
Defines a list of nodes where this job could potentially be executed on. Restrict where this project can be run.
> ⚠️ Okay bestie, listen up, this one matters: if you're using a node or label parameter to run your job on a particular node, you should **not** use the option `"Restrict where this project can be run"` in the job configuration — it will not have any effect to the selection of your node anymore! 💀
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter
- **`description`** (*str*) — a description of the parameter *(optional)*
- **`default-slaves`** (*list*) — The nodes used when job gets triggered by anything else other than manually
- **`allowed-slaves`** (*list*) — The nodes available for selection when job gets triggered manually. Empty means `'All'`.
- **`ignore-offline-nodes`** (*bool*) — Ignore nodes not online or not having executors (default `false`)
- **`allowed-multiselect`** (*bool*) — Allow multi node selection for concurrent builds - this option only makes sense (and must be selected!) in case the job is configured with: `"Execute concurrent builds if necessary"`. With this configuration the build will be executed on all the selected nodes in parallel. (default `false`) 🔥
Example:
parameters:
- node: name: SLAVE_NAME description: "Select slave" allowed-slaves:
- slave001
- slave002
- slave003 ignore-offline-nodes: true allowed-multiselect: true
---
## ➖ <lavender>parameter-separator()</lavender>
A parameter separator — it's literally just a lil divider for your parameter page, and honestly? Iconic 🎀
<pink>Parameters:</pink>
- **`name`** (*str*) — name of the separator (default `""`, the plugin will assign a randomly generated UUID if not specified)
- **`separator-style`** (*str*) — the style of the separator. Uses CSS. (default `""`)
- **`section-header-text`** (*str*) — the section header text of the separator (default `""`)
- **`section-header-style`** (*str*) — the section header style (CSS) of the separator. Uses CSS. (default `""`)
Example:
parameters:
- parameter-separator: name: lorem separator-style: FOO section-header: bar section-header-style: font-weight:bold;z-index:10000
---
## 🔐 <red>password()</red>
A password parameter. Keep your secrets secret, bestie 🤫
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter *(optional)*
- **`description`** (*str*) — a description of the parameter *(optional)*
Example:
parameters:
- password: name: FOO default: 1HSC0Ts6E161FysGf+e1xasgsHkgleLh09JUTYnipPvw= description: "A parameter named FOO."
---
## 🔁 <green>persistent-bool()</green>
A persistent boolean parameter — so your choice *remembers itself* between builds, which is highkey convenient 💅
> Requires the <blue>Jenkins Persistent Parameter Plugin</blue> — `https://plugins.jenkins.io/persistent-parameter`
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter *(optional)*
- **`description`** (*str*) — a description of the parameter *(optional)*
- **`successfulOnly`** (*bool*) — if `true`, then the value of the parameter gets persisted only between successful builds *(optional, default: `false`)*
Example:
parameters:
- persistent-bool: name: FOO default: false description: "A persistent parameter named FOO, defaults to 'false'." successfulOnly: false
---
## 🎯 <hotpink>persistent-choice()</hotpink>
A persistent single selection parameter — pick one, and it stays picked 🫶
> Requires the <blue>Jenkins Persistent Parameter Plugin</blue> — `https://plugins.jenkins.io/persistent-parameter`
<pink>Parameters:</pink>
- **`name`** (*str*) — the name of the parameter
- **`choices`** (*list*) — the available choices, first one is the default one.
- **`description`** (*str*) — a description of the parameter *(optional)*
- **`successfulOnly`** (*bool*) — if `true`, then the value of the parameter gets persisted only between successful builds *(optional, default: `false`)*
Example:
parameters:
- persistent-choice: name: project choices:
- nova
- glance description: "On which project to run?" successfulOnly: false
---
## 🧵 <purple>persistent-string()</purple>
A persistent string parameter.
<pink>Needs the Jenkins Persistent Parameter Plugin</pink> — `https://plugins.jenkins.io/persistent-parameter` 💖
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter (optional)
- **`description`** (*str*) — a description of the parameter (optional)
- **`trim`** (*bool*) — trims the whitespace off the start and the end of the string (optional, default: `false`)
- **`successfulOnly`** (*bool*) — when this is `true`, the parameter's value only gets persisted in between successful builds (optional, default: `false`)
**Example:**
parameters:
- persistent-string: name: FOO default: bar description: "A parameter named FOO, defaults to 'bar'." trim: false successfulOnly: false
---
## ✨ `persistent-text()` ✨
A persistent **text** parameter, bestie. 🌸
<pink>Needs the Jenkins Persistent Parameter Plugin</pink> — `https://plugins.jenkins.io/persistent-parameter` 💅
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter (optional)
- **`description`** (*str*) — a description of the parameter (optional)
- **`trim`** (*bool*) — trims the whitespace off the start and the end of the string (optional, default: `false`)
- **`successfulOnly`** (*bool*) — when this is `true`, the parameter's value only gets persisted in between successful builds (optional, default: `false`)
**Example:**
parameters:
- persistent-text: name: FOO default: bar description: "A persistent parameter named FOO, defaults to 'bar'." successfulOnly: false
---
## 🎀 `promoted build()` 🎀
A promoted build parameter. Yes, the name has a lil space in it, that's just how it is, no notes. 😌
<pink>Needs the Jenkins Promoted Builds Plugin</pink> — `https://plugins.jenkins.io/promoted-builds` 🔥
**Parameters**
- **`name`** (*str*) — the name of the parameter (**required**)
- **`project-name`** (*str*) — the job that the user gets to pick runs from (**required**)
- **`promotion-name`** (*str*) — which promotion process to choose from (optional)
- **`description`** (*str*) — a description of the parameter (optional)
**Example:**
parameters:
- promoted: name: FOO project-name: "foo-build" promotion-name: "passed-promotion" description: "Select a foo-build for promotion"
---
## 🌈 `random-string()` 🌈
This one literally generates a random string and hands it to the build, which is what stops Jenkins from smooshing queued builds together. Iconic behaviour tbh. ✨
<pink>Needs the Jenkins Random String Parameter Plugin</pink> — `https://plugins.jenkins.io/random-string-parameter` 🦋
**Parameters**
- **`name`** (*str*) — name of the parameter
- **`description`** (*str*) — description of the parameter (default `''`)
- **`failed-validation-message`** (*str*) — the failure message that shows up when the input is invalid (default `''`)
**Example:**
parameters:
- random-string: name: job-string description: "A random string passed to the job" failed-validation-message: "Your input string is invalid"
---
## 💜 `run()` 💜
A run parameter.
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`project-name`** (*str*) — the name of the job the user gets to pick runs from
- **`description`** (*str*) — a description of the parameter (optional)
**Example:**
parameters:
- run: name: FOO project-name: "foo-build" description: "Select a foo-build for promotion"
---
## 🍓 `string()` 🍓
A string parameter. The classic. The blueprint. 👑
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter (optional)
- **`description`** (*str*) — a description of the parameter (optional)
- **`trim`** (*bool*) — trims the whitespace off the start and the end of the string (optional, default: `false`)
**Example:**
parameters:
- string: name: FOO default: bar description: "A parameter named FOO, defaults to 'bar'." trim: true
---
## 🧚 `svn-tags()` 🧚
A svn tag parameter.
<pink>Needs the Jenkins Parameterized Trigger Plugin</pink> — `https://plugins.jenkins.io/parameterized-trigger` 💖
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`url`** (*str*) — the url to list tags from
- **`credentials-id`** (*str*) — credentials ID to use for authentication (default `''`)
- **`filter`** (*str*) — the regular expression used to filter tags (default `''`)
- **`default`** (*str*) — the default value of the parameter (default `''`)
- **`description`** (*str*) — a description of the parameter (default `''`)
- **`max-tags`** (*int*) — how many tags to display (default `'100'`)
- **`sort-newest-first`** (*bool*) — sorts tags from newest to oldest (default `true`)
- **`sort-z-to-a`** (*bool*) — sorts tags in reverse alphabetical order (default `false`)
**Example:**
parameters:
- svn-tags: name: BRANCH_NAME default: release description: A parameter named BRANCH_NAME default is release url: http://svn.example.org/repo filter: [A-za-z0-9]*
---
## 🌸 `text()` 🌸
A text parameter.
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter (optional)
- **`description`** (*str*) — a description of the parameter (optional)
**Example:**
parameters:
- text: name: FOO default: bar description: "A parameter named FOO, defaults to 'bar'."
---
## ⭐ `validating-string()` ⭐
A validating string parameter. It checks your homework before you submit it, fr fr. 📝
<pink>Needs the Jenkins Validating String Plugin</pink> — `https://plugins.jenkins.io/validating-string-parameter` 🫶
**Parameters**
- **`name`** (*str*) — the name of the parameter
- **`default`** (*str*) — the default value of the parameter (optional)
- **`description`** (*str*) — a description of the parameter (optional)
- **`regex`** (*str*) — a regular expression used to validate the string
- **`msg`** (*str*) — a message to display when validation fails
**Example:**
parameters:
- validating-string: name: FOO default: bar description: "A parameter named FOO, defaults to 'bar'." regex: [A-Za-z]* msg: Your entered value failed validation
---
# 👑 PROPERTIES 👑
The Properties module serves up a whole *buffet* of options, and every single one of them is implemented as a Jenkins job property. We love a ranged queen. 🌈
**Component:** `properties`
- **Macro** — `property`
- **Entry Point** — `jenkins_jobs.properties`
**Example:**
job: name: test_job
properties:
---
## `class properties.Properties(registry)`
### `component_list_type = 'properties'`
The component list type gets used to look up all the possible implementations of the component type via entry points (entry points hand back a *list* of components, so bestie, it should be plural). Set both `component_type` and `component_list_type` to `None` if the module has no components. 💅
### `component_type = 'property'`
The component type for the components of this module. It gets used to look for macros (those are defined singularly, so they should **not** be plural). Set both `component_type` and `component_list_type` to `None` if the module has no components. 💅
### `gen_xml(xml_parent, data)`
Updates the XML element tree based on the YAML data. Override this method to add elements to the XML output. Make new `Element` objects and add them to the `xml_parent`. <red>Heads up, the YAML data structure must not be modified.</red> 🚨
`:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure`
### `sequence = 20`
The sequence number for the module. Modules get invoked in the order of their sequence number so the XML output comes out consistently ordered. ✨
---
## `authenticated-build()`
Specifies an authorization matrix where only authenticated users are allowed to trigger a build.
> <red>Deprecated since version 0.1.0.</red> Please use `authorization` instead. 💀
**Example:**
properties:
- authenticated-build
## `authorization()`
Specifies an authorization matrix. In 3.0 version of plugin was added support for explicitly assigning permissions to groups or users with a given name to prevent confusion when names match either. 🔐
For `matrix-auth >= 3.0` :arg list `<inheritance-strategy>`: `<inheritance-strategy>` the name of inheritance strategy 🌟
`<inheritance-strategy>` values 🎀
- `parent`
- `global`
- `none`
**Parameters**
`prefix:<name>` (*list*) — `.INDENT 7.0`
- •
**prefix**
- `GROUP`
- `USER`
- `<name>` is the name of the group or user, containing
For `matrix-auth < 3.0`
**Parameters**
- **`<name>`** (list) — `<name>` is the name of the group or user, and the value is the list of rights you're handing them 💅
- **`<name>` rights** — the actual rights, and bestie there are twenty of them, okay, buckle up:
- `credentials-create`
- `credentials-delete`
- `credentials-manage-domains`
- `credentials-update`
- `credentials-view`
- `job-build`
- `job-cancel`
- `job-configure`
- `job-delete`
- `job-discover`
- `job-extended-read`
- `job-move`
- `job-read`
- `job-status`
- `job-workspace`
- `ownership-jobs`
- `run-delete`
- `run-replay`
- `run-update`
- `scm-tag`
**Example:**
properties:
- authorization: inheritance-strategy: none USER:admin:
- credentials-create
- credentials-delete
- credentials-manage-domains
- credentials-update
- credentials-view
- job-build
- job-cancel
- job-configure
- job-delete
- job-discover
- job-move
- job-read
- job-status
- job-workspace
- ownership-jobs
- run-delete
- run-replay
- run-update
- scm-tag GROUP:anonymous:
- job-read
- job-extended-read authenticated:
- job-read
- job-discover
- job-extended-read
---
### 🧺 batch-tasks()
Okay so batch tasks are, like, tasks for *events* — releases, integration, archiving, all that. And the point is that <pink>anyone</pink> on the project team can run them, in a way that leaves a whole record behind. Accountability but make it ✨convenient✨.
A batch task is literally just two things: a shell script and a name. When you execute a build, that shell script gets run on the workspace, exactly like a build does. And here's the part you need to internalise, bestie: **batch tasks and builds "lock" the workspace**. So while one of those activities is in progress, all the others just… block in the queue. Everyone else waits their turn. No cutting. 🫶
Needs the Jenkins Batch Task Plugin <https://plugins.jenkins.io/batch-task>.
**Parameters**
- **`batch-tasks`** (list) — the batch tasks themselves, bestie.
**Tasks**
- **`name`** (str) — task name.
- **`script`** (str) — task script.
**Example:**
properties:
- batch-tasks:
- name: release script: mvn -B release:prepare release:perform
- name: say hello script: echo "Hello world"
---
### 🌿 branch-api()
Enforces a minimum time between builds, based on the desired maximum rate. Basically it's the bouncer at the door like <italic>girl, cool your jets</italic> 💅
Needs the Jenkins Branch API Plugin <https://plugins.jenkins.io/branch-api>.
**Parameters**
- **`number-of-builds`** (int) — the maximum number of builds allowed within the specified time period. (default `1`)
- **`time-period`** (str) — the time period within which the maximum number of builds will be enforced. (default `'hour'`)
valid values: `second` `minute` `hour,` `day,` `week,` `month,` `year`
- **`skip-rate-limit`** (bool) — permit user triggered builds to skip the rate limit (default `false`)
**Minimal Example:**
properties:
- branch-api
**Full example:**
properties:
- branch-api: time-period: day number-of-builds: 5 skip-rate-limit: true
---
### 🚧 build-blocker()
This plugin keeps the actual job sitting in the queue if at least one name of currently running jobs matches one of the regular expressions you gave it. It's giving <purple>personally, I'm not going until THEY are done</purple> energy 😤
Needs the Jenkins Build Blocker Plugin <https://plugins.jenkins.io/build-blocker-plugin>.
**Parameters**
- **`use-build-blocker`** (bool) — enable or disable build blocker (default `true`)
- **`blocking-jobs`** (list) — one regular expression per line, to select blocking jobs by their names (**required**)
- **`block-level`** (str) — block build globally (`'GLOBAL'`) or per node (`'NODE'`) (default `'GLOBAL'`)
- **`queue-scanning`** (str) — scan build queue for all builds (`'ALL'`) or only buildable builds (`'BUILDABLE'`) (default `'DISABLED'`)
**Example:**
**Minimal Example:**
properties:
- build-blocker: blocking-jobs:
- ".*-deploy"
**Full Example:**
properties:
- build-blocker: use-build-blocker: true blocking-jobs:
- ".*-deploy"
- "^maintenance.*" block-level: 'NODE' queue-scanning: 'BUILDABLE'
---
### 🗑️ build-discarder()
Your build history is not a hoarder's paradise, bestie. Throw some of it out 🎀
**Parameters**
- **`days-to-keep`** (int) — number of days to keep builds for (default `-1`)
- **`num-to-keep`** (int) — number of builds to keep (default `-1`)
- **`artifact-days-to-keep`** (int) — number of days to keep builds with artifacts (default `-1`)
- **`artifact-num-to-keep`** (int) — number of builds with artifacts to keep (default `-1`)
**Example:**
properties:
- build-discarder: days-to-keep: 42 num-to-keep: 43 artifact-days-to-keep: 44 artifact-num-to-keep: 45
properties:
- build-discarder
---
### 💀 build-failure-analyzer()
Controls failure cause analysis for builds. So when it all goes wrong (and it will, no cap), this tells you *why*. Requires the Jenkins Build Failure Analyzer Plugin <https://plugins.jenkins.io/build-failure-analyzer>.
**Example:**
properties:
- build-failure-analyzer
properties:
- build-failure-analyzer: disabled: true
---
### 🔗 builds-chain-fingerprinter()
Builds chain fingerprinter. It fingerprints chains of builds, which is exactly as iconic as it sounds ✨
Requires the Jenkins Builds chain fingerprinter Plugin <https://github.com/jenkinsci/builds-chain-fingerprinter-plugin>.
**Parameters**
- **`per-builds-chain`** (bool) — enable builds hierarchy fingerprinting (default `false`)
- **`per-job-chain`** (bool) — enable jobs hierarchy fingerprinting (default `false`)
**Example:**
properties:
- builds-chain-fingerprinter: per-builds-chain: true per-job-chain: true
---
### 🚦 cachet-gating()
The Cachet Gating Plugin hooks you up with a gating mechanism based on the availability of resources. Like, no resources? No build. It's a vibe check for your infrastructure 🌈
Requires the Jenkins: Cachet Gate Plugin <https://plugins.jenkins.io/cachet-gating>.
**Parameters**
- **`required-resources`** (bool) — confirm availability of listed resources before building. Requires the list of resources to also be defined. (default `true`)
- **`resources`** (list) — which resources to gate
**Example:**
properties:
- cachet-gating: required-resources: true resources:
- beaker
- brew
---
### 📋 copyartifact()
Lets you specify a list of projects that have access to copy the artifacts of this project. It's an exclusive guest list, and yes, there's a bouncer 👑
Requires the Jenkins Copy Artifact plugin <https://plugins.jenkins.io/copyartifact>.
**Parameters**
- **`projects`** (str) — comma separated list of projects that can copy artifacts of this project. Wild card character `'*'` is available.
**Example:**
properties:
- copyartifact: projects: foo*
---
### 🚚 delivery-pipeline()
Requires the Jenkins Delivery Pipeline Plugin <https://plugins.jenkins.io/delivery-pipeline-plugin>.
**Parameters**
- **`stage`** (str) — name of the stage for this job (default `''`)
- **`task`** (str) — name of the task for this job (default `''`)
- **`description`** (str) — task description template for this job (default `''`)
**Minimal Example:**
properties:
- delivery-pipeline
**Full Example:**
properties:
- delivery-pipeline: stage: Stage task: Task description: Task-Description
---
### ⏸️ disable-resume()
Do not allow the pipeline to resume if the master restarts. Once it's gone, it's gone, no coming back, we don't do second chances here 😭
Requires the Jenkins Pipeline Job Plugin <https://plugins.jenkins.io/workflow-aggregator>.
**Example:**
properties:
- disable-resume
---
### 💾 disk-usage()
Enables the Disk Usage Plugin. It watches your disk usage because somebody has to 🦋
Requires the Jenkins Disk Usage Plugin <https://plugins.jenkins.io/disk-usage>.
**Example:**
properties:
- disk-usage
---
### 🐳 docker-container()
Requires the Jenkins: Docker Plugin <https://plugins.jenkins.io/docker-plugin>.
**Parameters**
- **`docker-registry-url`** (str) — URL of the Docker registry. (default `''`)
- **`credentials-id`** (str) — Credentials Id for the Docker registry. (default `''`)
- **`commit-on-success`** (bool) — When a job completes, the docker slave instance is committed with repository based on the job name and build number as tag. (default `false`)
- **`additional-tag`** (*str*) — an extra tag slapped onto the docker slave instance when it gets committed. (default `''`)
- **`push-on-success`** (*bool*) — okay so ALSO push the resulting image when committing the docker slave instance. (default `false`)
- **`clean-local-images`** (*bool*) — tidy up and yeet images from the local daemon once the build's done. (default `true`)
**Minimal Example:**
properties:
- docker-container
**Full Example:**
properties:
- docker-container: commit-on-success: true additional-tag: latest push-on-success: true clean-local-images: true docker-registry-url: https://index.docker.io/v1/ credentials-id: 71e4f29c-162b-40d0-85d9-3ddfba2911a0
---
## <pink>`gitbucket()`</p> 🐙
Link your Jenkins up with <hotpink>GitBucket</hotpink>. bestie compat era fr fr.
Needs the Jenkins GitBucket Plugin 💅 — `https://plugins.jenkins.io/gitbucket`.
**Parameters** ✨
- **`url`** (*str*) — the GitBucket URL to issue. (required, no skips 💀)
- **`link-enabled`** (*bool*) — turn hyperlinking to the issue ON. (default `false`)
**Minimal Example:**
properties:
- gitbucket: url: https://foo.com
**Full Example:**
properties:
- gitbucket: url: https://foo.com link-enabled: true
---
## <purple>`github()`</purple> 🐱
Sets the GitHub URL for the project. the way that this is literally just a URL and yet. iconic.
**Parameters**
- **`url`** (*str*) — the GitHub URL. (required)
- **`display-name`** (*str*) — this value gets used as the context name for commit status, but ONLY if a status builder or status publisher is defined for this project. (`>= 1.14.1`) (default `''`)
**Minimal Example:**
properties:
**Full Example:**
properties:
- github: url: https://github.com/openstack-infra/jenkins-job-builder/ display-name: foo
---
## <orange>wait, no — <peach>`gitlab()`</peach></orange> 🦊
Sets the GitLab connection for the project. You configure it over in the Jenkins Global Configuration, not here, bestie.
Requires the Jenkins GitLab Plugin — `https://plugins.jenkins.io/gitlab-plugin`.
**Parameters**
- **`connection`** (*str*) — the GitLab connection name. (required)
**Example:**
properties:
- gitlab: connection: gitlab-connection
---
## <lavender>`gitlab-logo()`</lavender> 🎀
Configures the GitLab-Logo Plugin. it's giving branding.
Requires the Jenkins GitLab Logo Plugin — `https://plugins.jenkins.io/gitlab-logo`.
**Parameters**
- **`repository-name`** (*str*) — the GitLab repository name. (required)
**Example:**
properties:
- gitlab-logo: repository-name: gitlab-repository-name
---
## <mint>`gogs()`</mint> 🐹
Sets the Gogs webhook properties for the project. webhook moment.
Requires the Jenkins Gogs Plugin — `https://plugins.jenkins.io/gogs-webhook`.
**Parameters**
- **`secret`** (*str*) — the webhook secret. (default `''`)
- **`branch-filter`** (*str*) — the filter that needs to match in order to trigger a job. (default `''`)
**Minimal Example:**
properties:
- gogs
**Full Example:**
properties:
- gogs: branch-filter: 'master' secret: 'yoursecret'
> ngl the minimal one has no colon and no value and that is correct, don't @ me, write it exactly like that. 💅
---
## <cyan>`groovy-label()`</cyan> 🧚
This plugin lets you use a Groovy script to restrict **where** this project can be run. main character energy but for node restriction.
Requires the Jenkins Groovy Label Assignment Plugin — `https://plugins.jenkins.io/groovy-label-assignment`.
The return value from the Groovy script is treated as the **Label Expression**. And it's treated like this, okay:
- A non-string value gets converted to a string using `toString()`
- When `null` or a blank string comes back, node restriction does NOT take effect (or it's not overwritten).
- When an exception occurs, or the Label Expression isn't parsed correctly, <red>builds are canceled</red>. 😭 keep that in mind.
**Parameters**
- **`script`** (*str*) — the Groovy script. (default `''`)
- **`sandbox`** (*bool*) — use Groovy Sandbox. (default `false`) If it's checked, this Groovy script runs in a sandbox with limited abilities. If it's unchecked, and you are not a Jenkins administrator, you will need to wait for an administrator to approve the script. 🫶
- **`classpath`** (*list*) — additional classpath entries accessible from the script, each of which should be an absolute local path or URL to a JAR file, according to "The file URI Scheme". (optional)
**Minimal Example:**
properties:
- groovy-label
**Full Example:**
properties:
- groovy-label: script: "$LABEL_NAME" sandbox: true classpath:
- "file:/minimal/absolute/path/to/file.jar"
- "file:///traditional/absolute/path/to/file.jar"
- "http://example.org/path/to/file.jar"
- "https://example.org/path/to/file.jar"
---
## <hotpink>`heavy-job()`</hotpink> 🏋️
This plugin lets you define a "weight" on each job, and makes each job consume that many executors. big job era.
Requires the Jenkins Heavy Job Plugin — `https://plugins.jenkins.io/heavy-job`.
**Parameters**
- **`weight`** (*int*) — specify the total number of executors that this job should occupy. (default `1`)
**Example:**
properties:
- heavy-job: weight: 2
---
## <yellow>`inject()`</yellow> 💉
Lets you inject environment variables into the build. casual sorcery ✨
Requires the Jenkins EnvInject Plugin — `https://plugins.jenkins.io/envinject`.
**Parameters**
- **`properties-file`** (*str*) — file to read with properties. (optional)
- **`properties-content`** (*str*) — `key=value` properties. (optional)
- **`script-file`** (*str*) — file with a script to run. (optional)
- **`script-content`** (*str*) — script to run. (optional)
- **`groovy-content`** (*str*) — groovy script to run. (optional)
- **`groovy-sandbox`** (*bool*) — run the groovy script in a sandbox. (default `false`)
- **`load-from-master`** (*bool*) — load files from master. (default `false`)
- **`enabled`** (*bool*) — injection enabled. (default `true`)
- **`keep-system-variables`** (*bool*) — keep system variables. (default `true`)
- **`keep-build-variables`** (*bool*) — keep build variables. (default `true`)
- **`override-build-parameters`** (*bool*) — override build parameters. (default `false`)
**Example:**
properties:
- inject: properties-content: | FOO=bar BAZ=foobar
---
## <blue>`least-load()`</blue> ⚖️
Enables the Least Load Plugin. lowkey the chillest scheduling vibe.
Requires the Jenkins Least Load Plugin — `https://plugins.jenkins.io/leastload`.
**Parameters**
- **`disabled`** (*bool*) — whether or not leastload is disabled. (default `true`)
**Example:**
properties:
- least-load: disabled: False
> yes, the default is `true` and the example says `False`. that is what the page says, that is what you get. 🙈
---
## <purple>`lockable-resources()`</purple> 🔒
Requires the Jenkins Lockable Resources Plugin — `https://plugins.jenkins.io/lockable-resources`.
**Parameters**
- **`resources`** (*str*) — list of required resources, space separated. (required, mutual exclusive with `label`)
- **`label`** (*str*) — if you've created a pool of resources, i.e. a label, you can take it into use here. The build will select the resource(s) from the pool that includes all resources sharing the given label. (required, mutual exclusive with `resources`)
- **`var-name`** (*str*) — name for the Jenkins variable to store the reserved resources in. Leave it empty to disable. (default `''`)
- **`number`** (*int*) — number of resources to request; an empty value or `0` means all. This is useful if you've got a pool of similar resources and you want one or more of them reserved. (default `0`)
- **`match-script`** (*str*) — Groovy script to reserve a resource based on its properties. Leave empty to disable. (default `None`)
- **`groovy-sandbox`** (*bool*) — execute the provided `match-script` in a Groovy sandbox. Leave empty to disable. (default `False`)
**Example:**
properties:
- lockable-resources: resources: "the-resource"
properties:
- lockable-resources: label: "pool-1"
properties:
- lockable-resources: resources: "the-resource" var-name: "RESOURCE_NAME" number: 10
properties:
- lockable-resources: match-script: "resourceName == MY_VAR" groovy-sandbox: true
> remember bestie: `resources` and `label` are **mutually exclusive**. pick one, not both. ✨
---
## <pink>`naginator-opt-out()`</pink> 🙅♀️
Lets you opt out so that no rebuild option for Naginator gets added. setting boundaries, love that for you.
Requires the Jenkins Naginator Plugin — `https://plugins.jenkins.io/naginator`.
**Parameters**
- **`opt-out`** (*bool*) — disables the rebuild option if `True`. (default `False`).
**Example:**
properties:
- naginator-opt-out: opt-out: true
---
## <mint>`office-365-connector()`</mint> 💌
Used to send actionable messages to MS Outlook or Teams. corporate slay fr.
Requires the Jenkins: `Office-365-Connector` Plugin (the page writes this one as `:jenkins-plugins:` `Office-365-Connector` Plugin).
**Parameters**
- **`webhooks`** (*list*) — list of webhooks. (required)
---
- <pink>**`url`**</pink> (`srt`) — the URL generated in the Office 365 Connectors page, and bestie, it is **required** 💅
- <pink>**`name`**</pink> (`str`) — lets you name the connection. It is *not* mandatory, but it helps a lot when there are many connections assigned to the build (optional, default `''`) 🎀
- <pink>**`start-notification`**</pink> (`bool`) — should the notification be sent on start of build? (optional, default `False`) ✨
- <pink>**`notify-success`**</pink> (`bool`) — should the notification be sent on succeeded build? (optional, default `True`) 💖
- <pink>**`notify-aborted`**</pink> (`bool`) — should the notification be sent on aborted build? (optional, default `False`) 🦋
- <pink>**`notify-not-built`**</pink> (`bool`) — should the notification be sent on not built build? (optional, default `False`) 🌸
- <pink>**`notify-unstable`**</pink> (`bool`) — should the notification be sent on unstable build? (optional, default `True`) 🌈
- <pink>**`notify-failure`**</pink> (`bool`) — should the notification be sent on failed build? (optional, default `True`) 🔥
- <pink>**`notify-back-to-normal`**</pink> (`bool`) — should the notification be sent on back to normal build? (optional, default `True`) 👑
- <pink>**`notify-repeated-failure`**</pink> (`bool`) — should the notification be sent on repeated failures? (optional, default `False`) 💀
- <pink>**`timeout`**</pink> (`int`) — connection timeout, in milliseconds, for TCP and HTTP (optional, default `30000`) ⏳
- <pink>**`macros`**</pink> (`list`) — list of macros 🧚
- <lavender>**`template`**</lavender> (`str`) · <lavender>**`value`**</lavender> (`str`)
- <pink>**`fact-definitions`**</pink> (`list`) — list of fact definitions 🫶
- <lavender>**`name`**</lavender> (`str`) · <lavender>**`template`**</lavender> (`str`)
**Example:**
properties:
- office-365-connector: webhooks:
- url: http://outlook.office.com/webhook name: full start-notification: true notify-success: false notify-aborted: true notify-not-built: true notify-unstable: false notify-failure: false notify-back-to-normal: false notify-repeated-failure: true timeout: 30001 macros:
- template: macro1 value: macro1_value
- template: macro2 value: macro2_value fact-definitions:
- name: fd1 template: fd1_value
- name: fd2 template: fd2_value
- url: http://outlook.office.com/webhook name: full start-notification: true notify-success: false notify-aborted: true notify-not-built: true notify-unstable: false notify-failure: false notify-back-to-normal: false notify-repeated-failure: true timeout: 30001 macros:
### <rainbow>ownership()</rainbow> 👑
This plugin gives you explicit ownership for jobs and slave nodes. It's giving control, no cap.
Requires the Jenkins Ownership Plugin (`https://plugins.jenkins.io/ownership`).
**Parameters**
- <pink>**`enabled`**</pink> (`bool`) — whether ownership enabled (default: `true`)
- <pink>**`owner`**</pink> (`str`) — the owner of job
- <pink>**`co-owners`**</pink> (`list`) — list of job co-owners
**Example:**
properties:
- ownership: owner: foo co-owners:
- bar
- moo
### <cyan>priority-sorter()</cyan> 💅
Allows simple ordering of builds, using a configurable job priority. So your fave build can cut the line, periodt.
Requires the Jenkins Priority Sorter Plugin (`https://plugins.jenkins.io/PrioritySorter`).
**Parameters**
- <pink>**`priority`**</pink> (`int`) — Priority of the job. Higher value means higher priority, with `3` as the default priority. (required)
**Example:**
properties:
- priority-sorter: priority: 3
### <purple>promoted-build()</purple> ⭐
Marks a build for promotion. A promotion process with an identical name **must** be created via the web interface in the job in order for the job promotion to persist. Promotion processes themselves cannot be configured by `jenkins-jobs` due to the separate storage of plugin configuration files. So yeah, web UI first, bestie.
Requires the Jenkins Promoted Builds Plugin (`https://plugins.jenkins.io/promoted-builds`).
**Parameters**
- <pink>**`names`**</pink> (`list`) — the promoted build names (optional)
**Example:**
properties:
- promoted-build: names:
- "Release to QA"
- "Jane Must Approve"
### <mint>rebuild()</mint> 🎀
This plug-in allows the user to rebuild a parameterized build without entering the parameters again. It will also allow the user to edit the parameters before rebuilding. Iconic, honestly.
Requires the Jenkins Rebuild Plugin (`https://plugins.jenkins.io/rebuild`).
**Parameters**
- <pink>**`auto-rebuild`**</pink> (`bool`) — Rebuild without asking for parameters (default `false`)
- <pink>**`rebuild-disabled`**</pink> (`bool`) — Disable rebuilding for this job (default `false`)
**Minimal Example:**
properties:
- rebuild
**Full Example:**
properties:
- rebuild: auto-rebuild: true rebuild-disabled: true
### <yellow>resource-gating()</yellow> 🔒
Jenkins Gating enables requiring external resources to be available before build starts. Vibe check before the build walks in.
Requires the Jenkins: Jenkins Gating (`https://plugins.jenkins.io/gating-core`).
**Parameters**
- <pink>**`resources`**</pink> (`list`) — Resource identifiers to be up before building
**Example:**
properties:
- resource-gating: resources:
- external/ci.example.com
- foo/bar/baz
### <peach>sidebar()</peach> 🌸
Allows you to add links in the sidebar. Cute little shortcuts, we love.
Requires the Jenkins Sidebar-Link Plugin (`https://plugins.jenkins.io/sidebar-link`).
**Parameters**
- <pink>**`url`**</pink> (`str`) — url to link to (optional)
- <pink>**`text`**</pink> (`str`) — text for the link (optional)
- <pink>**`icon`**</pink> (`str`) — path to icon (optional)
**Example:**
properties:
- sidebar: url: https://jenkins.debian.net/userContent/about.html text: About jenkins.debian.net icon: /userContent/images/debian-swirl-24x24.png
- sidebar: url: https://jenkins.debian.net/view/reproducible text: reproducible builds jobs icon: /userContent/images/debian-jenkins-24x24.png
### <hotpink>slack()</hotpink> 💬
Requires the Jenkins Slack Plugin (`https://plugins.jenkins.io/slack`).
When using Slack Plugin version `< 2.0`, Slack Plugin itself requires a publisher aswell as properties — please note that you have to add the publisher to your job configuration aswell. When using Slack Plugin version `>= 2.0`, you should only configure the publisher. So check your version, bestie, it's giving compatibility lore.
**Parameters**
- <pink>**`notify-start`**</pink> (`bool`) — Send notification when the job starts (default `false`)
- <pink>**`notify-success`**</pink> (`bool`) — Send notification on success. (default `false`)
- <pink>**`notify-aborted`**</pink> (`bool`) — Send notification when job is aborted. (default `false`)
- <pink>**`notify-not-built`**</pink> (`bool`) — Send notification when job set to `NOT_BUILT` status. (default `false`)
- <pink>**`notify-unstable`**</pink> (`bool`) — Send notification when job becomes unstable. (default `false`)
- <pink>**`notify-failure`**</pink> (`bool`) — Send notification when job fails. (default `false`)
- <pink>**`notify-back-to-normal`**</pink> (`bool`) — Send notification when job is succeeding again after being unstable or failed. (default `false`)
- <pink>**`notify-repeated-failure`**</pink> (`bool`) — Send notification when job is still failing after last failure. (default `false`)
- <pink>**`include-test-summary`**</pink> (`bool`) — Include the test summary. (default `False`)
- <pink>**`include-custom-message`**</pink> (`bool`) — Include a custom message into the notification. (default `false`)
- <pink>**`custom-message`**</pink> (`str`) — Custom message to be included. (default `''`)
- <pink>**`room`**</pink> (`str`) — A comma separated list of rooms / channels to send the notifications to. (default `''`)
**Example:**
properties:
- slack: room: dummy, dummy2 notify-start: true notify-success: true
### <lavender>slave-prerequisites()</lavender> 🧚
This plugin allows you to check prerequisites on slave before a job can run a build on it. Gotta make sure the node is actually ready before you send the build in there.
Requires the Jenkins Slave Prerequisites Plugin (`https://plugins.jenkins.io/slave-prerequisites`).
**Parameters**
- <pink>**`script`**</pink> (`str`) — A script to be executed on slave node. If returning non `0` status, the node will be vetoed from hosting the build. (required)
- <pink>**`interpreter`**</pink> (`str`) — Command line interpreter to be used for executing the prerequisite script - either `shell` for Unix shell or `cmd` for Windows batch script. (default `shell`)
**Example:**
properties:
- slave-prerequisites: script: | #!/bin/bash AVAILABLE=$(df -BG --output=avail / | tail -1) test ${AVAILABLE%G} -ge 10
properties:
- slave-prerequisites: interpreter: cmd script: | @echo off if exist C:\Jenkins\workspace.lock exit /b 1
## Publishers 💖
OK so **publishers** are the little post-credits scenes of your Jenkins job, bestie — they define the actions the job should do *after* the build is done. 🎬
**Component:** `publishers`
- **Macro** — `publisher`
- **Entry Point** — `jenkins_jobs.publishers`
### class `publishers.Publishers(registry)`
- **`component_list_type = 'publishers'`** — this is the list type that gets used to look up all the possible implementations of this component type through entry points (entry points hand you a *list* of components, so yeah, plural, obviously 💅). If a module doesn't have any components at all, set both `component_type` and `component_list_type` to `None`, no cap.
- **`component_type = 'publisher'`** — the component type for the components of this module. This is what gets used to hunt down macros (those are defined *singularly*, so not plural, don't come for me). Same deal: if the module has no components, set both `component_type` and `component_list_type` to `None`.
- **`gen_xml(xml_parent, data)`** — updates the XML element tree based on your YAML data. Override this method if you wanna add stuff to the XML output. Make new `Element` objects and add them to the `xml_parent`. And listen — the YAML data structure **must not be modified**. Hands off. 🙅
:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure
- **`sequence = 70`** — the sequence number for the module. Modules get invoked in order of their sequence number so the XML output comes out consistently ordered. Iconic organisational behaviour, honestly.
---
### `aggregate-flow-tests()`
Aggregates the downstream test results in a Build Flow job. 🧪
**Requires** the Jenkins Build Flow Test Aggregator Plugin <https://github.com/zeroturnaround/build-flow-test-aggregator>.
**Parameters**
- `show-test-results-trend` (bool) — whether to show the test results trend graph (default `true`)
**Example:**
publishers:
- aggregate-flow-tests: show-test-results-trend: false
### `aggregate-tests()`
Aggregates downstream test results. That's it, that's the whole vibe. 🫶
**Parameters**
- `include-failed-builds` (bool) — whether to include failed builds (default `false`)
**Example:**
publishers:
- aggregate-tests: include-failed-builds: true
### `allure()`
Publishes an Allure report for the build. **Requires** the Jenkins Allure Plugin <https://plugins.jenkins.io/allure-jenkins-plugin>. ✨
**Parameters**
- `jdk` (str) — a string identifier for a JDK installation in Jenkins
- `commandline` (str) — a string identifier for an Allure-commandline tool installation
- `report-build-policy` (str) — a string identifier for a report build policy enum. Possible values: `'ALWAYS'`, `'UNSTABLE'`, `'UNSUCCESSFUL'`. (By default it's `'ALWAYS'`)
- `include-properties` (bool) — flag to include the specified properties
- `results-paths` (list) — list of results directories
- `properties` (list) — list of `key:value` property pairs
**Minimal Example:**
publishers:
- allure: results-paths:
- path: 'build/allure-results'
**Full Example:**
publishers:
- allure: results-paths:
- path: 'build/allure-results1'
- path: 'build/allure-results2' properties:
- key: 'allure.link.issue.pattern' value: 'http://test.tms/{}' jdk: openjdk1.8 commandline: allure2 report-build-policy: UNSTABLE include-properties: true
### `archive()`
Archives build artifacts. Get those files saved, babes. 📦
**Parameters**
- `artifacts` (str) — path specifier for the artifacts to archive
- `excludes` (str) — path specifier for artifacts to exclude (optional)
- `latest-only` (bool) — only keep the artifacts from the latest successful build
- `allow-empty` (bool) — pass the build if no artifacts are found (default `false`)
- `follow-symlinks` (bool) — follow symbolic links during archiving (default `false`)
- `only-if-success` (bool) — archive artifacts only if the build is successful (default `false`)
- `fingerprint` (bool) — fingerprint all archived artifacts (default `false`)
- `default-excludes` (bool) — this option lets you enable or disable the default Ant exclusions. (default `true`)
- `case-sensitive` (bool) — treat include and exclude patterns as case sensitive. (default `true`)
**Example:**
publishers:
- archive: artifacts: '*.tar.gz' allow-empty: 'true' fingerprint: true default-excludes: false
### `artifact-deployer()`
This plugin makes it possible to copy artifacts to remote locations. Long-distance relationship with your build outputs? Slay. 🌍
**Requires** the Jenkins ArtifactDeployer Plugin <https://plugins.jenkins.io/artifactdeployer>.
**Parameters**
- `entries` (list) — list of deploy entries, each one containing:
- `files` (str) — files to deploy
- `basedir` (str) — the dir from which files are deployed
- `excludes` (str) — the mask to exclude files
- `remote` (str) — a remote output directory
- `flatten` (bool) — ignore the source directory structure (default `false`)
- `delete-remote` (bool) — clean-up the remote directory before deployment (default `false`)
- `delete-remote-artifacts` (bool) — delete remote artifacts when the build is deleted (default `false`)
- `fail-no-files` (bool) — fail the build if there are no files (default `false`)
- `groovy-script` (str) — execute a Groovy script before a build is deleted
- `deploy-if-fail` (bool) — deploy if the build is failed (default `false`)
**Example:**
publishers:
- artifact-deployer: entries:
- files: '.tar.gz' basedir: '/opt/data' excludes: 'tmp*' remote: '/home/test/' flatten: true delete-remote: true delete-remote-artifacts: true fail-no-files: true groovy-script: 'print 123' deploy-if-fail: true
### `artifactory()`
Uses/requires the Artifactory plugin to deploy artifacts to an Artifactory Server. 🚀
**Requires** the Jenkins Artifactory Plugin <https://plugins.jenkins.io/artifactory>.
### Parameters
- **`url`** *(str)* — the Artifactory server url you're pointing at (default `''`)
- **`name`** *(str)* — the Artifactory user, with permissions, that you use to connect to the selected Artifactory Server (default `''`)
- **`release-repo-key`** *(str)* — name of the Release repository (default `''`)
- **`snapshot-repo-key`** *(str)* — name of the Snapshots repository (default `''`)
- **`publish-build-info`** *(bool)* — push build metadata along with the artifacts (default `false`)
- **`discard-old-builds`** *(bool)* — yeet older build info out of Artifactory (default `false`)
- **`discard-build-artifacts`** *(bool)* — yeet older build artifacts out of Artifactory (default `false`)
- **`even-if-unstable`** *(bool)* — deploy artifacts even when the build is unstable (default `false`)
- **`run-checks`** *(bool)* — run the automatic license scanning check once the build is done (default `false`)
- **`include-publish-artifacts`** *(bool)* — include the build's published module artifacts in the license violation checks, if they're also used as dependencies for other modules in this build (default `false`)
- **`pass-identified-downstream`** *(bool)* — when true, a build parameter named `ARTIFACTORY_BUILD_ROOT` with a value of `${JOB_NAME}-${BUILD_NUMBER}` gets sent to downstream builds (default `false`)
- **`license-auto-discovery`** *(bool)* — tells Artifactory **not** to try and automatically analyze and tag the build's dependencies with license information upon deployment (default `true`)
- **`enable-issue-tracker-integration`** *(bool)* — when the Jenkins JIRA plugin is enabled, synchronize info about JIRA issues over to Artifactory and attach issue info to build artifacts (default `false`)
- **`aggregate-build-issues`** *(bool)* — when the Jenkins JIRA plugin is enabled, include all the issues from previous builds up to the latest build status defined in `"Aggregation Build Status"` (default `false`)
- **`allow-promotion-of-non-staged-builds`** *(bool)* — the build promotion operation becomes available to **all** successful builds instead of only the staged ones (default `false`)
- **`filter-excluded-artifacts-from-build`** *(bool)* — add the excluded files to the `excludedArtifacts` list and remove them from the artifacts list in the build info (default `false`)
- **`scopes`** *(str)* — a list of dependency scopes/configurations to run license violation checks on. Leave it empty and all dependencies from all scopes get checked (default `''`)
- **`violation-recipients`** *(str)* — the recipients who need to be notified about license violations in the build info (default `''`)
- **`matrix-params`** *(list)* — semicolon-separated list of properties to attach to all deployed artifacts, on top of the default ones: `build.name`, `build.number`, and `vcs.revision` (default `[]`)
- **`black-duck-app-name`** *(str)* — the existing Black Duck Code Center application name (default `''`)
- **`black-duck-app-version`** *(str)* — the existing Black Duck Code Center application version (default `''`)
- **`black-duck-report-recipients`** *(str)* — the recipients who'll get a report emailed to them once the automatic Black Duck Code Center compliance checks finish (default `''`)
- **`black-duck-scopes`** *(str)* — a list of dependency scopes/configurations to run Black Duck Code Center compliance checks on. Leave it empty and all deps from all scopes get checked (default `''`)
- **`black-duck-run-checks`** *(bool)* — automatic Black Duck Code Center compliance checks happen after the build completes (default `false`)
- **`black-duck-include-published-artifacts`** *(bool)* — include the build's published module artifacts in the license violation checks, if they're also used as dependencies for other modules in this build (default `false`)
- **`auto-create-missing-component-requests`** *(bool)* — auto-create missing components in the Black Duck Code Center application after the build is completed and deployed in Artifactory (default `true`)
- **`auto-discard-stale-component-requests`** *(bool)* — auto-discard stale components in the Black Duck Code Center application after the build is completed and deployed in Artifactory (default `true`)
- **`deploy-artifacts`** *(bool)* — push artifacts to the Artifactory Server. Use `deployment-include-patterns` and `deployment-exclude-patterns` to filter which artifacts get deployed. (default `true`)
- **`deployment-include-patterns`** *(list)* — new line or comma separated mappings of build artifacts to published artifacts. Supports Ant-style wildcards mapping to target directories. E.g.: `/.zip=>dir` (default `[]`)
- **`deployment-exclude-patterns`** *(list)* — new line or comma separated patterns for excluding artifacts from deployment to Artifactory (default `[]`)
- **`env-vars-include`** *(bool)* — include all environment variables accessible by the build process. Jenkins-specific env variables are **always** included. Use `env-vars-include-patterns` and `env-vars-exclude-patterns` to filter which variables get published, (default `false`)
- **`env-vars-include-patterns`** *(list)* — comma or space-separated list of environment variables that'll be included as part of the published build info. Environment variables can contain the `*` and the `?` wildcards (default `[]`)
- **`env-vars-exclude-patterns`** *(list)* — comma or space-separated list of environment variables that'll be excluded from the published build info (default `[]`)
<yellow>Example:</yellow>
publishers:
- artifactory: url: http://artifactory.example.net/artifactory name: 'test' release-repo-key: libs-release-local snapshot-repo-key: libs-snapshot-local
publishers:
- artifactory: url: http://artifactory.example.net/artifactory name: 'test' release-repo-key: libs-release-local snapshot-repo-key: libs-snapshot-local publish-build-info: true discard-old-builds: true discard-build-artifacts: true even-if-unstable: true run-checks: true include-publish-artifacts: true pass-identified-downstream: true license-auto-discovery: true aggregate-build-issues: true allow-promotion-of-non-staged-builds: true filter-excluded-artifacts-from-build: true violation-recipients: myfake@email.com matrix-params: [] black-duck-app-name: myapp black-duck-app-version: '1.0' black-duck-report-recipients: myfake@email.com black-duck-scopes: [] black-duck-run-checks: true black-duck-include-published-artifacts: true auto-create-missing-component-requests: false auto-discard-stale-component-requests: false deploy-artifacts: true deployment-include-patterns: [] deployment-exclude-patterns: [] env-vars-include: true env-vars-include-patterns: [] env-vars-exclude-patterns: []
---
### `blame-upstream()`
Notify upstream committers when the build fails 🫶
Needs the Jenkins Blame Upstream Committers Plugin — `https://github.com/jenkinsci/blame-upstream-commiters-plugin`.
<yellow>Example:</yellow>
publishers:
- blame-upstream
---
### `build-publisher()`
This plugin lets records from one Jenkins get published onto a **different** Jenkins. cross-instance gossip, iconic honestly.
Needs the Jenkins Build Publisher Plugin — `https://plugins.jenkins.io/build-publisher`.
#### Parameters
- **`publish-unstable-builds`** *(bool)* — publish unstable builds (default `true`)
- **`publish-failed-builds`** *(bool)* — publish failed builds (default `true`)
- **`days-to-keep`** *(int)* — how many days to keep when publishing results (optional)
- **`num-to-keep`** *(int)* — how many jobs to keep in the published results (optional)
<yellow>Minimal Example:</yellow>
publishers:
- build-publisher
<yellow>Full Example:</yellow>
publishers:
- build-publisher: publish-unstable-builds: false publish-failed-builds: false days-to-keep: -1 num-to-keep: 100
---
### `campfire()`
Send build notifications to Campfire rooms. Needs the Jenkins Campfire Plugin — `https://plugins.jenkins.io/campfire`.
Campfire notifications have global default values that have to be configured for the Jenkins instance. If you don't specify specific values for a job, those defaults get used — so literally every config param here is optional. 💅
#### Parameters
- **`subdomain`** *(str)* — override the default campfire subdomain
- **`token`** *(str)* — override the default API token
- **`ssl`** *(bool)* — override the default 'use SSL'
- **`room`** *(str)* — override the default room name
<yellow>Example:</yellow>
publishers:
- campfire: subdomain: 'sub' ssl: true token: 'TOKEN' room: 'room'
---
### `checkstyle()`
Okay so this one *publishes trend reports with Checkstyle*. Trend reports!! The little graphs that go up and down and make you feel things 💖
Requires the Jenkins Checkstyle Plugin — it lives at `https://github.com/jenkinsci/checkstyle-plugin`.
The `checkstyle` component takes a dictionary, and here's literally every single thing you can stuff in it:
**Parameters**
- **`pattern`** (*str*) — Report filename pattern (default `''`)
- **`can-run-on-failed`** (*bool*) — Also runs for failed builds, instead of just stable or unstable builds (default `false`)
- **`should-detect-modules`** (*bool*) — Determines if Ant or Maven modules should be detected for all files that contain warnings (default `false`)
- **`healthy`** (*int*) — Sunny threshold (default `''`)
- **`unhealthy`** (*int*) — Stormy threshold (default `''`)
- **`health-threshold`** (*str*) — Threshold priority for health status (`'low'`, `'normal'` or `'high'`) (default `'low'`)
- **`thresholds`** (*dict*) — Mark build as failed or unstable if the number of errors exceeds a threshold. (optional)
- **`unstable`** (*dict*)
- `total-all` (*int*)
- `total-high` (*int*)
- `total-normal` (*int*)
- `total-low` (*int*)
- `new-all` (*int*)
- `new-high` (*int*)
- `new-normal` (*int*)
- `new-low` (*int*)
- **`failed`** (*dict*)
- `total-all` (*int*)
- `total-high` (*int*)
- `total-normal` (*int*)
- `total-low` (*int*)
- `new-all` (*int*)
- `new-high` (*int*)
- `new-normal` (*int*)
- `new-low` (*int*)
- **`default-encoding`** (*str*) — Encoding for parsing or showing files (default `''`)
- **`do-not-resolve-relative-paths`** (*bool*) — (default `false`)
- **`dont-compute-new`** (*bool*) — If set to `false`, computes new warnings based on the reference build (default `true`)
- **`use-previous-build-as-reference`** (*bool*) — determines whether to always use the previous build as the reference build (default `false`)
- **`use-stable-build-as-reference`** (*bool*) — The number of new warnings will be calculated based on the last stable build, allowing reverts of unstable builds where the number of warnings was decreased. (default `false`)
- **`use-delta-values`** (*bool*) — If set then the number of new warnings is calculated by subtracting the total number of warnings of the current build from the reference build. (default `false`)
**Example:**
publishers:
- checkstyle: pattern: '**/checkstyle-result.xml' healthy: 0 unhealthy: 100 health-threshold: 'high' thresholds: unstable: total-high: 10 failed: total-high: 1
**Full example** (every single knob, turned, bestie 🎀):
publishers:
- checkstyle: pattern: '**/checkstyle-result.xml' can-run-on-failed: true should-detect-modules: true healthy: 0 unhealthy: 100 health-threshold: 'high' thresholds: unstable: total-all: 90 total-high: 80 total-normal: 70 total-low: 60 new-all: 50 new-high: 40 new-normal: 30 new-low: 20 failed: total-all: 91 total-high: 81 total-normal: 71 total-low: 61 new-all: 51 new-high: 41 new-normal: 31 new-low: 21 default-encoding: 'utf-8' do-not-resolve-relative-paths: true dont-compute-new: false use-stable-build-as-reference: true use-delta-values: true
---
### `chuck-norris()`
Not me finding this one at 2am 😭 It <pink>displays a picture of Chuck Norris</pink> (instead of Jenkins the butler, iconic behaviour) and a random Chuck Norris 'The Programmer' fact on each build page.
Requires the Jenkins ChuckNorris Plugin: `https://plugins.jenkins.io/chucknorris`.
**Example:**
publishers:
- chuck-norris
---
### `cifs()`
Upload files via <cyan>CIFS</cyan>. Requires the Jenkins Publish over CIFS Plugin: `https://plugins.jenkins.io/publish-over-cifs`.
**Parameters**
- **`site`** (*str*) — name of the cifs site/share (**required**)
- **`target`** (*str*) — destination directory (**required**)
- **`target-is-date-format`** (*bool*) — whether target is a date format. If `true`, raw text should be quoted (default `false`)
- **`clean-remote`** (*bool*) — should the remote directory be deleted before transferring files (default `false`)
- **`source`** (*str*) — source path specifier (**required**)
- **`excludes`** (*str*) — excluded file pattern (default `''`)
- **`remove-prefix`** (*str*) — prefix to remove from uploaded file paths (default `''`)
- **`fail-on-error`** (*bool*) — fail the build if an error occurs (default `false`).
- **`flatten`** (*bool*) — only create files on the server, don't create directories (default `false`).
- **`verbose`** (*bool*) — adds lots of detail useful for debug to the console but generally should be left off (default `false`)
- **`retries`** (*int*) — the number of times to retry this server in the event of failure (optional)
- **`retry-delay`** (*int*) — the time to wait, in milliseconds, before attempting another transfer (default `10000`)
**Minimal Example:**
publishers:
- cifs: site: 'cifs.share' target: 'dest/dir' source: 'base/source/dir/**'
**Full Example:**
publishers:
- cifs: site: 'cifs.share' target: "'dest/dir/'yyyyMMddHHmmss" target-is-date-format: true clean-remote: true source: 'base/source/dir/' excludes: '/*.excludedfiletype' remove-prefix: 'base/source/dir' fail-on-error: true flatten: true verbose: true retries: 99 retry-delay: 12345
---
### `cigame()`
Gamification era fr 🎮 This plugin introduces a game where users get points for improving the builds. Requires the Jenkins Continuous Integration Game plugin: `https://github.com/jenkinsci/ci-game-plugin`.
**Example:**
publishers:
- cigame
---
### `claim-build()`
Claim build failures 🫶 Requires the Jenkins Claim Plugin: `https://plugins.jenkins.io/claim`.
**Example:**
publishers:
- claim-build
---
### `clamav()`
Check files with <green>ClamAV</green>, an open source antivirus engine. Requires the Jenkins ClamAV Plugin: `https://plugins.jenkins.io/clamav`.
**Parameters**
- **`includes`** (*str*) — Comma separated list of files that should be scanned. Must be set for ClamAV to check for artifacts. (default `''`)
- **`excludes`** (*str*) — Comma separated list of files that should be ignored (default `''`)
**Full Example:**
publishers:
- clamav: includes: '*.zip' excludes: 'foo.zip'
**Minimal Example:**
publishers:
- clamav
---
### `clone-workspace()`
Archive the workspace from builds of one project and reuse them as the SCM source for another project. Lowkey the most underrated trick on this whole list, no cap 🦋 Requires the Jenkins Clone Workspace SCM Plugin: `https://plugins.jenkins.io/clone-workspace-scm`.
**Parameters**
- **`workspace-glob`** (*str*) — Files to include in cloned workspace (default `''`)
- **`workspace-exclude-glob`** (*str*) — Files to exclude from cloned workspace
- **`criteria`** (*str*) — Criteria for build to be archived. Can be `'any'`, `'not failed'`, or `'successful'`. (default `'any'`)
- **`archive-method`** (*str*) — Choose the method to use for archiving the workspace. Can be `'tar'` or `'zip'`. (default `'tar'`)
- **`override-default-excludes`** (*bool*) — Override default ant excludes. (default `false`)
**Minimal example:**
publishers:
- clone-workspace
**Full example:**
publishers:
- clone-workspace: criteria: "Any" archive-method: "TAR" override-default-excludes: false workspace-glob: "/.zip" workspace-exclude-glob: "/.tgz"
## 💖 `cloudfoundry()`
okay so bestie, imagine shipping your whole project at the end of a build — that's literally this one. It pushes a project to Cloud Foundry, or honestly any CF-based platform (e.g. Stackato), at the end of a build. It requires the **Jenkins Cloud Foundry Plugin**, which lives at `https://plugins.jenkins.io/cloudfoundry` 🫶
### Parameters
- **`target`** (*str*) — the API endpoint of the platform you want to push to. This is the URL you use to access the platform, possibly with `".api"` added. **required** 🔥
- **`organization`** (*str*) — an org is a development account that an individual or multiple collaborators can own and use. **required**
- **`space`** (*str*) — gives users access to a shared location for application development, deployment, and maintenance. **required**
- **`credentials-id`** (*str*) — the credentials-id of the user. **required** 🔑
- **`self-signed`** (*bool*) — allow self-signed SSL certificates from the target (default `false`)
- **`reset-app`** (*bool*) — delete the app before pushing the app's configurations (default `false`)
- **`plugin-timeout`** (*int*) — the time in seconds before the Cloud Foundry plugin stops fetching logs and marks the build a failure (default `120`) ⏳
- **`create-services`** (*list*) — create services automatically (default `''`)
- **`name`** (*'str'*) — service name (default `''`)
- **`type`** (*'str'*) — service type (default `''`)
- **`plan`** (*'str'*) — service plan (default `''`)
- **`reset-service`** (*'bool'*) — delete the service before creating the new one (default `false`)
- **`value`** (*str*) — select to read configuration from a manifest file, or to enter configuration in Jenkins (default `'manifestFile'`)
- **`manifest-file`** (*str*) — path to manifest file (default `'manifest.yml'`) 📄
- **`app-name`** (*str*) — the application's name. Defaults to the Jenkins build name. (default `''`)
- **`memory`** (*int*) — the application's memory usage in MB (default `512`)
- **`host-name`** (*str*) — the hostname of the URI to access your application. Defaults to `app-name` (default `''`)
- **`instances`** (*int*) — number of instances of your application on creation (default `1`)
- **`manifest-timeout`** (*int*) — the time in seconds before the health-manager gives up on starting the application (default `60`)
- **`no-route`** (*bool*) — no URI path will be created to access the application (default `false`)
- **`app-path`** (*str*) — path to application (default `''`)
- **`build-pack`** — if your application requires a custom buildpack, you can use this to specify its URL or name (default `''`)
- **`stack`** (*str*) — if your application requires a custom stack, you can use this to specify its name. (default `''`)
- **`command`** (*str*) — set a custom start command for your application (default `''`)
- **`domain`** (*str*) — the domain of the URI to access your application (default `''`)
- **`environment-variables`** (*list*) — inject environment variables 🌈
- **`key`** (*'str'*) — environment variable key (default `''`)
- **`value`** (*'str'*) — environment variable value (default `''`)
- **`services-names`** (*list*) — name of service instances
- **`name`** (*'str'*) — name of the service instance (default `''`)
---
**Minimal example:**
publishers:
- cloudfoundry: target: https://api.stackato-rkw2.local organization: AS space: SimpleSpace credentials-id: j89jk213
**Full example:**
publishers:
- cloudfoundry: target: https://api.stackato-rkw2.local organization: AS space: SimpleSpace credentials-id: 123 self-signed: true reset-app: true timeout: 240 create-services:
- name: foo-name type: foo-type plan: plan1 reset-service: true
- name: bar-name type: bar-type plan: plan2 reset-service: false value: jenkinsConfig manifest-file: manifest.yml app-name: cloudfoundry memory: 1024 host-name: cloudfoundry instances: 5 manifest-timeout: 120 no-route: true app-path: foo build-pack: custom-buildpack stack: custom-stack command: start domain: cloudfoundry.domain environment-variables:
- key: key value: value
- key: key2 value: value2 services-names:
- name: service-name
- name: service-name2
---
## 🌸 `cloudformation()`
okay next up, and this one's giving big "set it up before, tear it down after" energy: it creates cloudformation stacks **before** running a build, and optionally deletes them at the end. It requires the **Jenkins AWS Cloudformation Plugin** at `https://plugins.jenkins.io/jenkins-cloudformation-plugin` ✨
### Parameters
- **`create-stacks`** (*list*) — list of stacks to create
**`create-stacks` attributes**
- **arg str `name`** — the name of the stack (**Required**)
- **arg str `description`** — description of the stack (Optional)
- **arg str `recipe`** — the cloudformation recipe file (**Required**)
- **arg list `parameters`** — a list of key/value pairs, will be joined together into a comma separated string (Optional)
- **arg int `timeout`** — number of seconds to wait before giving up creating a stack (default `0`)
- **arg str `access-key`** — the Amazon API Access Key (**Required**)
- **arg str `secret-key`** — the Amazon API Secret Key (**Required**)
- **arg int `sleep`** — number of seconds to wait before continuing to the next step (default `0`)
- **arg array `region`** — 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`
- **`delete-stacks`** (*list*) — list of stacks to delete
**`delete-stacks` attributes**
- **arg list `name`** — the names of the stacks to delete (**Required**)
- **arg str `access-key`** — the Amazon API Access Key (**Required**)
- **arg str `secret-key`** — the Amazon API Secret Key (**Required**)
- **arg bool `prefix`** — if selected the tear down process will look for the stack that Starts with the stack name with the oldest creation date and will delete it. (default `false`)
- **arg array `region`** — 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:**
kay the example's right there, keep scrolling bestie 💅
publishers:
- cloudformation: create-stacks:
- 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 delete-stacks:
- name: "foo" prefix: true region: us-west-2 access-key: "$AWS_ACCESS_KEY" secret-key: "$AWS_SECRET_KEY"
- name: "bar" region: us-west-1 access-key: "$AWS_ACCESS_KEY" secret-key: "$AWS_SECRET_KEY"
- name: "foo" description: "Build the foo stack" recipe: "foo.json" parameters:
---
### 🍀 `cloverphp()`
Okay bestie, this one snatches code coverage reports straight out of PHPUnit 🫶. It needs the Jenkins Clover PHP Plugin, which lives at `<https://plugins.jenkins.io/cloverphp>` — no cap, go get it.
So the way this works: your job definition has to hand PHPUnit the `--coverage-clover` option, pointed at some file living in the workspace (like, say, `clover-coverage.xml`). And then that exact filename has to show up in the `xml-location` field. They gotta match, periodt.
**Parameters**
- **`xml-location`** (*str*) — Path to the coverage XML file that PHPUnit made with `--coverage-clover`. Relative to workspace. **Required**, girl, you can't skip this one. 💅
- **`html`** (*dict*) — When it exists, this says whether the plugin should generate an HTML report. Lowkey important note: PHPUnit already gives you an HTML report through its own `--cover-html` option, and you can just set that in your builder instead. (optional)
- **`dir`** (*str*): Directory where the HTML report will be generated, relative to workspace. (**required in html dict**).
- **`archive`** (*bool*): Whether to archive the HTML reports (default `true`).
- **`metric-targets`** (*list*) — A whole list of metric targets you wanna reach. Each one has to be one of `healthy`, `unhealthy` and `failing`. Every metric target can take two parameters:
- `method` — Target for method coverage
- `statement` — Target for statements coverage
And here's a cute little detail: whenever a metric target is left empty, the Jenkins plugin can just fill in the defaults for you. As of v0.3.3 of the plugin, the `healthy` target gets `method: 70` and `statement: 80` if both are left empty. Jenkins Job Builder mimics that feature on purpose, so the configuration diff stays clean. Queen behavior honestly. 👑
**Minimal example:**
Test for the defaults, only xml-location is required
publishers:
- cloverphp: xml-location: 'build/clover.xml'
**Full example:**
Exercise all options with non defaults values
publishers:
- cloverphp: xml-location: 'build/clover.xml' html: dir: 'html' archive: false metric-targets:
- healthy: method: 80 statement: 90
- unhealthy: method: 40 statement: 50
- failing: method: 10 statement: 20
---
### 📊 `cobertura()`
Generate a cobertura coverage report, bestie ✨. This one needs the Jenkins Cobertura Coverage Plugin: `<https://plugins.jenkins.io/cobertura>`.
**Parameters**
- **`report-file`** (*str*) — This is a file name pattern, and you use it to locate the cobertura xml report files (optional).
- **`only-stable`** (*bool*) — Include only stable builds (default `false`).
- **`fail-no-reports`** (*bool*) — Fail builds if no coverage reports are found (default `false`).
- **`fail-unhealthy`** (*bool*) — Unhealthy projects will be failed (default `false`).
- **`fail-unstable`** (*bool*) — Unstable projects will be failed (default `false`).
- **`health-auto-update`** (*bool*) — Auto update threshold for health on a successful build (default `false`).
- **`stability-auto-update`** (*bool*) — Auto update threshold for stability on a successful build (default `false`).
- **`zoom-coverage-chart`** (*bool*) — Zoom the coverage chart and crop the area below the minimum and above the maximum coverage of the past reports (default `false`).
- **`source-encoding`** (*str*) — Override the source encoding (default `ASCII`).
- **`targets`** (*dict*) — `.INDENT 2.0`
`targets` (which can be `packages`, `files`, `classes`, `method`, `line`, `conditional`)
- **`healthy`** (*int*): Healthy threshold (default `0`)
- **`unhealthy`** (*int*): Unhealthy threshold (default `0`)
- **`failing`** (*int*): Failing threshold (default `0`)
**Example:**
publishers:
- cobertura: report-file: "/reports/cobertura/coverage.xml" only-stable: "true" fail-no-reports: "true" fail-unhealthy: "true" fail-unstable: "true" health-auto-update: "true" stability-auto-update: "true" zoom-coverage-chart: "true" source-encoding: "Big5" targets:
- files: healthy: 10 unhealthy: 20 failing: 30
- method: healthy: 50 unhealthy: 40 failing: 30
---
### 📈 `codecover()`
This plugin lets you capture a code coverage report from CodeCover, and Jenkins will generate the trend report of coverage for you 🌈. It needs the Jenkins CodeCover Plugin: `<https://plugins.jenkins.io/codecover>`.
**Parameters**
- **`include`** (*str*) — Specify the path to the CodeCover HTML report file, relative to the workspace root (default `''`).
- **`min-statement`** (*int*) — Minimum statement threshold (default `0`).
- **`max-statement`** (*int*) — Maximum statement threshold (default `90`).
- **`min-branch`** (*int*) — Minimum branch threshold (default `0`).
- **`max-branch`** (*int*) — Maximum branch threshold (default `80`).
- **`min-loop`** (*int*) — Minimum loop threshold (default `0`).
- **`max-loop`** (*int*) — Maximum loop threshold (default `50`).
- **`min-condition`** (*int*) — Minimum condition threshold (default `0`).
- **`max-condition`** (*int*) — Maximum condition threshold (default `50`).
**Minimal Example:**
publishers:
- codecover
**Full Example:**
publishers:
- codecover: include: ./path/report.html min-statement: 1 max-statement: 100 min-branch: 2 max-branch: 90 min-loop: 3 max-loop: 80 min-condition: 4 max-condition: 70
---
### 🎀 `conditional-publisher()`
Conditionally execute some post-build steps, bestie — it's giving "only do the thing if the vibe is right" 💅. It needs the Jenkins Flexible Publish Plugin: `<https://plugins.jenkins.io/flexible-publish>`.
A Flexible Publish list of Conditional Actions gets created in Jenkins. Slay.
**Parameters**
- **`condition-kind`** (*str*) — The condition kind that has to be verified *before* the action is executed. The valid values and their extra attributes are described in the conditions table.
- **`condition-aggregation`** (*bool*) — If `true`, Matrix Aggregation will be enabled. (default `false`)
- **`condition-aggregation-kind`** (*str*) — The Condition Aggregation kind that has to be verified before the action is executed. The valid values and their extra attributes are described in the conditions table.
- **`on-evaluation-failure`** (*str*) — What the outcome of the build should be if the evaluation of the condition fails. Possible values are `fail`, `mark-unstable`, `run-and-mark-unstable`, `run` and `dont-run`. Default is `fail`.
> heads up babe: if you don't say anything about `on-evaluation-failure`, it defaults to `fail` — so a busted condition will tank your build by default. 😭
- **`action`** (list) — the action to run when the condition checks out. Each item can be <pink>any publisher</pink> that Jenkins Job Builder knows about and that the Flexible Publish Plugin supports. 💖
So like, the *condition kind* is the whole vibe check, and here's the tea on every single one:
- **`always`** — condition is <green>always</green> verified. Yes queen, always. ✨
- **`never`** — condition is <red>never</red> verified. Not today, bestie. 💀
- **`boolean-expression`** — the action runs if the expression expands to a representation of `true`
- **`condition-expression`** — the expression to expand 🌸
- **`current-status`** — run the action if the current build status is within the configured range
- **`condition-worst`** — accepted values are `SUCCESS`, `UNSTABLE`, `FAILURE`, `NOT_BUILD`, `ABORTED`
- **`condition-best`** — accepted values are `SUCCESS`, `UNSTABLE`, `FAILURE`, `NOT_BUILD`, `ABORTED`
- **`shell`** — run the action if the shell command succeeds
- **`condition-command`** — shell command to execute 🧚
- **`windows-shell`** — same energy as `shell`, except the commands get executed by `cmd`, on Windows
- **`condition-command`** — command to execute
- **`regexp`** — run the action if a regular expression matches
- **`condition-expression`** — regular expression
- **`condition-searchtext`** — text to match against the regular expression 🦋
- **`file-exists`** — run the action if a file exists
- **`condition-filename`** — check existence of this file
- **`condition-basedir`** — if `condition-filename` is relative, it will be considered relative to either `workspace`, `artifact-directory`, or `jenkins-home`. Default is `workspace`. 💅
---
### ✨ Single Conditional Action Example:
publishers:
- conditional-publisher:
- condition-kind: current-status condition-worst: FAILURE condition-best: SUCCESS action:
- archive: artifacts: '/' allow-empty: 'true'
- condition-kind: current-status condition-worst: FAILURE condition-best: SUCCESS action:
### 🌈 Multiple Conditional Actions Example
(includes an example of multiple actions per condition, which requires <yellow>v0.13 or higher</yellow> of the Flexible Publish plugin, jsyk):
publishers:
- conditional-publisher:
- condition-kind: always on-evaluation-failure: run-and-mark-unstable action:
- archive: artifacts: '/' allow-empty: 'true'
- aggregate-tests: include-failed-builds: true
- condition-kind: always on-evaluation-failure: run-and-mark-unstable action:
### Multiple Conditional Actions Example for pre-v0.13 versions
---
### <purple>copy-to-master()</purple>
Copy files to master from slave. 🫶
Requires the Jenkins Copy To Slave Plugin <https://plugins.jenkins.io/copy-to-slave>.
**Parameters**
- **`includes`** (list) — list of file patterns to copy
- **`excludes`** (list) — list of file patterns to exclude
- **`destination`** (str) — absolute path into which the files will be copied. If left blank they will be copied into the workspace of the current job (default `''`)
- **`run-after-result`** (bool) — if this is checked then copying files back to master will not run until the build result is finalized. (default `true`)
**Example:**
publishers:
- copy-to-master: includes:
- file1
- file2*.txt excludes:
- file2bad.txt
---
### <purple>coverage()</purple>
> ⚠️ **WARNING:** The `coverage` function is <red>deprecated</red>. Instead, use the `cobertura` function to generate a cobertura coverage report. Not me being dramatic, it's literally in the docs bestie. 😭
Requires the Jenkins Cobertura Coverage Plugin <https://plugins.jenkins.io/cobertura>.
**Example:**
publishers:
- coverage
### 🦋 `cppcheck()`
ngl bestie, this one is your <pink>Cppcheck result publisher</pink> 🎀 It needs the Jenkins Cppcheck Plugin (`<https://plugins.jenkins.io/cppcheck>`) to actually do its thing, so go get that first, fr fr.
**Parameters** 💅
- **`pattern`** (*str*) — the file pattern for the cppcheck xml report (<red>required</red>, so like… you HAVE to give it)
- **`ignoreblankfiles`** (*bool*) — ignore blank files (default `false`)
- **`allow-no-report`** (*bool*) — do **not** fail the build if the Cppcheck report isn't found (default `false`)
- **`thresholds`** (*dict*) — this is the vibe-check for your build's status and health ✨ A build gets marked unstable or failure if the new or total number of issues goes over the thresholds you set. Build health is also determined by these thresholds, and if the actual number of issues lands *between* your provided thresholds, the build health is interpolated. Cute, right?
- **`unstable`** (*str*): total number unstable threshold (default `''`)
- **`new-unstable`** (*str*): new number unstable threshold (default `''`)
- **`failure`** (*str*): total number failure threshold (default `''`)
- **`new-failure`** (*str*): new number failure threshold (default `''`)
- **`healthy`** (*str*): healthy threshold (default `''`)
- **`unhealthy`** (*str*): unhealthy threshold (default `''`)
- **`severity`** (*dict*) — decides which severity of issues count when the build status and health get evaluated, and it defaults to everything being `true` 👑
- **`error`** (*bool*): severity error (default `true`)
- **`warning`** (*bool*): severity warning (default `true`)
- **`style`** (*bool*): severity style (default `true`)
- **`performance`** (*bool*): severity performance (default `true`)
- **`information`** (*bool*): severity information (default `true`)
- **`nocategory`** (*bool*): severity nocategory (default `true`)
- **`portability`** (*bool*): severity portability (default `true`)
- **`graph`** (*dict*) — graph configuration, obviously 📊
- **`xysize`** (*array*): chart width and height (default `[500, 200]`)
- **`num-builds-in-graph`** (*int*): builds number in graph (default `0`)
- **`:arg dict display`** — which errors to display, defaults to only sum
- **`sum`** (*bool*): display sum of all issues (default `true`)
- **`error`** (*bool*): display errors (default `false`)
- **`warning`** (*bool*): display warnings (default `false`)
- **`style`** (*bool*): display style (default `false`)
- **`performance`** (*bool*): display performance (default `false`)
- **`information`** (*bool*): display information (default `false`)
- **`nocategory`** (*bool*): display no category (default `false`)
- **`portability`** (*bool*): display portability (default `false`)
**Minimal Example:** — the bare minimum, lowkey perfect 🫶
publishers:
- cppcheck: pattern: "**/cppcheck.xml"
**Full Example:** — okay go off, main character energy 🌈
publishers:
- cppcheck: pattern: "**/cppcheck.xml" # the rest is optional ignoreblankfiles: true allow-no-report: true # build status (new) error count thresholds thresholds: unstable: 5 new-unstable: 5 failure: 7 new-failure: 3 healthy: 5 unhealthy: 10 # severities which count towards the threshold, default all true severity: error: false warning: false style: false performance: false information: false nocategory: false portability: false graph: xysize: [600, 300] num-builds-in-graph: 10 # which errors to display, default only sum display: sum: false error: true warning: true style: true performance: true information: true nocategory: true portability: true
---
### 🥒 `cucumber-reports()`
This plugin creates pretty cucumber-jvm html reports on jenkins 💖 It requires the Jenkins cucumber reports plugin (`<https://plugins.jenkins.io/cucumber-reports>`). Look at those pretty reports, iconic.
**Parameters** ✨
- **`json-reports-path`** (*str*) — the path relative to the workspace of the json reports generated by cucumber-jvm, e.g. `target`. Leave it empty and it'll scan the whole workspace, which is giving "feral but effective" (default `''`)
- **`file-include-pattern`** (*str*) — include pattern (default `''`)
- **`file-exclude-pattern`** (*str*) — exclude pattern (default `''`)
- **`plugin-url-path`** (*str*) — the path to the jenkins user content url, e.g. `http://host:port[/jenkins/]plugin`. Leave it empty if the jenkins url root is `host:port` (default `''`)
- **`skipped-fails`** (*bool*) — skipped steps cause the build to fail (default `false`)
- **`pending-fails`** (*bool*) — pending steps cause the build to fail (default `false`)
- **`undefined-fails`** (*bool*) — undefined steps cause the build to fail (default `false`)
- **`missing-fails`** (*bool*) — missing steps cause the build to fail (default `false`)
- **`no-flash-charts`** (*bool*) — use javascript charts instead of flash charts (default `false`) — bestie it is NOT 2009, javascript is the move 💀
- **`ignore-failed-tests`** (*bool*) — entire build to fail when these tests fail (default `false`)
- **`parallel-testing`** (*bool*) — run same test in parallel for multiple devices (default `false`)
- **`failed-steps-number`** (*int*) — maximum number of failed steps above which the build result is changed (default `0`)
- **`skipped-steps-number`** (*int*) — maximum number of skipped steps above which the build result is changed (default `0`)
- **`pending-steps-number`** (*int*) — maximum number of pending steps above which the build result is changed (default `0`)
- **`undefined-steps-number`** (*int*) — maximum number of undefined steps above which the build result is changed (default `0`)
- **`failed-scenarios-number`** (*int*) — maximum number of failed scenarios above which the build result is changed (default `0`)
- **`failed-features-number`** (*int*) — maximum number of failed features above which the build result is changed (default `0`)
- **`build-status`** (*list*) — build result to which the build should be set when the report becomes failed or unstable (default `''`)
- **`trends-limit`** (*int*) — number of past reports that should be presented. Zero means unlimited number of builds 👀 (default `0`)
- **`sorting-method`** (*list*) — result sorting order (default `'NATURAL'`)
**Full example:** 🌸
publishers:
- cucumber-reports: json-reports-path: path plugin-url-path: http://example.com/ file-include-pattern: '*/.json' file-exclude-pattern: badfile.txt skipped-fails: true pending-fails: true undefined-fails: true missing-fails: true no-flash-charts: true ignore-failed-tests: true parallel-testing: true failed-steps-number: 1 skipped-steps-number: 2 pending-steps-number: 3 undefined-steps-number: 4 failed-scenarios-number: 5 failed-features-number: 6 build-status: UNSTABLE trends-limit: 7 sorting-method: ALPHABETICAL sorting-values:
- key-value-pair: key: classification key 1 value: classification value 1
- key-value-pair: key: classification key 2 value: classification value 2
**Minimal Example:** — yes bestie, it really is this short 💅
publishers:
- cucumber-reports
---
### 🧚 `cucumber-testresult()`
Publishes cucumber test results 🎀 It requires the Jenkins Cucumber testresult plugin (`<https://plugins.jenkins.io/cucumber-testresult-plugin>`).
**Parameters** ⭐
- **`results`** (*str*) — results filename (<red>required</red>, don't skip it)
- **`ignore-bad-steps`** (*bool*) — ignore not existed step results (default `false`)
**Minimal example:** 🦋
publishers:
- cucumber-testresult: results: nosetests.xml
**Full Example:** 💜
publishers:
- cucumber-testresult: results: nosetests.xml ignore-bad-steps: true
---
### 🔍 `dependency-check()`
Dependency-Check is an open source utility that identifies project dependencies and checks if there are any known, publicly disclosed, vulnerabilities 👑 periodt, that's the whole point of it.
It requires the Jenkins OWASP Dependency-Check Plugin (`<https://plugins.jenkins.io/dependency-check-jenkins-plugin>`).
**Parameters** 🌟
- **`pattern`** (*str*) — report filename pattern (optional)
- **`can-run-on-failed`** (*bool*) — also runs for failed builds, instead of just stable or unstable builds (default `false`)
- **`should-detect-modules`** (*bool*) — determines if Ant or Maven modules should be detected for all files that contain warnings (default `false`)
- **`healthy`** (*int*) — Sunny threshold (optional)
- **`unhealthy`** (*int*) — Stormy threshold (optional)
- **`health-threshold`** (*str*) — the priority threshold for health status, and your options are `'low'`, `'normal'` or `'high'`, defaulting to `'low'` 🩺
- **`thresholds`** (*dict*) — mark the build as failed or unstable if the number of errors exceeds a threshold. it's optional bestie, you don't *have* to 💅
- **`unstable`** (*dict*) — the "we're fine but we're not FINE" tier 😭
- **`total-all`** (*int*)
- **`total-high`** (*int*)
- **`total-normal`** (*int*)
- **`total-low`** (*int*)
- **`new-all`** (*int*)
- **`new-high`** (*int*)
- **`new-normal`** (*int*)
- **`new-low`** (*int*)
- **`failed`** (*dict*) — the "we are SO done" tier 💀
- **`total-all`** (*int*)
- **`total-high`** (*int*)
- **`total-normal`** (*int*)
- **`total-low`** (*int*)
- **`new-all`** (*int*)
- **`new-high`** (*int*)
- **`new-normal`** (*int*)
- **`new-low`** (*int*)
- **`default-encoding`** (*str*) — the encoding used for parsing or showing files. optional 💖
- **`do-not-resolve-relative-paths`** (*bool*) — defaults to `false`
- **`dont-compute-new`** (*bool*) — if you set this to `false`, it computes new warnings based on the reference build. defaults to `true` ✨
- **`use-previous-build-as-reference`** (*bool*) — decides whether to *always* use the previous build as the reference build. defaults to `false` 🦋
- **`use-stable-build-as-reference`** (*bool*) — the number of new warnings gets calculated based on the last stable build, which lets you revert unstable builds where the number of warnings was decreased. defaults to `false` 🌸
- **`use-delta-values`** (*bool*) — if it's set, the number of new warnings is calculated by subtracting the total number of warnings of the current build from the reference build. defaults to `false` 🔥
**Minimal Example:**
publishers:
- dependency-check
**Full Example:**
publishers:
- dependency-check: pattern: '**/dependency-check-report.xml' can-run-on-failed: true should-detect-modules: true healthy: 0 unhealthy: 100 health-threshold: 'high' thresholds: unstable: total-all: 90 total-high: 80 total-normal: 70 total-low: 60 new-all: 50 new-high: 40 new-normal: 30 new-low: 20 failed: total-all: 91 total-high: 81 total-normal: 71 total-low: 61 new-all: 51 new-high: 41 new-normal: 31 new-low: 21 default-encoding: 'utf-8' do-not-resolve-relative-paths: true dont-compute-new: false use-previous-build-as-reference: true use-stable-build-as-reference: true use-delta-values: true
---
### 💬 `description-setter()`
This plugin sets the description for each build, based on a RegEx test of the build log file. icon behavior, honestly 👑
Requires the Jenkins Description Setter Plugin `https://plugins.jenkins.io/description-setter`.
**Parameters**
- **`regexp`** (*str*) — a RegEx used to scan the build log file. defaults to `''` 🔍
- **`regexp-for-failed`** (*str*) — a RegEx used for failed builds. defaults to `''` 💀
- **`description`** (*str*) — the description to set on the build. optional ✨
- **`description-for-failed`** (*str*) — the description to set on the failed builds. optional 😭
- **`set-for-matrix`** (*bool*) — also set the description on a multi-configuration build. defaults to `false` 🎀
**Minimal Example:**
publishers:
- description-setter
**Full Example:**
publishers:
- description-setter: regexp: ".(<a href=.a>)" regexp-for-failed: ".*(<a href=.*a>)" description: "some description" description-for-failed: "another description" set-for-matrix: true
---
### 🚫 `disable-failed-job()`
Automatically disables failed jobs. it's giving "you're on timeout, bestie" 🙈
Requires the Jenkins Disable Failed Job Plugin `https://plugins.jenkins.io/disable-failed-job`.
**Parameters**
- **`when-to-disable`** (*str*) — the condition to disable the job. **required** ⚠️ Possible values are:
- `Only Failure`
- `Failure and Unstable`
- `Unstable`
- **`no-of-failures`** (*int*) — the number of consecutive failures needed to disable the job. optional 💅
**Example:**
publishers:
- disable-failed-job: when-to-disable: 'Failure and Unstable' no-of-failures: 3
---
### 🎮 `discord-notifier()`
This plugin lets a job publish results to discord. Requires the Jenkins `https://plugins.jenkins.io/discord-notifier`.
**Parameters**
- `webhook-url` (*str*) — Discord webhook URL ( **required** ) 🔗
**Minimal Example:**
publishers:
- discord-notifier: webhook-url: "https://discord.com/api/webhooks/token"
**Full Example:**
publishers:
- discord-notifier: webhook-url: "https://discord.com/api/webhooks/token" branch-name: "branchName" status-title: "statusTitle" thumbnail-url: "thumbnailURL" notes: "notes" custom-avatar-url: "customAvatarUrl" custom-username: "customUsername" send-on-state-change: true enable-url-linking: true enable-artifact-list: true enable-footer-info: true show-changeset: true send-log-file: true send-start-notification: true
---
### 🔭 `display-upstream-changes()`
Display SCM changes of upstream jobs. Requires the Jenkins Display Upstream Changes Plugin `https://plugins.jenkins.io/display-upstream-changes`.
**Example:**
publishers:
- display-upstream-changes
---
### 🐳 `docker-stop-container()`
This plugin lets you remove stopped docker containers. It requires the Docker build step plugin `https://plugins.jenkins.io/docker-build-step`. bye bye lil containers 🫶
**Parameters**
- `remove-stopped-containers` (*bool*) — a boolean value to remove stopped docker containers. defaults to `False`
**Minimal Example:** `.. literalinclude:: /../../tests/publishers/fixtures/docker-stop-container-minimal.yaml`
**Full Example:** `.. literalinclude:: /../../tests/publishers/fixtures/docker-stop-container-full.yaml`
---
### 🌊 `downstream-ext()`
Trigger multiple downstream jobs when a job is completed and the condition is met. chain reaction energy fr fr 🔥
Requires the Jenkins Downstream-Ext Plugin `https://plugins.jenkins.io/downstream-ext`.
**Parameters**
- **`projects`** (*list*) — projects to build. **required** 🛠️
- **`condition`** (*str*) — the comparison condition used for the criteria. one of `'equal-or-over'`, `'equal-or-under'`, `'equal'`. defaults to `'equal-or-over'`
- **`criteria`** (*str*) — trigger the downstream job if the build results meet the condition. one of `'success'`, `'unstable'`, `'failure'` or `'aborted'`. defaults to `'success'` ✅
- **`only-on-scm-change`** (*bool*) — trigger only if the downstream project has SCM changes. defaults to `false`
- **`only-on-local-scm-change`** (*bool*) — trigger only if the current project has SCM changes. defaults to `false`
**Example:**
publishers:
- downstream-ext: projects:
- foo
- bar only-on-scm-change: true criteria: unstable condition: equal
---
### 📚 `doxygen()`
This plugin parses the Doxygen descriptor (Doxyfile) and provides a link to the generated Doxygen documentation. so academic of it 🌈
Requires the Jenkins Doxygen Plugin `https://plugins.jenkins.io/doxygen`.
**Parameters**
- **`doxyfile`** (*str*) — the doxyfile path. **required** 📄
- **`slave`** (*str*) — the node or label to pull the doxygen HTML files from. defaults to `''`
- **`keep-all`** (*bool*) — retain doxygen generation for each successful build. defaults to `false` 💖
- **`folder`** (*str*) — folder where you run doxygen. defaults to `''`
**Minimal Example:**
publishers:
- doxygen: doxyfile: "Doxyfile"
**Full Example:**
publishers:
- doxygen: doxyfile: "Doxyfile" slave: "doxygen-slave" keep-all: true folder: "build"
---
### 🧺 `dry()`
Publish trend reports with DRY. keep it DRY bestie, no repeats 💅
Requires the Jenkins DRY Plugin (`https://github.com/jenkinsci/dry-plugin`).
The DRY component accepts a dictionary with the following values:
**Parameters**
- **`pattern`** (*str*) — report filename pattern. defaults to `''` 🔎
- **`can-run-on-failed`** (bool) — <pink>also runs for failed builds</pink> instead of just stable or unstable ones. Default: `false` 💅
- **`should-detect-modules`** (bool) — says whether Ant or Maven modules should get detected for every file that has warnings. Default: `false` ✨
- **`healthy`** (int) — the sunny ☀️ threshold. Default: `''`
- **`unhealthy`** (int) — the stormy ⛈️ threshold. Default: `''`
- **`health-threshold`** (str) — which threshold takes priority for the health status: `'low'`, `'normal'` or `'high'`. Defaults to `'low'` 🫶
- **`high-threshold`** (int) — minimum number of duplicated lines before a warning counts as high priority. Default: `50` 🔥
- **`normal-threshold`** (int) — minimum number of duplicated lines before a warning counts as normal priority. Default: `25` 🌸
- **`thresholds`** (dict) — marks the build as failed or unstable if the number of errors blows past a threshold. Default: `''` 💀
These are the thresholds, bestie:
- **`unstable`** (dict) — the unstable ones 👑
- **`total-all`** (int)
- **`total-high`** (int)
- **`total-normal`** (int)
- **`total-low`** (int)
- **`new-all`** (int)
- **`new-high`** (int)
- **`new-normal`** (int)
- **`new-low`** (int)
- **`failed`** (dict) — the failed ones 😭
- **`total-all`** (int)
- **`total-high`** (int)
- **`total-normal`** (int)
- **`total-low`** (int)
- **`new-all`** (int)
- **`new-high`** (int)
- **`new-normal`** (int)
- **`new-low`** (int)
- **`default-encoding`** (str) — the encoding used for parsing or showing files (optional) 🎀
- **`do-not-resolve-relative-paths`** (bool) — Default: `false`
- **`dont-compute-new`** (bool) — if you set it to `false`, it computes new warnings based on the reference build. Default: `true` ⭐
- **`use-previous-build-as-reference`** (bool) — decides whether the previous build is <italic>always</italic> the reference build. Default: `false`
- **`use-stable-build-as-reference`** (bool) — the number of new warnings gets calculated from the last stable build, which lets you revert unstable builds where the warning count went down 💖. Default: `false`
- **`use-delta-values`** (bool) — if this is set, the number of new warnings is calculated by subtracting the total number of warnings of the current build from the reference build. Default: `false`
**Example:** ✨
publishers:
- dry: pattern: '**/cpd-result.xml' healthy: 0 unhealthy: 100 health-threshold: 'high' high-threshold: 50 normal-threshold: 25 thresholds: unstable: total-high: 10 failed: total-high: 1
**Full example:** 💅
publishers:
- dry: pattern: '**/cpd-result.xml' can-run-on-failed: true should-detect-modules: true healthy: 0 unhealthy: 100 health-threshold: 'high' high-threshold: 20 normal-threshold: 10 thresholds: unstable: total-all: 90 total-high: 80 total-normal: 70 total-low: 60 new-all: 50 new-high: 40 new-normal: 30 new-low: 20 failed: total-all: 91 total-high: 81 total-normal: 71 total-low: 61 new-all: 51 new-high: 41 new-normal: 31 new-low: 21 default-encoding: 'utf-8' do-not-resolve-relative-paths: true dont-compute-new: false use-stable-build-as-reference: true use-delta-values: true
---
### `email()`
<green>Email notifications on build failure.</green> This one needs the Jenkins Mailer Plugin, which lives at `https://plugins.jenkins.io/mailer` 📧
**Parameters** 🫶
- **`recipients`** (str) — a space-separated list of recipient email addresses. <red>Required, bestie — you can't skip it.</red>
- **`notify-every-unstable-build`** (bool) — send an email for <italic>every</italic> unstable build. Default: `true`
- **`send-to-individuals`** (bool) — send an email to the individual who broke the build 😭. Default: `false`
**Example:** 🌸
publishers:
- email: recipients: foo@example.com
publishers:
- email: recipients: foo@example.com bar@example.com notify-every-unstable-build: false send-to-individuals: true
---
### `email-ext()`
<rainbow>Extends Jenkins' built-in email notification!</rainbow> Needs the Jenkins Email-ext Plugin, over at `https://plugins.jenkins.io/email-ext` ✨
**Parameters** 💜
- **`disable-publisher`** (bool) — disables the publisher while keeping all the settings intact. The whole point of this one is when you wanna test stuff out in the build without actually sending emails during testing. A message gets printed to the build log saying the publisher is disabled 💀. Default: `false`
- **`recipients`** (str) — comma-separated list of recipient email addresses. Default: `'$DEFAULT_RECIPIENTS'`
- **`reply-to`** (str) — comma-separated list of email addresses that should go in the Reply-To header for this project. Default: `'$DEFAULT_REPLYTO'`
- **`from`** (str) — the email address that goes in the From header for this project. Default: `''`
- **`content-type`** (str) — the content type of the emails being sent. If you don't set it, the Jenkins plugin uses whatever value is set on the main configuration page. Possible values: `'html'`, `'text'`, `'both-html-text'` or `'default'`. Default: `'default'`
- **`subject`** (str) — the subject for the email. Can include variables like `${BUILD_NUMBER}`, or honestly even groovy or javascript code 👀. Default: `'$DEFAULT_SUBJECT'`
- **`body`** (str) — the content for the body of the email. Can include variables like `${BUILD_NUMBER}`, but the <italic>real</italic> magic is using groovy or javascript to hook straight into the Jenkins API itself 🔥. Default: `'$DEFAULT_CONTENT'`
- **`attach-build-log`** (bool) — include the build log in the email. Default: `false`
- **`compress-log`** (bool) — compress the build log in the email. Default: `false`
- **`attachments`** (str) — pattern of files to include as an attachment. Default: `''`
- **`always`** (bool) — send an email for every result. Default: `false`
- **`unstable`** (bool) — send an email for an unstable result. Default: `false`
- **`first-failure`** (bool) — send an email for just the first failure. Default: `false`
- **`first-unstable`** (bool) — send an email for just the first unstable build. Default: `false`
- **`not-built`** (bool) — send an email if the build wasn't built. Default: `false`
- **`aborted`** (bool) — send an email if the build gets aborted. Default: `false`
- **`regression`** (bool) — send an email if there's a regression. Default: `false`
- **`failure`** (bool) — send an email if the build fails. Default: `true`
- **`second-failure`** (bool) — send an email for the second failure. Default: `false`
- **`improvement`** (bool) — send an email if the build improves 🦋. Default: `false`
- **`still-failing`** (bool) — send an email if the build is still failing. Default: `false`
- **`success`** (bool) — send an email for a successful build 🎀. Default: `false`
- **`fixed`** (bool) — send an email if the build is fixed. Default: `false`
- **`fixed-unhealthy`** (bool) — send an email if the build status changes from "Failure" or "Unstable" to "Success". Intermediate "Aborted" builds are ignored 👑. Default: `false`
- **`still-unstable`** (bool) — send an email if the build is still unstable. Default: `false`
- **`pre-build`** (bool) — send an email <italic>before</italic> the build. Default: `false`
- **`trigger-script`** (str) — a Groovy script used to determine whether an email should be sent 📜
- **`presend-script`** (str) — a Groovy script executed prior to sending the mail. Default: `''`
- **`postsend-script`** (str) — a Groovy script executed after sending the email. Default: `''`
- **`save-output`** (bool) — save email content to the workspace. Default: `false`
- **`matrix-trigger`** (str) — if you're using matrix projects, this is when to trigger ⏰
These are the **matrix-trigger values**:
- `both`
- `only-parent`
- `only-configurations` 💅 — literally the only vibe allowed, bestie
- **`send-to`** (list) — the guest list for who actually gets this email 💌 it's a list of recipients pulled from the predefined groups
**`send-to` values** (the whole roster, pick ur faves)
- `developers` — <pink>disabled by default</pink> 🙈
- `requester` — <pink>disabled by default</pink> 🙈
- `culprits` — <pink>disabled by default</pink> (yeah, the ones who broke it 💀)
- `recipients` — <mint>enabled by default</mint> ✅ queen behavior
- `upstream-committers` (`>=2.39`) — <pink>disabled by default</pink>
- `failing-test-suspects-recipients` (`>=2.39`) — <pink>disabled by default</pink>
- `first-failing-build-suspects-recipients` (`>=2.39`) — <pink>disabled by default</pink>
**Example:**
publishers:
- email-ext: recipients: foo@example.com, bar@example.com reply-to: foo@example.com content-type: html subject: Subject for Build ${BUILD_NUMBER} body: The build has finished attach-build-log: false compress-log: false attachments: "/foo.log" always: true unstable: true first-failure: true first-unstable: true not-built: true aborted: true regression: true failure: true second-failure: true improvement: true still-failing: true success: true fixed: true fixed-unhealthy: true still-unstable: true pre-build: true matrix-trigger: only-configurations presend-script: "cancel=true" postsend-script: "cancel=true" save-output: true send-to:
- developers
- requester
- culprits
- recipients
- upstream-committers
---
## 🎭 `emotional-jenkins()`
Emotional Jenkins, bestie. This funny plugin changes the expression of Mr. Jenkins in the background when your builds fail. 😭 it's giving ✨drama✨ and honestly? relatable.
Requires the Jenkins Emotional Jenkins Plugin <https://plugins.jenkins.io/emotional-jenkins-plugin>.
**Example:**
publishers:
- emotional-jenkins
---
## 🐛 `findbugs()`
FindBugs reporting for builds 🐞
Requires the Jenkins FindBugs Plugin (<https://github.com/jenkinsci/findbugs-plugin>).
**Parameters**
- **`pattern`** (*str*) — specifies the generated raw FindBugs XML report files, such as `**/findbugs.xml` or `**/findbugsXml.xml`. (default `''`)
- **`rank-priority`** (*bool*) — Use rank as priority (default `false`)
- **`include-files`** (*str*) — Comma separated list of files to include. (default `''`)
- **`exclude-files`** (*str*) — Comma separated list of files to exclude. (default `''`)
- **`can-run-on-failed`** (*bool*) — Weather or not to run plug-in on failed builds (default `false`)
- **`should-detect-modules`** (*bool*) — Determines if Ant or Maven modules should be detected for all files that contain warnings. (default `false`)
- **`healthy`** (*int*) — Sunny threshold (default `''`) ☀️
- **`unhealthy`** (*int*) — Stormy threshold (default `''`) ⛈️
- **`health-threshold`** (*str*) — Threshold priority for health status (`'low'`, `'normal'` or `'high'`, defaulted to `'low'`)
- **`dont-compute-new`** (*bool*) — If set to `false`, computes new warnings based on the reference build (default `true`)
- **`use-delta-values`** (*bool*) — Use delta for new warnings. (default `false`)
- **`use-previous-build-as-reference`** (*bool*) — If set then the number of new warnings will always be calculated based on the previous build. Otherwise the reference build. (default `false`)
- **`use-stable-build-as-reference`** (*bool*) — The number of new warnings will be calculated based on the last stable build, allowing reverts of unstable builds where the number of warnings was decreased. (default `false`)
- **`thresholds`** (*dict*) — 👇
**`thresholds`**
- `unstable` (*dict*)
**`unstable`**
- `total-all` (*int*)
- `total-high` (*int*)
- `total-normal` (*int*)
- `total-low` (*int*)
- `new-all` (*int*)
- `new-high` (*int*)
- `new-normal` (*int*)
- `new-low` (*int*)
- `failed` (*dict*)
**`failed`**
- `total-all` (*int*)
- `total-high` (*int*)
- `total-normal` (*int*)
- `total-low` (*int*)
- `new-all` (*int*)
- `new-high` (*int*)
- `new-normal` (*int*)
- `new-low` (*int*)
**Minimal Example:**
publishers:
- findbugs
**Full Example:**
publishers:
- findbugs: pattern: '*/findbugs.xml' rank-priority: true include-files: 'f,d,e,.' exclude-files: 'a,c,d,.*' can-run-on-failed: true should-detect-modules: true healthy: 80 unhealthy: 10 use-delta-values: true health-threshold: 'high' thresholds: unstable: total-all: 90 total-high: 80 total-normal: 50 total-low: 20 new-all: 95 new-high: 85 new-normal: 55 new-low: 25 failed: total-all: 80 total-high: 70 total-normal: 40 total-low: 10 new-all: 85 new-high: 75 new-normal: 45 new-low: 15 dont-compute-new: false use-delta-values: true use-previous-build-as-reference: true use-stable-build-as-reference: true
---
## `fingerprint()`
Fingerprint files to track them across builds. 🔍 Requires the Jenkins Fingerprint Plugin <https://plugins.jenkins.io/create-fingerprint>.
**Parameters**
- **`files`** (*str*) — files to fingerprint, follows the `@includes` of Ant fileset (default `''`)
- **`record-artifacts`** (*bool*) — fingerprint all archived artifacts (default `false`)
**Example:**
publishers:
- fingerprint: files: builddir/test*.xml record-artifacts: false
---
## 🏋️ `fitnesse()`
Publish Fitnesse test results 💪
Requires the Jenkins Fitnesse plugin <https://plugins.jenkins.io/fitnesse>.
**Parameters**
- **`results`** (*str*) — path specifier for results files
**Example:**
publishers:
- fitnesse: results: "fitnesse-results/*/.xml"
---
## 🌊 `flowdock()`
This plugin publishes job build results to a Flowdock flow. 💬
Requires the Jenkins Flowdock Plugin <https://plugins.jenkins.io/jenkins-flowdock-plugin>.
**Parameters**
- **`token`** (*str*) — API token for the targeted flow. (**required**)
- **`tags`** (*str*) — Comma-separated list of tags to include in message (default `""`)
- **`chat-notification`** (*bool*) — Send chat notification when build fails (default `true`)
- **`notify-success`** (*bool*) — Send notification on build success (default `true`)
- **`notify-failure`** (*bool*) — Send notification on build failure (default `true`)
- **`notify-fixed`** (*bool*) — Send notification when build is fixed (default `true`)
- **`notify-unstable`** (*bool*) — Send notification when build is unstable (default `false`)
- **`notify-aborted`** (*bool*) — Send notification when build was aborted (default `false`)
- **`notify-notbuilt`** (*bool*) — Send notification when build did not occur (default `false`)
**Example:**
publishers:
- flowdock: token: abcdefghijklmnopqrstuvwxyzabcdef
**Full example:**
publishers:
- flowdock: token: abcdefghijklmnopqrstuvwxyzabcdef tags: jenkins,ci chat-notification: true notify-success: true notify-failure: true notify-fixed: true notify-unstable: false notify-aborted: false notify-notbuilt: false
---
## 📤 `ftp()`
Upload files via FTP. Requires the Jenkins Publish over FTP Plugin <https://plugins.jenkins.io/publish-over-ftp>.
**Parameters**
- **`site`** (*str*) — name of the ftp site (**required**)
- **`target`** (*str*) — destination directory (**required**)
- **`target-is-date-format`** (*bool*) — whether `target` is a date format. If true, raw text should be quoted (default `false`)
- **`clean-remote`** *(bool)* — should we yeet the remote directory before we start transferring files? (default `false`)
- **`source`** *(str)* — the source path specifier (required, bestie, you GOTTA give us this one)
- **`excludes`** *(str)* — file pattern to exclude (optional)
- **`remove-prefix`** *(str)* — prefix to strip off the uploaded file paths (optional)
- **`fail-on-error`** *(bool)* — blow up the build if an error happens (default `false`)
- **`flatten`** *(bool)* — only make files on the server, do NOT make directories (default `false`)
- **`verbose`** *(bool)* — dumps a whole lotta detail that's useful for debug straight to the console, but like, generally you wanna leave it off (default `false`)
- **`retries`** *(int)* — how many times to retry this server if it fails (optional)
- **`retry-delay`** *(int)* — how long to wait, in milliseconds, before trying another transfer (default `10000`)
**Minimal Example:**
publishers:
- ftp: site: 'ftp.example.com' target: 'dest/dir' source: 'base/source/dir/**'
**Full Example:**
publishers:
- ftp: site: 'ftp.example.com' target: "'dest/dir/'yyyyMMddHHmmss" target-is-date-format: true clean-remote: true source: 'base/source/dir/' excludes: '/*.excludedfiletype' remove-prefix: 'base/source/dir' fail-on-error: true flatten: true verbose: true retries: 99 retry-delay: 12345
---
## <pink>ftp-publisher()</p> 🎀
Okay so this plugin? It uploads your project artifacts AND whole entire directories up to an ftp server. So versatile, we love her. 💅
> Needy queen alert: this REQUIRES the Jenkins FTP-Publisher Plugin — <https://plugins.jenkins.io/ftppublisher>.
### <lavender>Parameters</lavender> ✨
- **`uploads`** *(list)* — the list of files to upload, bestie
**uploads**
- `file-path` *(str)* — destination folder. It's gonna get created if it doesn't exist already, no cap. Created relative to the ftp root directory. (default `''`)
- `source-file` *(str)* — source files that will be uploaded (default `''`)
- **`site-name`** *(str)* — name of the FTP server to upload to (required)
- **`use-timestamps`** *(bool)* — use timestamps in the FTP directory path (default `false`)
- **`flatten-files`** *(bool)* — flatten files on the FTP host (default `false`)
- **`skip-publishing`** *(bool)* — skip publishing entirely (default `false`)
**Minimal Example:**
publishers:
- ftp-publisher: site-name: foo
**Full Example:**
publishers:
- ftp-publisher: uploads:
- file-path: destination/folder source-file: folder/dist/*.jar
- file-path: foo/bar source-file: foo/bar/*.ear site-name: foo use-timestamps: true flatten-files: true skip-publishing: true
---
## <cyan>gatling()</cyan> 🦋
Publishes gatling results as a trend graph. It's giving analytics era. 📈
> Requires the Jenkins Gatling Plugin — <https://plugins.jenkins.io/gatling>.
**Example:**
publishers:
- gatling
---
## <mint>git()</mint> 🌿
This plugin configures the Jenkins Git plugin so it pushes merge results, tags, and/or branches to remote repositories once the job finishes. Main character push energy, fr fr. 🔥
Requires the Jenkins Git Plugin — <https://plugins.jenkins.io/git>.
### <lavender>Parameters</lavender> ✨
- **`push-merge`** *(bool)* — push merges back to the origin specified in the pre-build merge options (default `false`)
- **`push-only-if-success`** *(bool)* — only push to remotes if the build succeeds — otherwise, literally nothing gets pushed. (default `true`)
- **`force-push`** *(bool)* — add the force option to `git push` (default `false`)
- **`tags`** *(list)* — tags to push at the completion of the build
**tag**
- `remote` *(str)* — remote repo name to push to (default `'origin'`)
- `name` *(str)* — name of tag to push
- `message` *(str)* — message content of the tag
- `create-tag` *(bool)* — whether or not to create the tag after the build; if this is `False` then the tag needs to exist locally (default `false`)
- `update-tag` *(bool)* — whether to overwrite a remote tag or not (default `false`)
- **`branches`** *(list)* — branches to push at the completion of the build
**branch**
- `remote` *(str)* — remote repo name to push to (default `'origin'`)
- `name` *(str)* — name of remote branch to push to
- `rebase` *(bool)* — whether or not to rebase before push (default `false`)
- **`notes`** *(list)* — notes to push at the completion of the build
**note**
- `remote` *(str)* — remote repo name to push to (default `'origin'`)
- `message` *(str)* — content of the note
- `namespace` *(str)* — namespace of the note (default `master`)
- `replace-note` *(bool)* — whether to overwrite a note or not (default `false`)
**Minimal Example:**
publishers:
- git
**Full Example:**
publishers:
- git: push-merge: true push-only-if-success: false force-push: true tags:
- tag: remote: tagremotename name: tagname message: "some tag message" create-tag: true update-tag: true branches:
- branch: remote: branchremotename name: "some/branch" rebase: true notes:
- note: remote: remotename message: "some note to push" namespace: notenamespace replace-note: true
---
## <purple>github-notifier()</purple> 🐙
Sets the build status on a Github commit. Channeling your inner status queen. 👑
> Requires the Jenkins Github Plugin — <https://plugins.jenkins.io/github>.
**Example:**
publishers:
- github-notifier
---
## <hotpink>github-pull-request-merge()</hotpink> 💖
This action merges the pull request that triggered the build (see the github pull request trigger). Iconic merge behavior, honestly.
> Requires the Jenkins GitHub pull request builder plugin — <https://plugins.jenkins.io/ghprb>.
### <lavender>Parameters</lavender> ✨
- **`only-admins-merge`** *(bool)* — if `true`, only administrators can merge the pull request, (default `false`)
- **`disallow-own-code`** *(bool)* — if `true` it will allow merging your own pull requests, in opposite to needing someone else to trigger the merge. (default `false`)
- **`merge-comment`** *(str)* — comment to set on the merge commit (default `''`)
- **`fail-on-non-merge`** *(bool)* — fail the job if the merge was unsuccessful (default `false`)
- **`delete-on-merge`** *(bool)* — delete the branch of the pull request on successful merge (default `false`)
**Full Example:**
publishers:
- github-pull-request-merge: only-admins-merge: true disallow-own-code: true merge-comment: 'my fancy commit message' fail-on-non-merge: true delete-on-merge: true
**Minimal Example:**
publishers:
- github-pull-request-merge
---
## <peach>gitlab-message()</peach> 🍑
Adds a note with the build status on a GitLab merge request. It's giving commentary era, bestie. 💬
> Requires the Jenkins GitLab Plugin — <https://plugins.jenkins.io/gitlab-plugin>.
### <lavender>Parameters</lavender> ✨
- **`failure-only`** *(bool)* — make a comment only on failure (default `false`)
- **`success-note`** *(bool)* — make a comment on the GitLab Merge Request if the build succeeds (default `false`)
- **`failure-note`** *(bool)* — make a comment on the GitLab Merge Request if the build failed (default `false`)
- **`abort-note`** *(bool)* — make a comment on the GitLab Merge Request if the build aborted (default `false`)
- **`unstable-note`** *(bool)* — make a comment on the GitLab Merge Request if the build is unstable (default `false`)
- **`success-note-text`** *(str)* — text of the comment on a success build (default `''`)
- **`failure-note-text`** *(str)* — text of the comment on a failed build (default `''`)
- **`abort-note-text`** *(str)* — text of the comment on an aborted build (default `''`)
- **`unstable-note-text`** *(str)* — text of the comment on an unstable build (default `''`)
**Minimal Example:**
publishers:
- gitlab-message
**Full Example:**
publishers:
- gitlab-message: failure-only: true success-note: true success-note-text: "SUCCESS" failure-note: true failure-note-text: "Build was failed. See log on Jenkins" abort-note: true abort-note-text: "Build was aborted" unstable-note: true unstable-note-text: "The build is unstable"
---
### ✨ `gitlab-notifier()` ✨
Sets the build status right on your GitLab commit, bestie 💅. This one needs the Jenkins GitLab Plugin — `https://plugins.jenkins.io/gitlab-plugin`.
**Parameters**
- **`name`** (*str*) — the name of the build as it shows up in GitLab. This is literally how you tell different Jenkins jobs apart when they're all posting on the same commit in GitLab. (default `'jenkins'`)
- **`mark-unstable-as-success`** (*bool*) — (default `false`)
**Minimal Example:**
publishers:
- gitlab-notifier
**Full Example:**
publishers:
- gitlab-notifier: name: foobar-jenkins mark-unstable-as-success: true
---
### 🗳️ `gitlab-vote()` 🗳️
Casts a vote for the build status on a GitLab merge request. Yeah, it's giving democracy ✨. Needs the Jenkins GitLab Plugin — `https://plugins.jenkins.io/gitlab-plugin`.
**Example:**
publishers:
- gitlab-vote
---
### ☁️ `google-cloud-storage()` ☁️
Uploads your build artifacts straight to Google Cloud Storage. Requires the Jenkins Google Cloud Storage plugin — `https://plugins.jenkins.io/google-storage-plugin`.
Heads up bestie, this isn't just "install the plugin and go" 👀 — you also need Google OAuth Credentials installed *and* the required credentials added to Jenkins. All of it, no skipping.
**Parameters**
- **`credentials-id`** (*str*) — the set of Google credentials registered with the Jenkins Credential Manager, used to authenticate with your project. (**required**)
- **`uploads`** (*list*) —
- **`expiring-elements`** (*dict*)
- params
- **`bucket-name`** (*str*) — bucket name to upload artifacts (**required**)
- **`days-to-retain`** (*int*) — days to keep artifacts (**required**)
- **`build-log`** (*dict*)
- params
- **`log-name`** (*str*) — name of the file that the Jenkins console log should be named (**required**)
- **`storage-location`** (*str*) — bucket name to upload artifacts (**required**)
- **`share-publicly`** (*bool*) — whether to share uploaded artifacts with everyone (default `false`)
- **`upload-for-failed-jobs`** (*bool*) — whether to upload artifacts even if the build fails (default `false`)
- **`show-inline`** (*bool*) — whether to show the uploaded build log inline in web browsers instead of forcing it to be downloaded (default `true`)
- **`strip-prefix`** (*str*) — strip this prefix off the file names (default not set)
- **`classic`** (*dict*)
- params
- **`file-pattern`** (*str*) — ant style globs to match the files to upload (**required**)
- **`storage-location`** (*str*) — bucket name to upload artifacts (**required**)
- **`share-publicly`** (*bool*) — whether to share uploaded artifacts with everyone (default `false`)
- **`upload-for-failed-jobs`** (*bool*) — whether to upload artifacts even if the build fails (default `false`)
- **`show-inline`** (*bool*) — whether to show the uploaded artifacts inline in web browsers instead of forcing them to be downloaded (default `false`)
- **`strip-prefix`** (*str*) — strip this prefix off the file names (default not set)
**Example:**
publishers:
- google-cloud-storage: credentials-id: 'myCredentials' uploads:
- expiring-elements: bucket-name: 'gs://myBucket' days-to-retain: 7
**Full example:**
publishers:
- google-cloud-storage: credentials-id: 'myCredentials' uploads:
- expiring-elements: bucket-name: 'gs://myBucket' days-to-retain: 7
- build-log: log-name: 'console.log' storage-location: 'gs://myBucket' upload-for-failed-jobs: true share-publicly: true
- classic: file-pattern: 'target/*.war' storage-location: 'gs://myBucket' upload-for-failed-jobs: true
- classic: file-pattern: '*/build/.iso' storage-location: 'gs://myBucket/artifacts/' share-publicly: true strip-prefix: 'path/to/'
---
### 🍇 `groovy-postbuild()` 🍇
Runs a groovy script, obviously 💅. Requires the Jenkins Groovy Postbuild Plugin — `https://plugins.jenkins.io/groovy-postbuild`.
> okay but PLEASE check which version of the plugin you actually have installed, because 1.x and 2.x have **incompatible changes** between them 😭. Full info, migration process and all — go look at the plugin's home page: `https://plugins.jenkins.io/groovy-postbuild`.
**Parameters**
- **`script`** (*str*) — the groovy script to execute
- **`classpath`** (*list*) — list of additional classpaths (>=1.6)
- **`on-failure`** (*str*) — when the script fails: leave the build as it is with `"nothing"`, mark the build unstable with `"unstable"`, or mark the job as failure with `"failed"` (default `'nothing'`)
- **`matrix-parent`** (*bool*) — run the script for the matrix parent only (>=1.9) (default `false`)
- **`sandbox`** (*bool*) — execute the script inside of the groovy sandbox (>=2.0) (default `false`)
**Example:**
publishers:
- groovy-postbuild: script: "manager.buildFailure()" classpath:
- "file:///path/to/your/lib"
- "file:///path/to/your/lib" on-failure: "failed" matrix-parent: true
---
### 🐻 `growl()` 🐻
Pushes notifications out to a growl client 🫶. Requires the Jenkins Growl Plugin — `https://plugins.jenkins.io/growl`.
**Parameters**
- **`ip`** (*str*) — IP address to send growl notifications to (**required**)
- **`notify-only-on-fail-or-recovery`** (*bool*) — only send a growl when the build fails or recovers from a failure (default `false`)
**Minimal Example:**
publishers:
- growl: ip: foo.ip.address
**Full Example:**
publishers:
- growl: ip: foo.ip.address notify-only-on-fail-or-recovery: true
---
### 💬 `hipchat()` 💬
A publisher that sends hipchat notifications on job events. Requires the Jenkins Hipchat Plugin — `https://plugins.jenkins.io/hipchat` — version **>=1.9**.
For older plugin versions, the docs live over here: `https://jenkins-job-builder.readthedocs.io/en/latest/hipchat.html`.
**Parameters**
- **`token`** (*str*) — this overrides the default auth token (optional)
- **`rooms`** (*list*) — list of HipChat rooms to post messages to; overrides the global default (optional)
- **`notify-start`** (*bool*) — post messages about the build start event (default `false`)
- **`notify-success`** (*bool*) — post messages about a successful build event (default `false`)
- **`notify-aborted`** (*bool*) — post messages about an aborted build event (default `false`)
- **`notify-not-built`** (*bool*) — post messages about a build set to `NOT_BUILT`. That status code gets used in multi-stage builds where a problem in an earlier stage stopped later stages from ever building. (default `false`)
- **`notify-unstable`** (*bool*) — post messages about an unstable build event (default `false`)
- **`notify-failure`** (*bool*) — post messages about the build failure event (default `false`)
- **`notify-back-to-normal`** (*bool*) — post messages about the build being back to normal after being unstable or failed (default `false`)
- **`start-message`** *(str)* — overrides the default start message. it's optional, bestie 💖
- **`complete-message`** *(str)* — overrides the default complete message. also optional ✨
**Example:**
publishers:
- hipchat: token: auth rooms:
- room1
- room2 notify-start: true notify-aborted: true start-message: job started complete-message: job completed
---
### `hp-alm()` 🧚
Publishes your test results straight to HP-ALM. it's giving "corporate but make it slay".
Needs the Jenkins Micro Focus Application Automation Tools plugin — that's `https://plugins.jenkins.io/hp-application-automation-tools-plugin`.
**Parameters:**
- **`server-name`** *(str)* — the name of the ALM Server. <red>required</red>, no skipping 🫶
- **`credentials-id`** *(str)* — credentials-id of the user (default `''`)
- **`domaine`** *(str)* — the Domain of the project to be used. <red>required</red>. and yes, it's literally spelled `domaine` in here, that's not me being quirky, that's the option name, so type it exactly 💅
- **`client-type`** *(str)* — client type, and it's required for some ALM above `12.60` in authentication. (default `''`)
- **`project`** *(str)* — the project to be used. <red>required</red>
- **`testing-framework`** *(str)* — the testing framework used when generating the testing result file. (default `Junit`)
- **`testing-tool`** *(str)* — the testing tool used when generating the testing result file. (default `''`)
- **`folder`** *(str)* — the path of the test folder that'll hold the uploaded test. <pink>heads up</pink>: the path does **not** include the Root test folder (`Subject`). so like, `sampletestfolder/subfolder` means your tests get uploaded to a test folder called `subfolder`, which lives under the test folder called `sampletestfolder`, which lives under the root test folder `Subject`. (required)
- **`set-folder`** *(str)* — the path of the testset folder that'll hold the uploaded testset. same deal, <pink>the path does not include the Root testset folder</pink>. for example `sampletestsetfolder/subfolder` means the testsets go into a testset folder named `subfolder`, which is under the testset folder named `sampletestsetfolder`, which is under the root testset folder `Root`. (required)
- **`testing-result-file`** *(str)* — the condition used to find the testing result file, and it starts from the root path of the job. like, `**/junitResult.xml` finds the testing result file for the Junit Plugin, and `**/testng-results.xml` finds the testing result file for the TestNG plugin. (required)
- **`jenkins-server-url`** *(str)* — the HTTP URL of the Jenkins Server, for example `http://jenkins.example.org:8080`. (optional)
**Minimal example using defaults:**
publishers:
- hp-alm: server-name: HP-ALM domain: FOO_COMPANY project: foo_project folder: 'ALM/foo/release1/test_case1' set-folder: 'ALM/foo/release1/test_case1/$env' testing-result-file: '**/junitResult.xml'
**Full example:**
publishers:
- hp-alm: server-name: HP-ALM credentials-id: cba09876-4321-4567-890a-bcde12345678 domain: FOO_COMPANY project: foo_project client-type: foo_client testing-framework: JUnit testing-tool: foo_tool folder: 'ALM/foo/release1/test_case1' set-folder: 'ALM/foo/release1/test_case1/$env' testing-result-file: '**/junitResult.xml' jenkins-server-url: 'http://myjenkinsserver.test.com:8080'
---
### `html-publisher()` 🌸
This plugin publishes HTML reports. simple, iconic, does exactly what it says ✨
Needs the Jenkins HTML Publisher Plugin — `https://plugins.jenkins.io/htmlpublisher`.
**Parameters:**
- **`name`** *(str)* — report name (required)
- **`dir`** *(str)* — HTML directory to archive (required)
- **`files`** *(str)* — specify the pages to display (required)
- **`keep-all`** *(bool)* — keep HTML reports for each past build (default `false`)
- **`allow-missing`** *(bool)* — allow missing HTML reports (default `false`)
- **`link-to-last-build`** *(bool)* — if this **and** `keep-all` are both true, it publishes the link on project level even if the build failed. (default `false`)
**Example:**
publishers:
- html-publisher: name: "some name" dir: "path/" files: "index.html" keep-all: true allow-missing: true link-to-last-build: true
---
### `hue-light()` 🌈
Okay this one is <rainbow>so fun</rainbow> — it shows the state of your builds using the awesome Philips hue lights 🎀. your room glows green when the build passes. main character CI/CD energy, fr.
Needs the Jenkins hue-light Plugin — `https://plugins.jenkins.io/hue-light`.
**Parameters:**
- **`light-id`** *(int)* — ID of the light. define multiple lights by using a comma as a separator (required)
- **`pre-build`** *(str)* — colour of building state (default `'blue'`)
- **`good-build`** *(str)* — colour of successful state (default `'green'`)
- **`unstable-build`** *(str)* — colour of unstable state (default `'yellow'`)
- **`bad-build`** *(str)* — colour of unsuccessful state (default `'red'`)
**Full Example:**
publishers:
- hue-light: light-id: 123 pre-build: yellow good-build: red unstable-build: blue bad-build: green
**Minimal Example:**
publishers:
- hue-light: light-id: 123
---
### `image-gallery()` 🦋
Produces an image gallery using a Javascript library. cute AND functional, we love to see it.
Needs the Jenkins Image Gallery Plugin — `https://plugins.jenkins.io/image-gallery`.
**Parameters:**
- **`gallery-type`** *(str)* — here are the `gallery-type` values you can pick from:
- `archived-images-gallery` (default)
- `in-folder-comparative-gallery`
- `multiple-folder-comparative-gallery`
- **`title`** *(str)* — gallery title (optional)
- **`image-width`** *(int)* — width of the image (optional)
- **`unstable-if-no-artifacts`** *(bool)* — marks the build as unstable if no archived artifacts were found (default `false`)
- **`includes`** *(str)* — include pattern (valid for `archived-images-gallery` gallery)
- **`base-root-folder`** *(str)* — base root dir (valid for comparative gallery)
- **`image-inner-width`** *(int)* — width of the image displayed in the inner gallery popup (valid for comparative gallery, optional)
**Example:**
publishers:
- image-gallery:
- gallery-type: archived-images-gallery title: Gallery 1 includes: path/images image-width: 100 unstable-if-no-artifacts: true
- gallery-type: in-folder-comparative-gallery title: Gallery 2 base-root-folder: path/images2 image-width: 321 image-inner-width: 111 unstable-if-no-artifacts: false
- gallery-type: multiple-folder-comparative-gallery title: Gallery 3 base-root-folder: path/images3 image-width: 222 image-inner-width: 1
---
### `influx-db()` 💜
Needs the Jenkins :jenkins-plugins: Influx DB `<influxdb>`.
---
### `ircbot()` 🔥
`ircbot` lets Jenkins send build notifications over IRC, and it lets you interact with Jenkins through an IRC bot. it's giving old-school and honestly? iconic 💅
Needs the Jenkins IRC Plugin — `https://plugins.jenkins.io/ircbot`.
**Parameters:**
- **`strategy`** *(str)* — this is your "when do we actually send notifications" dial. these are the `strategy` values:
- `all` — always (default)
- `any-failure` — on any failure
- `failure-and-fixed` — on failure and fixes
- `new-failure-and-fixed` — on new failure and fixes
- `statechange-only` — only on state change
- **`notify-start`** *(bool)* — whether to send notifications to channels when a build starts (default `false`)
- **`notify-committers`** *(bool)* — whether to send notifications to the users that are suspected of having broken this build (default `false`)
- **`notify-culprits`** *(bool)* — also send notifications to 'culprits' from previous unstable/failed builds (default `false`)
- **`notify-upstream`** *(bool)* — whether to send notifications to upstream committers if no committers were found for a broken build (default `false`)
- **`notify-fixers`** *(bool)* — whether to send notifications to the users that have fixed a broken build (default `false`)
- **`message-type`** *(str)* — channel notification message, and here's what you can set it to:
- `summary-scm` — for summary and SCM changes (default)
- `summary` — for summary only
- `summary-params` — for summary and build parameters
- `summary-scm-fail` — for summary, SCM changes, failures)
- **`channels`** *(list)* —
- **`list channels`** — these are your channel definitions! If you leave it empty, it just snags the channel from your Jenkins configuration. (default: empty) ⚠️ <red>**WARNING:**</red> the IRC plugin *needs* the channel configured in the system-wide config, or your jobs will straight-up fail to emit notifications to the channel. periodt.
<pink>**Channel**</pink>
- **`name`** (*str*) — Channel name 💬
- **`password`** (*str*) — Channel password (optional) 🤫
- **`notify-only`** (*bool*) — Set to `true` if you wanna disallow bot commands (default `false`)
- **`matrix-notifier`** (*str*) — --
notify for matrix projects 💫 instant-messaging-plugin injects an extra field into the configuration form whenever the project is a multi-configuration project
<purple>**`matrix-notifier` values**</purple>
- `all`
- `only-configurations` (default)
- `only-parent`
<pink>**Minimal Example:**</pink>
publishers:
- ircbot
<pink>**Full Example:**</pink>
publishers:
- ircbot: strategy: failure-and-fixed notify-start: true notify-committers: true notify-culprits: true notify-upstream: true notify-fixers: true message-type: summary channels:
- name: '#jenkins-channel1' password: secrete notify-only: false
- name: '#jenkins-channel2' notify-only: true matrix-notifier: all
---
### <hotpink>`jabber()`</hotpink> 🦋
Integrates Jenkins with the Jabber/XMPP instant messaging protocol 💌 Requires the Jenkins Jabber Plugin <https://plugins.jenkins.io/jabber>.
<purple>**Parameters**</purple>
- **`notify-on-build-start`** (*bool*) — Whether to send notifications to channels when a build starts (default `false`) 🚀
- **`notify-scm-committers`** (*bool*) — Whether to send notifications to the users that are suspected of having broken this build (default `false`) 😬
- **`notify-scm-culprits`** (*bool*) — Also send notifications to 'culprits' from previous unstable/failed builds (default `false`) 👀
- **`notify-upstream-committers`** (*bool*) — Whether to send notifications to upstream committers if no committers were found for a broken build (default `false`) ⬆️
- **`notify-scm-fixers`** (*bool*) — Whether to send notifications to the users that have fixed a broken build (default `false`) 🛠️
- **`group-targets`** (*list*) — List of group targets to notify 👥
- **`individual-targets`** (*list*) — List of individual targets to notify 🧍
- **`strategy`** (*dict*) — --
When to send notifications (default `all`)
<purple>**`strategy` values**</purple>
- `all` — Always
- `failure` — On any failure
- `failure-fixed` — On failure and fixes
- `new-failure-fixed` — On new failure and fixes
- `change` — Only on state change
- **`message`** (*dict*) — --
Channel notification message (default `summary-scm`)
<purple>**`message` values**</purple>
- `summary-scm` — Summary + SCM changes
- `summary` — Just summary
- `summary-build` — Summary and build parameters
- `summary-scm-fail` — Summary, SCM changes, and failed tests
<pink>**Minimal Example:**</pink>
publishers:
- jabber
<pink>**Full Example:**</pink>
publishers:
- jabber: notify-on-build-start: true notify-scm-committers: true notify-scm-culprits: true notify-upstream-committers: true notify-scm-fixers: true group-targets:
- "foo-room@conference-2-fooserver.foo.com" individual-targets:
- "foo-user@conference-2-fooserver.foo.com" strategy: new-failure-fixed message: summary
---
### <hotpink>`jacoco()`</hotpink> 📊
Generate a JaCoCo coverage report ✨ Requires the Jenkins JaCoCo Plugin <https://plugins.jenkins.io/jacoco>.
<purple>**Parameters**</purple>
- **`exec-pattern`** (*str*) — This is a file name pattern that can be used to locate the jacoco report files (default `**/**.exec`)
- **`class-pattern`** (*str*) — This is a file name pattern that can be used to locate class files (default `**/classes`)
- **`source-pattern`** (*str*) — This is a file name pattern that can be used to locate source files (default `**/src/main/java`)
- **`source-inclusion-pattern`** (*str*) — This is a file name pattern that can be used to include certain source files (default `**/*.java`)
- **`update-build-status`** (*bool*) — Update the build according to the results (default `false`)
- **`inclusion-pattern`** (*str*) — This is a file name pattern that can be used to include certain class files (default `''`)
- **`exclusion-pattern`** (*str*) — This is a file name pattern that can be used to exclude certain class files (default `''`)
- **`targets`** (*dict*) — `.INDENT 2.0`
<purple>**`targets`**</purple>
(`instruction`, `branch`, `complexity`, `line`, `method`, `class`)
- **`healthy`** (*int*): Healthy threshold (default `0`) 💚
- **`unhealthy`** (*int*): Unhealthy threshold (default `0`) 💔
<pink>**Minimal Example:**</pink>
publishers:
- jacoco
<pink>**Full Example:**</pink>
publishers:
- jacoco: exec-pattern: '/.exec' class-pattern: '/classes' source-pattern: '/src/main/java' source-inclusion-pattern: '/.java,/.kt' update-build-status: true inclusion-pattern: '/.class' exclusion-pattern: '/Test*.class' targets:
- instruction: healthy: 7 unhealthy: 1
- branch: healthy: 8 unhealthy: 2
- complexity: healthy: 9 unhealthy: 3
- line: healthy: 10 unhealthy: 4
- method: healthy: 11 unhealthy: 5
- class: healthy: 12 unhealthy: 6
---
### <hotpink>`javadoc()`</hotpink> 📚
Publish Javadoc ✨ Requires the Jenkins Javadoc Plugin <https://plugins.jenkins.io/javadoc>.
<purple>**Parameters**</purple>
- **`directory`** (*str*) — Directory relative to the root of the workspace, like `'myproject/build/javadoc'` (optional)
- **`keep-all-successful`** (*bool*) — When `true`, it will retain Javadoc for each successful build 💾 This lets you browse Javadoc for older builds, at the expense of additional disk space requirement. If `false`, it will only keep the latest Javadoc, so older Javadoc gets overwritten as new builds succeed. (default `false`)
<pink>**Example:**</pink>
publishers:
- javadoc: directory: myproject/build/javadoc keep-all-successful: true
---
### <hotpink>`jclouds()`</hotpink> ☁️
JClouds Cloud Storage Settings gives you a way to store artifacts on JClouds supported storage providers 🗄️ Requires the Jenkins JClouds Plugin <https://plugins.jenkins.io/jclouds-jenkins>.
JClouds Cloud Storage Settings *has* to be configured for the Jenkins instance, no cap.
<purple>**Parameters**</purple>
- **`profile`** (*str*) — preconfigured storage profile (**required**) 🫡
- **`files`** (*str*) — files to upload (regex) (**required**)
- **`basedir`** (*str*) — the source file path (relative to workspace, Optional)
- **`container`** (*str*) — the destination container name (**required**)
- **`hierarchy`** (*bool*) — keep hierarchy (default `false`) 🌳
<pink>**Example:**</pink>
publishers:
- jclouds: profile: hp files: '*.tar.gz' container: jenkins basedir: test base dir
---
### <hotpink>`jdepend()`</hotpink> 🔍
Publish jdepend report ✨ Requires the JDepend Plugin <https://plugins.jenkins.io/jdepend>.
<purple>**Parameters**</purple>
- **`file`** (*str*) — path to jdepend file (**required**)
<pink>**Example:**</pink>
publishers:
- jdepend: file: build/jdepend/main.xml
---
### <hotpink>`jira()`</hotpink> 🎫
Update relevant JIRA issues 💜 Requires the Jenkins JIRA Plugin <https://plugins.jenkins.io/jira>.
<pink>**Example:**</pink>
publishers:
- jira
---
### <hotpink>`jms-messaging()`</hotpink> 📨
The JMS Messaging Plugin provides the following functionality, bestie:
- A build trigger to submit jenkins jobs upon receipt of a matching message 🔔
- A builder that may be used to submit a message to the topic upon the completion of a job 📤
- A post-build action that may be used to submit a message to the topic upon the completion of a job 🎯
<purple>**JMS Messaging provider types supported:**</purple>
- ActiveMQ
- FedMsg
Requires the Jenkins JMS Messaging Plugin Pipeline Plugin <https://plugins.jenkins.io/jms-messaging>.
<purple>**Parameters**</purple>
- **`override-topic`** (*str*) — If you need to override the default topic. (default `''`) 🎙️
- **`provider-name`** (*str*) — the name of the message provider setup in the global config. (default `''`)
- **`msg-type`** (*str*) — a message type (default `'CodeQualityChecksDone'`)
- **`msg-props`** (*str*) — message header to publish. (default `''`)
- **`msg-content`** (*str*) — message body to publish. (default `''`)
Ok bestie here's the **full glow-up example** 💅:
publishers:
- jms-messaging: override-topic: org.centos.stage.ci.pipeline.compose.complete provider-name: fedmsg msg-type: Custom msg-props: | topic=org.centos.prod.ci.pipeline.compose.complete username=fedora-atomic msg-content: | { "build_url": "${BUILD_URL}", "compose_url": "<full-url-to-compose>", "build_id": "${BUILD_ID}", "ref": "fedora/rawhide/${basearch}/atomic-host", "rev": "<sha of the commit from dist-git>", "namespace": "rpms", "repo": "php-simplepie", "status": "<success/failure/aborted>", "test_guidance": "<comma-separated-list-of-test-suites-to-run>"}
And the **bare minimum** version (low effort, still slays) ✨:
publishers:
- jms-messaging: provider-name: fedmsg msg-type: CodeQualityChecksDone msg-props: test msg-content: test
## 🦋 `join-trigger()` 🦋
Triggers a job *after* all the immediate downstream jobs have finished. The way this one waits for the whole friend group to show up before the party starts 😤. Needs the <pink>Jenkins Join Plugin</pink> at `https://plugins.jenkins.io/join`.
**Parameters**
- **`projects`** (*list*) — list of projects to trigger
- **`publishers`** (*list*) — list of triggers from the `publishers` module that defines projects that need to be triggered
- **`threshold`** (*str*) — result threshold to trigger jobs (optional). Valid values are `"success"`, `"unstable"`, `"failure"`, and `"aborted"`.
- **`even-if-unstable`** (*bool*) — if true, jobs will trigger even if some downstream jobs are marked as unstable (default `false`) (**DEPRECATED** — yeah it's giving legacy energy, don't come for me)
**Example:**
publishers:
- join-trigger: projects:
- project-one
- project-two threshold: unstable publishers:
- trigger-parameterized-builds:
- project: archive current-parameters: true trigger-from-child-projects: true trigger-with-no-params: true
- project: cleanup current-parameters: true trigger-with-no-params: false
---
## 🌸 `junit()` 🌸
Publishes JUnit test results. Needs the <pink>Jenkins JUnit Plugin</pink> at `https://plugins.jenkins.io/junit`. This is the one that tells everyone how the tests did fr fr 🧪.
**Parameters**
- **`results`** (*str*) — results filename (**required** — no results, no party 💀)
- **`keep-long-stdio`** (*bool*) — retain long standard output/error in test results (default `true`).
- **`health-scale-factor`** (*float*) — amplification factor to apply to test failures when computing the test result contribution to the build health score. (default `1.0`)
- **`allow-empty-results`** (*bool*) — do not fail the build on empty test results (default `false`)
- **`skip-publishing-checks`** (*bool*) — do not publish issues to SCM provider platforms (default `false`)
- **`skip-marking-build-unstable`** (*bool*) — do not mark build as unstable on test failure (default `false`)
- **`test-stability`** (*bool*) — add historical information about test results stability (default `false`). Needs the <pink>Jenkins Test stability Plugin</pink> at `https://plugins.jenkins.io/test-stability`.
- **`claim-build`** (*bool*) — allow claiming of failed tests (default `false`). Needs the <pink>Jenkins Claim Plugin</pink> at `https://plugins.jenkins.io/claim`.
- **`measurement-plots`** (*bool*) — create measurement plots (default `false`). Needs the <pink>Jenkins Measurement Plots Plugin</pink> at `https://github.com/jenkinsci/measurement-plots-plugin`.
- **`flaky-test-reports`** (*bool*) — publish flaky test reports (default `false`). Needs the <pink>Jenkins Flaky Test Handler Plugin</pink> at `https://plugins.jenkins.io/flaky-test-handler`.
- **`junit-attachments`** (*bool*) — publish test attachments (default `false`). Needs the <pink>Jenkins JUnit Attachments Plugin</pink> at `https://plugins.jenkins.io/junit-attachments`.
**Minimal example using defaults** (the "I woke up like this" version 😌):
publishers:
- junit: results: nosetests.xml
**Full example** (main character energy, every option turned ON 👑):
publishers:
- junit: results: nosetests-example.xml keep-long-stdio: false health-scale-factor: 2.0 allow-empty-results: true skip-publishing-checks: true skip-marking-build-unstable: true test-stability: true claim-build: true measurement-plots: true flaky-test-reports: true junit-attachments: true
---
## 🌈 `logparser()` 🌈
Needs the <pink>Jenkins Log Parser Plugin</pink> at `https://plugins.jenkins.io/log-parser`. It reads your logs and is like "I see you 👀".
**Parameters**
- **`parse-rules`** (*str*) — full path to parse rules (default `''`)
- **`use-project-rules`** (*bool*) — use project rules instead of global (default `true`)
- **`unstable-on-warning`** (*bool*) — mark build unstable on warning (default `false`)
- **`fail-on-error`** (*bool*) — mark build failed on error (default `false`)
- **`show-graphs`** (*bool*) — show parser trend graphs (default `true`)
**Minimal Example:**
publishers:
- logparser: parse-rules: "project-log-parser-rules.txt"
**Full Example:**
publishers:
- logparser: use-project-rules: false parse-rules: "/path/to/global-rules" unstable-on-warning: true fail-on-error: true show-graphs: false
---
## 💜 `logstash()` 💜
Sends the job's console log to Logstash so it can process and analyze your job data. Also stores test metrics from Junit. Needs the <pink>Jenkins Logstash Plugin</pink> at `https://plugins.jenkins.io/logstash`. Basically it sends your logs to the group chat that actually reads them 💅.
**Parameters**
- **`max-lines`** (*int*) — the maximum number of log lines to send to Logstash. (default `1000`)
- **`fail-build`** (*bool*) — mark build as failed if this step fails. (default `false`)
**Minimal Example:**
publishers:
- logstash
**Full Example:**
publishers:
- logstash: max-lines: 2000 fail-build: true
---
## ⭐ `maven-deploy()` ⭐
Deploys artifacts to a Maven repository. Shipping the goods, no cap 📦.
**Parameters**
- **`id`** (*str*) — repository ID
- **`url`** (*str*) — repository URL (optional)
- **`unique-version`** (*bool*) — assign unique versions to snapshots (default `true`)
- **`deploy-unstable`** (*bool*) — deploy even if the build is unstable (default `false`)
- **`release-env-var`** (*str*) — if the given variable name is set to `"true"`, the deploy steps are skipped. (optional)
**Example:**
publishers:
- maven-deploy: id: example url: http://repo.example.com/maven2/ unique-version: true deploy-unstable: false release-env-var: TIMER
---
## 🦋 `mqtt()` 🦋
This plugin lets you send build notifications to an MQTT message queue. Needs the <pink>MQTT Notification Plugin</pink> at `https://plugins.jenkins.io/mqtt-notification-plugin`. It's giving little messenger pigeon but make it protocol vibes 🕊️.
**Parameters**
- **`broker-url`** (*str*) — the broker URL, as `protocol://address:port` (**required**)
- **`credentials-id`** (*str*) — credentials to use to connect to the broker (optional)
- **`topic`** (*str*) — the message topic (default `"jenkins/$PROJECT_URL"`)
- **`message`** (*str*) — the message itself (default `"$BUILD_RESULT"`)
- **`qos`** (*str*) — one of `AT_MOST_ONCE`, `AT_LEAST_ONCE`, or `EXACTLY_ONCE` (default `AT_MOST_ONCE`)
- **`retain-message`** (*bool*) — whether to resend message or not when a new client connects (default `false`)
**Minimal Example:**
publishers:
- mqtt: broker-url: tcp://localhost:1883
**Full Example:**
publishers:
- mqtt: broker-url: tcp://localhost:1883 topic: hello message: world qos: EXACTLY_ONCE retain-message: true credentials-id: abcde
---
## 🎀 `naginator()` 🎀
Automatically reschedules a build after a build failure. It's the "bestie we're running it back 🔁" of Jenkins plugins, honestly iconic. Needs the <pink>Jenkins Naginator Plugin</pink> at `https://plugins.jenkins.io/naginator`.
**Parameters**
- **`rerun-unstable-builds`** (*bool*) — rerun build for unstable builds as well as failures (default `false`)
- **`rerun-matrix-part`** (*bool*) — rerun build only for failed parts on the matrix (`>=1.12`) (default `false`)
- **`fixed-delay`** (*int*) — how many seconds to sit around before retrying the build. Bestie, you **cannot** use this one at the same time as `progressive-delay-increment` or `progressive-delay-maximum`. Also it's the default delay type 💅 (default `0`)
- **`progressive-delay-increment`** (*int*) — the progressive delay, in seconds, that gets incremented before retrying a build. Nope, you can't use it while `fixed-delay` is in play (default `0`)
- **`progressive-delay-maximum`** (*int*) — the progressive delay, in seconds, before the retry hits its max delay. Same rule: not allowed when `fixed-delay` is being used (default `0`)
- **`max-failed-builds`** (*int*) — the max number of successive failed builds, like the plug is on its last nerve (default `0`)
- **`regular-expression`** (*str*) — only rerun the build if this regular expression shows up in the output, no cap 🕵️ (default `''`)
Example:
publishers:
- naginator: rerun-unstable-builds: true rerun-matrix-part: true progressive-delay-increment: 5 progressive-delay-maximum: 15 max-failed-builds: 6 regular-expression: "foo"
---
## <purple>openshift-build-canceller()</purple> 🎀
Okay so this action is literally the cleanup crew for a Jenkins job that failed because a build is hung — like, it did *not* terminate with a failure code, it just. sat there. This step lets you do the equivalent of an `oc cancel-build` for the build config you handed over, and any builds under that build config that weren't already terminated (successfully or unsuccessfully) or cancelled? Cancelled. Every last one. Periodt. ✨
Requires the Jenkins OpenShift Pipeline Plugin <https://plugins.jenkins.io/openshift-pipeline>.
### Parameters
- **`api-url`** (*str*) — this is the value you'd specify if you were using the `--server` option on the OpenShift `oc` command (default `'https://openshift.default.svc.cluster.local'`)
- **`bld-cfg`** (*str*) — whatever the output form `oc project` was when you created the BuildConfig you want to run a Build on (default `'frontend'`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in `"namespace"`, that's the value you wanna put here (default `'test'`)
- **`auth-token`** (*str*) — what you supply with the `--token` option when you're invoking the OpenShift `oc` command (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off (default `false`)
### Full Example:
publishers:
- openshift-build-canceller: api-url: https://openshift.example.local.url/ bld-cfg: front namespace: test-build auth-token: ose-key-canceller1 verbose: true
### Minimal Example:
publishers:
- openshift-build-canceller
---
## <purple>openshift-deploy-canceller()</purple> 🦋
This action is built to clean up any OpenShift deployments still running when the Job finishes — messy queen behavior, we don't do that here 💅 — and this step lets you do the equivalent of an `oc deploy --cancel` for the deployment config you provided.
Requires the Jenkins OpenShift Pipeline Plugin <https://plugins.jenkins.io/openshift-pipeline>.
### Parameters
- **`api-url`** (*str*) — this is the value you'd specify if you were using the `--server` option on the OpenShift `oc` command (default `'https://openshift.default.svc.cluster.local'`)
- **`dep-cfg`** (*str*) — whatever the output form `oc project` was when you created the BuildConfig you want to run a Build on (default `frontend`)
- **`namespace`** (*str*) — if you run `oc get bc` for the project listed in `"namespace"`, that's the value you wanna put here (default `'test'`)
- **`auth-token`** (*str*) — what you supply with the `--token` option when you're invoking the OpenShift `oc` command (default `''`)
- **`verbose`** (*bool*) — the toggle for turning detailed logging in this plug-in on or off (default `false`)
### Full Example:
publishers:
- openshift-deploy-canceller: api-url: https://openshift.example.local.url/ dep-cfg: front namespace: test6 auth-token: ose-key-dep-canceller1 verbose: true
### Minimal Example:
publishers:
- openshift-deploy-canceller
---
## <hotpink>opsgenie()</hotpink> 🔔
OpsGenie notification when the build completes. Requires the OpsGenie Notifier Plugin <https://plugins.jenkins.io/opsgenie>.
### Parameters
- **`enable-sending-alerts`** (*bool*) — send alerts to opsgenie (default `false`)
- **`notify-build-start`** (*bool*) — send a notification when the build starts (default `false`)
- **`api-key`** (*str*) — this token is used to verify requests between OpsGenie and Jenkins. You can copy this key from your OpsGenie-Jenkins Integration page 👀 (default `''`)
- **`tags`** (*str*) — comma-separated list of tags you want to add on the alert (default `''`)
- **`teams`** (*str*) — comma-separated list of teams that get notified from the alert (default `''`)
- **`priority`** (*str*) — sets the priority of the alert that's gonna be created at OpsGenie, if the job's build fails (default `'P3'`)
- **`build-starts-alerts-priority`** (*str*) — sets the priority of the build started alert that's gonna be created at OpsGenie (default `'P3'`)
- **`api-url`** (*str*) — api url that collects the webhook (default `''`)
### Minimal example:
publishers:
- opsgenie
### Full Example:
publishers:
- opsgenie: enable-sending-alerts: true notify-build-start: true api-key: "test api key" priority: "P1" build-starts-alerts-priority: "P2" api-url: "another-opsgenie-instance.com" tags: "a,b,c" teams: "team a, team b"
---
## <cyan>packer()</cyan> 📦
This plugin lets a job publish an image generated by Packer. Requires the Jenkins Packer Plugin <https://plugins.jenkins.io/packer>.
### Parameters
- **`name`** (*str*) — name of the packer installation (**required** 👑)
- **`json-template`** (*str*) — path to a Packer JSON template file (default `''`)
- **`json-template-text`** (*str*) — text of Packer JSON template (default `''`)
- **`add-params`** (*str*) — specify which additional parameters to pass to packer (default `''`)
- **`use-debug`** (*bool*) — adds `-debug` argument when packer executes (default `false`)
- **`change-dir`** (*str*) — if set, the current directory will be changed to this before starting packer (default `''`)
- **`template-mode`** (*str*) — Packer template option used (default `global`)
template-mode values
- global
- file
- text
- **`file-entries`** (*list*) — file entries for the packer configuration (default `[]`)
- **`variable-name`** (*str*) — variable name for a file to be used in the configuration JSON (default `''`)
- **`contents`** (*str*) — file contents of the configuration JSON (default `''`)
### Minimal Example:
publishers:
- packer: name: test name
### Full Example:
publishers:
- packer: name: test name json-template: test template json-template-text: test template text add-params: additional params use-debug: true change-dir: change to directory template-mode: global file-entries:
- files: variable-name: test var contents: test content
- files: variable-name: test var 2 contents: test content 2
---
## <mint>performance()</mint> 📈
Publish performance test results from jmeter and junit — numbers girlies rise up ✨ Requires the Jenkins Performance Plugin <https://plugins.jenkins.io/performance>.
### Parameters
- **`failed-threshold`** (*int*) — specify the error percentage threshold that sets the build to failed. A negative value means don't use this threshold, we're chill like that (default `0`)
- **`unstable-threshold`** (*int*) — specify the error percentage threshold that sets the build unstable. A negative value means don't use this threshold (default `0`)
- **`unstable-response-time-threshold`** (*str*) — average response time threshold (default `''`)
- **`failed-threshold-positive`** (*float*) — maximum failed percentage for build comparison (default `0.0`)
- **`failed-threshold-negative`** (*float*) — minimum failed percentage for build comparison (default `0.0`)
- **`unstable-threshold-positive`** (*float*) — maximum unstable percentage for build comparison (default `0.0`)
- **`unstable-threshold-negative`** (*float*) — minimum unstable percentage for build comparison (default `0.0`)
- **`nth-build-number`** (*int*) — build number for build comparison (default `0`)
- **`mode-relative-thresholds`** (*bool*) — relative threshold mode (default `false`)
- **`config-type`** (*str*) — what are we even comparing here bestie 💅 default is `'ART'`. The values you can pick:
- `ART` — Average Response Time 💖
- `MRT` — Median Response Time ✨
- `PRT` — Percentile Response Time 🎀
- **`mode-of-threshold`** (*bool*) — the threshold's whole vibe. `true` means relative threshold, `false` means error threshold. Default is `false`.
- **`fail-build`** (*bool*) — do we hard-fail the build when the result files are literally not there? Default `false`.
- **`compare-build-previous`** (*bool*) — compare against the previous build. Default `false`.
- **`mode-performance-per-test-case`** (*bool*) — Performance Per Test Case Mode. Default `true`.
- **`mode-thoughput`** (*bool*) — show the Throughput Chart or nah. Default `false`. (yes the name is spelled exactly like that, we do not fix it, we respect it 🫶)
- **`report`** (*dict*) — your report config, and inside it:
- `jmeter` or `junit` (*dict or str*): drop in a custom report file if you want (both optional — `jmeter` defaults to `**/.jtl`, `junit` defaults to `*/TEST-*.xml`).
<purple>**Minimal Example:**</purple>
publishers:
- performance
<purple>**Full Example:**</purple>
publishers:
- performance: failed-threshold: 85 unstable-threshold: -1 unstable-response-time-threshold: "JMeterResultsOrders.jtl:2000" failed-threshold-positive: 90.0 failed-threshold-negative: 10.0 unstable-threshold-positive: 80.0 unstable-threshold-negative: 20.0 nth-build-number: 10 mode-relative-thresholds: true config-type: "PRT" mode-of-threshold: true fail-build: true compare-build-previous: true mode-performance-per-test-case: false mode-thoughput: true report:
- jmeter: "/special/file.jtl"
- junit: "/special/file.xml"
- jmeter
- junit
---
### ✨ `phabricator()` ✨
Integrate with Phabricator (<https://www.phacility.com/>) — yes the whole entire thing, we're connecting 💫
Needs the Jenkins Phabricator Plugin (<https://plugins.jenkins.io/phabricator-plugin>) or it's not happening, sorry not sorry.
**Parameters**
- **`comment-on-success`** (*bool*) — post a comment when the build succeeds. (optional)
- **`uberalls-enabled`** (*bool*) — integrate with uberalls. (optional)
- **`comment-file`** (*str*) — include the contents of a given file if commenting is enabled. (optional)
- **`comment-size`** (*int*) — maximum comment character length. (optional)
- **`comment-with-console-link-on-failure`** (*bool*) — post a comment when the build fails. (optional)
<purple>**Example:**</purple>
publishers:
- phabricator: comment-on-success: false uberalls-enabled: false comment-with-console-link-on-failure: false
---
### 🌈 `pipeline()` 🌈
Specify a downstream project in a pipeline. Requires the Jenkins Build Pipeline Plugin (<https://plugins.jenkins.io/build-pipeline-plugin>). Chain reaction energy fr fr 🔥
If you're using the `node-label-name` or `node-label` parameters, you also need the Jenkins NodeLabel Parameter Plugin (<https://plugins.jenkins.io/nodelabelparameter>). And heads up bestie: `'node-parameters'` **overrides** the Node that the triggered project is tied to. Watch out for that one 👀
**Parameters**
- **`projects`** (*list*) — list the jobs to trigger. This generates a comma-separated string containing the named jobs.
- **`predefined-parameters`** (*str*) — parameters to pass to the other job (optional)
- **`current-parameters`** (*bool*) — whether to include the parameters passed to the current build over to the triggered job (optional)
- **`node-parameters`** (*bool*) — use the same Node for the triggered builds that was used for this build. (optional)
- **`svn-revision`** (*bool*) — pass the svn revision to the triggered job (optional)
- **`include-upstream`** (*bool*) — include/pass through Upstream SVN Revisons. Only valid when `'svn-revision'` is `true`. (default `false`)
- **`git-revision`** (*dict*) — passes the git revision to the triggered job (optional).
- `combine-queued-commits` (*bool*): whether to combine queued git hashes or not (default `false`)
- **`boolean-parameters`** (*dict*) — pass boolean parameters to the downstream jobs. Specify the name and boolean value mapping of the parameters. (optional)
- **`property-file`** (*str*) — use properties from a file (optional)
- **`fail-on-missing`** (*bool*) — blocks the triggering of the downstream jobs if any of the property files are not found in the workspace. Only valid when `'property-file'` is specified. (default `false`)
- **`file-encoding`** (*str*) — encoding of the contents of the files. If it's not specified, the default encoding of the platform is used. Only valid when `'property-file'` is specified. (optional)
- **`restrict-matrix-project`** (*str*) — a filter that restricts the subset of the combinations that the downstream project will run (optional)
<purple>**Example:**</purple>
publishers:
- pipeline: project: test_project current-parameters: true predefined-parameters: foo=bar
publishers:
- pipeline: projects:
- test_project predefined-parameters: BUILD_NUM=${BUILD_NUMBER} current-parameters: true property-file: vars.txt git-revision: combine-queued-commits: true fail-on-missing: true file-encoding: UTF-8 boolean-parameters: p1: true p2: false svn-revision: true include-upstream: true
You can build pipeline jobs that are re-usable across different pipelines by using a Job Template <#job-template> to define the pipeline jobs, and variable substitution to specify the name of the downstream job in the pipeline. Job-specific substitutions are *so* useful here (see Project <#project>). Reuse queen behavior honestly 👑
Check `samples/pipeline.yaml` for an example pipeline implementation.
---
### 🎀 `plot()` 🎀
`Plot` provides generic plotting (or graphing). Graphs?? We love graphs 💖
Requires the Jenkins Plot Plugin (<https://plugins.jenkins.io/plot>).
**Parameters**
- **`title`** (*str*) — title for the graph (default `''`)
- **`yaxis`** (*str*) — title of the Y axis (default `''`)
- **`width`** (*int*) — the width of the plot in pixels (default `750`)
- **`height`** (*int*) — the height of the plot in pixels (default `450`)
- **`group`** (*str*) — name of the group to which the plot belongs (**required** — do not skip this one bestie, it's mandatory 😭)
- **`num-builds`** (*int*) — number of builds to plot across (default: plot all builds)
- **`style`** (*str*) — specifies the graph style of the plot. Can be: `area`, `bar`, `bar3d`, `line`, `line3d`, `stackedArea`, `stackedbar`, `stackedbar3d`, `waterfall` (default `'line'`)
- **`use-description`** (*bool*) — when false, the X-axis labels are formed using build numbers and dates, and the corresponding tooltips contain the build descriptions. When enabled, the contents of the labels and tooltips are swapped, with the descriptions used as X-axis labels and the build number and date used for tooltips. (default `false`)
- **`exclude-zero-yaxis`** (*bool*) — when false, Y-axis contains the value zero even if it is not included in the data series. When true, the value zero is not automatically included. (default `false`)
- **`logarithmic-yaxis`** (*bool*) — when true, the Y-axis will use a logarithmic scale. By default, the Y-axis uses a linear scale. (default `false`)
- **`keep-records`** (*bool*) — when true, show all builds up to `'Number of builds to include'`. (default `false`)
- **`csv-file-name`** (*str*) — use for choosing the file name in which the data will be persisted. If none is specified, a random name is generated as done in the Jenkins Plot plugin. (default: random generated `.csv` filename, same behaviour as the Jenkins Plot plugin)
- **`series`** (*list*) — list data series definitions 📊
**Series**
- `file` (*str*) : files to include
- `inclusion-flag` — filtering mode for CSV files. Possible values are:
- `off` (default)
- `include-by-string`
- `exclude-by-string`
- `include-by-column`
- `exclude-by-column`
- `exclude` (*str*) : exclude pattern for CSV file.
- `url` (*str*) : for `'csv'` and `'xml'` file types, used when you click on a point (default empty)
- `display-table` (*bool*) : for `'csv'` file type, if true, original CSV will be shown above the plot (default `false`)
- `label` (*str*) : used by `'properties'` file type. Specifies the legend label for this data series. (default empty)
- `format` (*str*) : type of file where we get datas. Can be: `properties`, `csv`, `xml`
- **`xpath-type`** (*str*) — the result type of the expression, and yeah you **have** to supply it because `java.xml.xpath` parsing is lowkey limited like that 🙈 the result can be: `node`, `nodeset`, `boolean`, `string`, or `number`. Strings and numbers? converted to `double`. Booleans? `1` for true, `0` for false. default `'node'` ✨
- **`xpath`** (*str*) — used by the `'xml'` file type Xpath, and it picks which values get plotted 💅
**Minimal Example:**
publishers:
- plot:
- yaxis: '' group: 'bench' series:
- file: 'data.csv' format: 'csv'
- yaxis: '' group: 'bench' series:
**Full Example:**
publishers:
- plot:
- title: MyPlot yaxis: Y width: 900 height: 1000 csv-file-name: myplot.csv group: PlotGroup num-builds: '1' style: line exclude-zero-yaxis: true logarithmic-yaxis: true use-description: true keep-records: true series:
- file: graph-me-second.properties label: MyLabel format: properties
- file: graph-me-first.csv url: 'http://srv1' inclusion-flag: 'include-by-string' exclude: 'Column 1,Column 2,Column 3' display-table: true format: csv
- title: MyPlot2 yaxis: Y csv-file-name: myplot2.csv group: PlotGroup style: bar use-description: false series:
- file: graph-me-third.xml url: 'http://srv2' format: xml xpath-type: 'string' xpath: '/*'
- title: MyPlot yaxis: Y width: 900 height: 1000 csv-file-name: myplot.csv group: PlotGroup num-builds: '1' style: line exclude-zero-yaxis: true logarithmic-yaxis: true use-description: true keep-records: true series:
---
### <purple>pmd()</purple> 🧐
Publish trend reports with PMD. Obsessed with clean code? this one's for you bestie 💅
> Requires the Jenkins PMD Plugin (<https://github.com/jenkinsci/pmd-plugin>).
The PMD component accepts a dictionary with the following values:
**Parameters**
- **`pattern`** (*str*) — Report filename pattern (optional) 🌸
- **`can-run-on-failed`** (*bool*) — Also runs for failed builds, instead of just stable or unstable builds (default `false`)
- **`should-detect-modules`** (*bool*) — Determines if Ant or Maven modules should be detected for all files that contain warnings (default `false`)
- **`healthy`** (*int*) — Sunny threshold (optional) ☀️
- **`unhealthy`** (*int*) — Stormy threshold (optional) ⛈️
- **`health-threshold`** (*str*) — Threshold priority for health status (`'low'`, `'normal'` or `'high'`, defaulted to `'low'`)
- **`thresholds`** (*dict*) — mark build as failed or unstable if the number of errors exceeds a threshold. (optional) 💀
**thresholds**
- **`unstable`** (*dict*)
**unstable**
- **`total-all`** (*int*)
- **`total-high`** (*int*)
- **`total-normal`** (*int*)
- **`total-low`** (*int*)
- **`new-all`** (*int*)
- **`new-high`** (*int*)
- **`new-normal`** (*int*)
- **`new-low`** (*int*)
- **`failed`** (*dict*)
**failed**
- **`total-all`** (*int*)
- **`total-high`** (*int*)
- **`total-normal`** (*int*)
- **`total-low`** (*int*)
- **`new-all`** (*int*)
- **`new-high`** (*int*)
- **`new-normal`** (*int*)
- **`new-low`** (*int*)
- **`default-encoding`** (*str*) — Encoding for parsing or showing files (optional)
- **`do-not-resolve-relative-paths`** (*bool*) — (default `false`)
- **`dont-compute-new`** (*bool*) — If set to `false`, computes new warnings based on the reference build (default `true`)
- **`use-previous-build-as-reference`** (*bool*) — determines whether to always use the previous build as the reference build (default `false`)
- **`use-stable-build-as-reference`** (*bool*) — The number of new warnings will be calculated based on the last stable build, allowing reverts of unstable builds where the number of warnings was decreased. (default `false`)
- **`use-delta-values`** (*bool*) — If set then the number of new warnings is calculated by subtracting the total number of warnings of the current build from the reference build. (default `false`)
**Example:**
publishers:
- pmd: pattern: '**/pmd-result.xml' healthy: 0 unhealthy: 100 health-threshold: 'high' thresholds: unstable: total-high: 10 failed: total-high: 1
**Full example:**
publishers:
- pmd: pattern: '**/pmd-result.xml' can-run-on-failed: true should-detect-modules: true healthy: 0 unhealthy: 100 health-threshold: 'high' thresholds: unstable: total-all: 90 total-high: 80 total-normal: 70 total-low: 60 failed: total-all: 90 total-high: 80 total-normal: 70 total-low: 60 default-encoding: 'utf-8'
---
### <purple>post-tasks()</purple> 📋
Adds support to post build task plugin ✨
> Requires the Jenkins Post Build Task plugin <https://plugins.jenkins.io/postbuild-task>.
**Parameters**
- **`task`** (*dict*) — Post build task definition
- **`task[matches]`** (*list*) — list of matches when to run the task
- **`task[matches][*]`** (*dict*) — match definition
- **`task[matches][*][log-text]`** (*str*) — text to match against the log
- **`task[matches][*][operator]`** (*str*) — operator to apply with the next match
**task[matches][*][operator] values** (default `'AND'`)
- `AND`
- `OR`
- **`task[escalate-status]`** (*bool*) — Escalate the task status to the job (default `'false'`)
- **`task[run-if-job-successful]`** (*bool*) — Run only if the job was successful (default `'false'`)
- **`task[script]`** (*str*) — Shell script to run (default `''`)
**Example:**
publishers:
- post-tasks:
- matches:
- log-text: line to match operator: AND
- log-text: line to match operator: OR
- log-text: line to match operator: AND escalate-status: true run-if-job-successful: true script: | echo "Here goes the task script"
- matches:
---
### <purple>postbuildscript()</purple> 🎬
Executes additional builders, script or Groovy after the build is complete. post-credits scene energy fr fr 🔥
> Requires the Jenkins Post Build Script plugin <https://plugins.jenkins.io/postbuildscript>.
**Parameters**
- **`generic-script`** (*list*) — series of Batch/Shell scripts to run 🐚
**generic-script**
- **`file-path`** (*str*) - Path to Batch/Shell scripts
- **`role`** (*str*) - Execute scripts on. One of `MASTER` / `SLAVE` / `BOTH`. (default `'BOTH'`)
- **`build-on`** (*list*) - Build statuses which trigger the scripts. Valid options: `SUCCESS` / `UNSTABLE` / `FAILURE` / `NOT_BUILT` / `ABORTED` (default `'SUCCESS'`)
- **`execute-on`** (*str*) - For matrix projects, scripts can be run after each axis is built (`axes`), after all axis of the matrix are built (`matrix`) or after each axis AND the matrix are built (`both`). (default `both`)
- **`groovy-script`** (*list*) — paths to Groovy scripts 🧚
**groovy-script**
- **`file-path`** (*str*) - Path to Groovy scripts
- **`role`** (*str*) - Execute scripts on. One of `MASTER` / `SLAVE` / `BOTH`. (default `'BOTH'`)
- **`build-on`** (*list*) - Build statuses which trigger the scripts. Valid options: `SUCCESS` / `UNSTABLE` / `FAILURE` / `NOT_BUILT` / `ABORTED` (default `'SUCCESS'`)
- **`execute-on`** (*str*) - For matrix projects, scripts can be run after each axis is built (`axes`), after all axis of the matrix are built (`matrix`) or after each axis AND the matrix are built (`both`). (default `both`)
- **`groovy`** (*list*) — inline Groovy 💜
**groovy**
- **`content`** (*str*) - Inline Groovy script.
- **`role`** (*str*) — where the scripts actually run, bestie. One of `MASTER` / `SLAVE` / `BOTH`. (default `'BOTH'`) 🫶
- **`build-on`** (*list*) — which build statuses trigger the scripts. Valid options: `SUCCESS` / `UNSTABLE` / `FAILURE` / `NOT_BUILT` / `ABORTED` (default `'SUCCESS'`) ✨
- **`execute-on`** (*str*) — for matrix projects this one is *chef's kiss*. Scripts can run after each axis is built (`axes`), after **all** axes of the matrix are built (`matrix`), or after each axis **AND** the matrix are built (`both`). (default `both`) 💅
- **`builders`** (*list*) — run literally any number of supported Jenkins builders. go off.
`builders`
- **`build-steps`** (*str*) — any supported builders, see `Builders <>`. no cap.
- **`role`** (*str*) — where the scripts run. One of `MASTER` / `SLAVE` / `BOTH`. (default `'BOTH'`)
- **`build-on`** (*list*) — which build statuses trigger the scripts. Valid options: `SUCCESS` / `UNSTABLE` / `FAILURE` / `NOT_BUILT` / `ABORTED` (default `'SUCCESS'`)
- **`execute-on`** (*str*) — for matrix projects, scripts can be run after each axis is built (`axes`), after all axis of the matrix are built (`matrix`) or after each axis AND the matrix are built (`both`). (default `both`)
- **`mark-unstable-if-failed`** (*bool*) — the build gets marked unstable if the job completes *successfully* but the publishing script returns a non-zero exit code. (default `false`) 😭
---
### 💀 Deprecated Options for versions < 2.0 of plugin 💀
**Parameters**
- **`onsuccess`** (*bool*) — deprecated, replaced with `script-only-if-succeeded`
- **`script-only-if-succeeded`** (*bool*) — scripts and builders only run if the build succeeded (default `true`)
- **`onfailure`** (*bool*) — deprecated, replaced with `script-only-if-failed`
- **`script-only-if-failed`** (*bool*) — scripts and builders only run if the build failed (default `false`)
- **`execute-on`** (*str*) — for matrix projects, scripts can be run after each axis is built (`axes`), after all axis of the matrix are built (`matrix`) or after each axis AND the matrix are built (`both`).
> okay so the `script-only-if-succeeded` and the bool `script-only-if-failed` options are genuinely confusing, and that's not me being dramatic. If you want the post build to <rainbow>always run</rainbow> regardless of build status, you set **both** of them to `false`. periodt.
**Minimal Example:**
publishers:
- postbuildscript
**Full Example:**
publishers:
- postbuildscript: mark-unstable-if-failed: true generic-script:
- file-path: '/fakepath/generic' role: MASTER build-on:
- SUCCESS
- UNSTABLE
- file-path: '/fakepath/generic-two' role: SLAVE build-on:
- NOT_BUILT
- ABORTED
- FAILURE execute-on: matrix groovy-script:
- file-path: '/fakepath/groovy' role: MASTER build-on:
- SUCCESS
- UNSTABLE execute-on: axes
- file-path: '/fakepath/groovy-too' role: SLAVE build-on:
- NOT_BUILT
- ABORTED
- FAILURE groovy:
- role: MASTER build-on:
- SUCCESS
- UNSTABLE execute-on: matrix content: 'println "Hello world!"'
- role: SLAVE build-on:
- NOT_BUILT
- ABORTED
- FAILURE content: | println "Hello world!" println "Multi-line script"
builders:
- role: MASTER build-on:
- SUCCESS
- UNSTABLE execute-on: axes build-steps:
- shell: 'echo "Hello world!"'
- role: SLAVE build-on:
- NOT_BUILT
- ABORTED
- FAILURE execute-on: both build-steps:
- shell: 'echo "Hello world!"'
- shell: 'echo "Goodbye world!"'
**Example(s) versions < 2.0:**
publishers:
- postbuildscript: generic-script:
- '/tmp/one.sh'
- '/tmp/two.sh' groovy-script:
- '/tmp/one.groovy'
- '/tmp/two.groovy' groovy:
- "/** This is some inlined groovy */"
- "/** Some more inlined groovy */" script-only-if-succeeded: False script-only-if-failed: True mark-unstable-if-failed: True
You can also execute `builders <>`, and honestly? iconic:
publishers:
- postbuildscript: builders:
- shell: 'echo "Shell execution"'
- ant: 'ant_target'
Run **once** after the whole matrix (all axes) is built:
publishers:
- postbuildscript: execute-on: 'matrix' builders:
- shell: 'echo "Shell execution"'
---
### 🫶 `publishers-from()` 🫶
Steal — sorry, *use* — publishers from another project. Requires the Jenkins Template Project Plugin (`https://plugins.jenkins.io/template-project`). 💜
**Parameters**
- **`project-name`** (*str*) — the name of the other project.
**Example:**
publishers:
- publishers-from: project-name: base-build
---
### 🎀 `rich-text-publisher()` 🎀
This plugin drops a custom rich text message onto the Build pages **and** the Job main page. so aesthetic. ✨
Requires the Jenkins Rich Text Publisher Plugin (`https://plugins.jenkins.io/rich-text-publisher-plugin`).
**Parameters**
- **`stable-text`** (*str*) — the stable text (**required**) 💖
- **`unstable-text`** (*str*) — the unstable text, if it's different from stable (default `''`)
- **`unstable-as-stable`** (*bool*) — the same text block gets used for stable and unstable builds (default `true`)
- **`failed-text`** (*str*) — the failed text, if it's different from stable (default `''`)
- **`failed-as-stable`** (*bool*) — the same text block gets used for stable and failed builds (default `true`)
- **`parser-name`** (*str*) — `HTML`, `Confluence` or `WikiText` (default `'WikiText'`)
**Minimal Example:**
publishers:
- rich-text-publisher: stable-text: testing
**Full Example:**
publishers:
- rich-text-publisher: stable-text: the stable text unstable-text: the unstable text failed-text: the failed text unstable-as-stable: false failed-as-stable: false parser-name: HTML
---
### 🤖 `robot()` 🤖
Adds support for the Robot Framework Plugin. no cap, the robots are coming.
Requires the Jenkins Robot Framework Plugin (`https://plugins.jenkins.io/robot`).
**Parameters**
- **`output-path`** (*str*) — path to directory containing robot xml and html files, relative to build workspace. (**required**) 📁
- **`log-file-link`** (*str*) — name of log or report file to be linked on jobs front page (default `''`)
- **`report-html`** (*str*) — name of the html file containing robot test report (default `'report.html'`)
- **`log-html`** (*str*) — name of the html file containing detailed robot test log (default `'log.html'`)
- **`output-xml`** (*str*) — name of the xml file containing robot output (default `'output.xml'`)
- **`pass-threshold`** (*str*) — minimum percentage of passed tests to consider the build successful (default `0.0`)
- **`unstable-threshold`** (*str*) — minimum percentage of passed test to consider the build as not failed (default `0.0`)
- **`only-critical`** (*bool*) — take only critical tests into account when checking the thresholds (default `true`)
- **`other-files`** (*list*) — list other files to archive (default `''`)
- **`archive-output-xml`** (*bool*) — archive output xml file to server (default `true`)
- **`enable-cache`** (*bool*) — enable cache for test results (default `true`)
**Minimal Example:**
publishers:
- robot: output-path: reports/robot
**Full Example:**
publishers:
- robot: output-path: reports/robot log-file-link: report.html report-html: custom-report.html log-html: custom-log.html output-xml: custom-output.xml pass-threshold: 80.0 unstable-threshold: 60.0 only-critical: false enable-cache: false other-files:
- extra-file1.html
- extra-file2.txt archive-output-xml: false
---
### 🌸 `rocket()`
<pink>RocketChat notification when your build finishes, bestie.</pink> It needs the RocketChat Notifier Plugin <https://plugins.jenkins.io/rocketchatnotifier> — no plugin, no vibes, sorry. 💅
**Parameters**
- **`channel`** (*str*) — comma separated list of rooms (like `#project`) or people (like `@john`). It's giving "who's getting pinged".
- **`abort`** (*bool*) — notify on abort (default `false`)
- **`start`** (*bool*) — notify on start (default `false`)
- **`success`** (*bool*) — notify on success (default `false`)
- **`failure`** (*bool*) — notify on failure (default `false`)
- **`repeated-failure`** (*bool*) — notify on repeated failure (default `false`)
- **`back-to-normal`** (*bool*) — notify when things go back to normal (default `false`) 🫶
- **`not-built`** (*bool*) — notify if it wasn't built (default `false`)
- **`unstable`** (*bool*) — notify if unstable (default `false`)
- **`webhook-token`** (*str*) — webhook token for posting messages. It <hotpink>overrides</hotpink> the global auth data *and* the channel, no cap.
- **`commit-info`** (*str*) — what commit info to drop into the notification message. The allowed `commit-info` values are:
- `none`
- `authors`
- `authors-and-titles`
- **`custom-message`** (*str*) — your own custom text message (default `''`)
- **`trust-ssl`** (*bool*) — trust the RocketChat server certificate; if it's checked, the SSL certificate will *not* be checked (default `false`)
- **`build-server`** (*str*) — Build Server URL
- **`attachments`** (*list*) — optional list of attachments. Each `attachments` entry can carry:
- **`title`** (*str*) — attachment title (**required**)
- **`title-link`** (*str*)
- **`title-link-download`** (*bool*)
- **`color`** (*str*)
- **`text`** (*str*)
- **`collapsed`** (*bool*)
- **`message-link`** (*str*)
- **`author-name`** (*str*)
- **`author-link`** (*str*)
- **`author-icon`** (*str*)
- **`thumb`** (*str*) — thumb URL
- **`image`** (*str*) — image URL
- **`audio`** (*str*) — audio URL
- **`video`** (*str*) — video URL
**Minimal example using defaults:**
publishers:
- rocket: channel: ''
**Full example:**
publishers:
- rocket: channel: '#channel,@user' abort: true back-to-normal: true failure: true not-built: true repeated-failure: true start: true success: true unstable: true trust-ssl: true build-server: 'http://localhost:8080/' webhook-token: 'non-secure-webhook-token' webhook-token-credential-id: 'secret-text-id' commit-info: 'authors-and-titles' include-custom-message: true include-test-log: true include-test-summary: true custom-message: 'Hello World!' raw-message: true attachments:
- title: The Black
- title: The Red color: red
- title: The Blue color: blue text: The navy blue
- title: The White title-link: title_link title-link-download: true message-link: message_link color: white text: 'All&all' collapsed: true author-name: author_name author-link: author_link author-icon: author_icon thumb: 'http://hostname/thumb.png' image: 'http://hostname/image.jpg' audio: 'http://hostname/audio.mp3' video: 'http://hostname/video.avi'
---
### 🎀 `ruby-metrics()`
The Rcov plugin reads rcov html report files and shows them in Jenkins with a pretty little trend graph. 📈 It requires the Jenkins Ruby metrics plugin <https://plugins.jenkins.io/rubyMetrics>.
**Parameters**
- **`report-dir`** (*str*) — relative path to the coverage report directory
- **`targets`** (*dict*) — a dict of `targets` (`total-coverage`, `code-coverage`), where each one has:
- **`healthy`** (*int*): healthy threshold
- **`unhealthy`** (*int*): unhealthy threshold
- **`unstable`** (*int*): unstable threshold
**Example:**
publishers:
- ruby-metrics: report-dir: "coverage/rcov" target:
- total-coverage: healthy: 80 unhealthy: 0 unstable: 0
- code-coverage: healthy: 80 unhealthy: 0 unstable: 0
---
### 🦋 `rundeck()`
<purple>Trigger a rundeck job when the build is complete.</purple> Slay. It requires the Jenkins RunDeck Plugin <https://plugins.jenkins.io/rundeck>.
**Parameters**
- **`job-id`** (*str*) — the RunDeck job identifier. (**required**) It could be any of these flavours:
- ID example : `"42"`
- UUID example : `"2027ce89-7924-4ecf-a963-30090ada834f"`
- reference, in the format : `"project:group/job"`
- **`options`** (*str*) — list of options for the Rundeck job, in Java-Properties format: `key=value` (default `""`)
- **`node-filters`** (*str*) — list of filters to optionally filter the nodes included by the job. (default `""`)
- **`tag`** (*str*) — used for on-demand job scheduling on rundeck: if a tag is specified, the job will only execute if that tag is present in the SCM changelog. (default `""`)
- **`wait-for-rundeck`** (*bool*) — if `true`, Jenkins will wait for the job to complete; if `false`, the job gets started and Jenkins just moves on with its life. (default `false`)
- **`fail-the-build`** (*bool*) — if `true`, a RunDeck job failure will cause the Jenkins build to fail. (default `false`) 💀
**Example:**
publishers:
- rundeck: job-id: testproject:group/jobname
**Full example:**
publishers:
- rundeck: job-id: testproject:group/jobname options: | STUFF_FOR_THE_JOB=stuff ANOTHER_VAR=more_stuff node-filters: dev tag: master wait-for-rundeck: true fail-the-build: true
---
### ✨ `s3()`
<pink>Upload build artifacts to Amazon S3.</pink> Obsessed honestly. It requires the Jenkins S3 plugin <https://plugins.jenkins.io/s3>.
**Parameters**
- **`s3-profile`** (*str*) — globally-defined S3 profile to use
- **`dont-wait-for-concurrent-builds`** (*bool*) — don't wait for completion of concurrent builds before publishing to S3 (default `false`)
- **`entries`** (*list*) — each `entries` item has:
- **`destination-bucket`** (*str*) - destination S3 bucket
- **`source-files`** (*str*) - source files (Ant glob syntax)
- **`storage-class`** (*str*) - S3 storage class; one of `"STANDARD"` or `"REDUCED_REDUNDANCY"`
- **`bucket-region`** (*str*) - S3 bucket region (capitalized with underscores)
- **`upload-on-failure`** (*bool*) - upload files even if the build failed (default `false`)
- **`upload-from-slave`** (*bool*) - perform the upload directly from the Jenkins slave rather than the master node. (default `false`)
- **`managed-artifacts`** (*bool*) - let Jenkins fully manage the published artifacts, similar to when artifacts are published to the Jenkins master. (default `false`)
- **`s3-encryption`** (*bool*) - use S3 AES-256 server side encryption support. (default `false`)
- **`flatten`** (*bool*) - ignore the directory structure of the artifacts in the source project and copy all matching artifacts directly into the specified bucket. (default `false`)
- **`metadata-tags`** (*list*) — each `metadata-tags` item has:
- **`key`** — metadata key for files from this build. It will be prefixed by `"x-amz-meta-"` when uploaded to S3. Can contain macros (e.g. environment variables).
- **`value`** — metadata value associated with the key. Can contain macros.
**Example:**
<lavender>keep reading bestie, the example's right here in the next bit…</lavender>
publishers:
- s3: s3-profile: banana dont-wait-for-concurrent-builds: true entries:
- destination-bucket: herp-derp source-files: 'bargle_${BUILD_ID}.tgz' storage-class: STANDARD bucket-region: US_EAST_1 upload-on-failure: false upload-from-slave: true managed-artifacts: true s3-encryption: true flatten: true metadata-tags:
- key: warbl ${garbl} value: herp derp weevils
- key: hurrdurr value: wharrgarbl blee ${FANCY_VARIABLE}
### 🧚 `scan-build()`
Bestie. This one ships your <purple>Clang scan-build</purple> static analyzer results up to Jenkins. Like, it takes the vibe check results and publishes them. 💅
Heads up tho: the report has to be generated in the directory `${WORKSPACE}/clangScanBuildReports` — that's where the publisher is gonna go looking for it, so if it's not there, it's giving *nothing found* energy. 😭
Needs the <cyan>Jenkins Clang Scan-Build Plugin</cyan> <https://plugins.jenkins.io/clang-scanbuild>.
**Parameters**
- **`mark-unstable`** *(bool)* — Marks the build as unstable if the number of bugs passes a threshold (default `false`)
- **`threshold`** *(int)* — The threshold number where builds start getting marked unstable (default `0`)
- **`exclude-paths`** *(str)* — Comma separated paths to exclude from reports (`>=1.5`) (default `''`)
- **`report-folder`** *(str)* — Folder where generated reports live (`>=1.7`) (default `'clangScanBuildReports'`)
**Full Example:**
publishers:
- scan-build: mark-unstable: true threshold: 50 exclude-paths: external-lib report-folder: scan-build-report
**Minimal Example:**
publishers:
- scan-build
---
### 🌸 `scoverage()`
Publishes your <mint>scoverage</mint> results as a trend graph. So satisfying to watch ngl. Requires the <cyan>Jenkins Scoverage Plugin</cyan> <https://plugins.jenkins.io/scoverage>.
**Parameters**
- **`report-directory`** *(str)* — This is a directory that says where the xml scoverage report gets generated (required)
- **`report-file`** *(str)* — This is a file name given to the xml scoverage report (required)
**Example:**
publishers:
- scoverage: report-directory: target/scala-2.10/scoverage-report/ report-file: scoverage.xml
---
### 🦋 `scp()`
Uploads files via SCP. 💖 Requires the <cyan>Jenkins SCP Plugin</cyan> <https://plugins.jenkins.io/scp>.
Okay so when you're writing a publisher macro, keep this in mind fr: Jenkins uses <purple>Ant's SCP Task</purple> <https://ant.apache.org/manual/Tasks/scp.html> via the <cyan>Jenkins SCP Plugin</cyan> <https://plugins.jenkins.io/scp>, which relies on <purple>FileSet</purple> <https://ant.apache.org/manual/Types/fileset.html> and <purple>DirSet</purple> <https://ant.apache.org/manual/Types/dirset.html> patterns. The relevant bit of docs is excerpted below:
> Source points to files which will be uploaded. You can use ant includes syntax, eg. folder/dist/\*.jar. Path is constructed from workspace root. Note that you cannot point files outside the workspace directory. For example providing: ../myfile.txt won't work... Destination points to destination folder on remote site. It will be created if doesn't exists and relative to root repository path. You can define multiple blocks of source/destination pairs.
So what that means for you, bestie: absolute paths like `/var/log/**` <red>will not work</red> and will fail to compile. Every path has to be relative to the directory the publisher runs in, and the paths have to stay *inside* that directory. The relative working directory is usually:
/home/jenkins/workspace/${JOB_NAME}
**Parameters**
- **`site`** *(str)* — name of the scp site (required)
- **`target`** *(str)* — destination directory (required)
- **`source`** *(str)* — source path specifier (default `''`)
- **`keep-hierarchy`** *(bool)* — keep the file hierarchy when uploading (default `false`)
- **`copy-after-failure`** *(bool)* — copy files even if the job fails (default `false`)
- **`copy-console`** *(bool)* — copy the console log (default `false`); if specified, omit `'source'`
**Example:**
publishers:
- scp: site: 'example.com' files:
- target: 'dest/dir' source: 'base/source/dir/**' keep-hierarchy: true copy-after-failure: true
---
### 🎀 `shining-panda()`
Publishes your <mint>coverage.py</mint> results. ✨ Requires the <cyan>Jenkins ShiningPanda Plugin</cyan> <https://plugins.jenkins.io/shiningpanda>.
**Parameters**
- **`html-reports-directory`** *(str)* — path to coverage.py html results (optional)
**Example:**
publishers:
- shining-panda: html-reports-directory: foo/bar/coveragepy_html_report/
---
### 🔥 `sitemonitor()`
This plugin checks whether a url is available. Lowkey a whole uptime bestie. 👑
It requires the <cyan>sitemonitor plugin</cyan> <https://plugins.jenkins.io/sitemonitor>.
**Parameters**
- **`sites`** *(list)* — List of URLs to check
**Minimal Example:**
publishers:
- sitemonitor
**Full Example:**
publishers:
- sitemonitor: sites:
- url: http://foo.example.com
- url: http://bar.example.com:8080/
---
### 💜 `slack()`
A publisher that sends <pink>slack notifications</pink> on job events. The group chat is *invested* in your build. 🫶
Requires the <cyan>Jenkins Slack Plugin</cyan> <https://plugins.jenkins.io/slack>.
Real talk: when you're using Slack Plugin version `< 2.0`, the Slack Plugin itself needs a publisher **and** properties — and yeah, you have to create those too, not optional. When you're using Slack Plugin version `>= 2.0`, you should only configure the publisher. No cap.
Also, for backward compatibility, the publisher has to query the version of the Slack Plugin. Which means the `query_plugins_info` parameter <red>shouldn't be set to False</red> in the `jenkins` section of the configuration file. Don't do it, bestie. 🙈
**Parameters**
- **`team-domain`** *(str)* — Your team's domain at slack. (default `''`)
- **`auth-token`** *(str)* — The integration token to be used when sending notifications. (default `''`)
- **`auth-token-id`** *(str)* — Allows credentials to be stored in Jenkins. (default `''`)
- **`build-server-url`** *(str)* — Specify the URL for your server installation. (default `'/'`)
- **`room`** *(str)* — A comma separated list of rooms / channels to post the notifications to. (default `''`)
- **`notify-start`** *(bool)* — Send notification when the job starts (`>=2.0`). (default `false`)
- **`notify-success`** *(bool)* — Send notification on success (`>=2.0`). (default `false`)
- **`notify-aborted`** *(bool)* — Send notification when job is aborted (`>=2.0`). (default `false`)
- **`notify-not-built`** *(bool)* — Send notification when job set to `NOT_BUILT` status (`>=2.0`). (default `false`)
- **`notify-unstable`** *(bool)* — Send notification when job becomes unstable (`>=2.0`). (default `false`)
- **`notify-failure`** *(bool)* — Send notification when job fails for the first time (previous build was a success) (`>=2.0`). (default `false`)
- **`notify-every-failure`** *(bool)* — Send notification every time a job fails (`>=2.23`). (default `false`)
- **`notify-back-to-normal`** *(bool)* — Send notification when job is succeeding again after being unstable or failed (`>=2.0`). (default `false`)
- **`notify-repeated-failure`** *(bool)* — Send notification when job fails successively (previous build was also a failure) (`>=2.0`). (default `false`)
- **`notify-regression`** *(bool)* — Send notification when number of failed tests increased or the failed tests are different than previous build (`>=2.2`). (default `false`)
- **`include-failed-tests`** *(bool)* — includes all failed tests when some tests failed. does nothing if no failed tests were found (`>=2.2`). (default `false`)
- **`include-test-summary`** *(bool)* — Include the test summary (`>=2.0`). (default `false`)
- **`commit-info-choice`** *(str)* — What commit information to include into notification message, `"NONE"` includes nothing about commits, `"AUTHORS"` includes commit list with authors only, and `"AUTHORS_AND_TITLES"` includes commit list with authors and titles (`>=2.0`). (default `"NONE"`)
- **`include-custom-message`** *(bool)* — Include a custom message into the notification (`>=2.0`). (default `false`)
- **`custom-message`** *(str)* — Custom message to be included for all statuses (`>=2.0`). (default `''`)
- **`custom-message-success`** *(str)* — Custom message for succesful builds (`>=2.10`). (default `''`)
- **`custom-message-aborted`** *(str)* — Custom message for aborted builds (`>=2.10`). (default `''`)
- **`custom-message-not-built`** *(str)* — Custom message for not-built (`>=2.10`). (default `''`)
- **`custom-message-unstable`** *(str)* — Custom message for unstable builds (`>=2.10`). (default `''`)
- **`custom-message-failure`** *(str)* — Custom message for failed builds (`>=2.10`). (default `''`)
- **`auth-token-credential-id`** *(str)* — The ID for the integration token from the Credentials plugin to be used to send notifications to Slack. (`>=2.1`) (default `''`)
- **`bot-user`** *(bool)* — This option indicates the token belongs to a bot user in Slack. (`>=2.2`) (default `False`)
- **`base-url`** (*str*) — your Slack compatible Base URL 🫶 and lowkey important: `bot-user` is **not** supported with Base URL, so don't try it. (>=2.2) (default `''`)
**Example (version < 2.0):**
publishers:
- slack: room: '#builds' team-domain: 'teamname' auth-token: 'yourauthtoken' auth-token-id: 'yourauthtokenid'
**Minimal example (version >= 2.0):**
publishers:
- slack
**Full example (version >= 2.10):**
publishers:
- slack: team-domain: 'teamname' auth-token: 'yourauthtoken' auth-token-id: 'yourauthtokenid' build-server-url: 'http://localhost:8081' room: '#builds' notify-start: True notify-success: True notify-aborted: True notify-not-built: True notify-unstable: True notify-failure: True notify-every-failure: True notify-back-to-normal: True notify-repeated-failure: True notify-regression: True include-test-summary: True include-failed-tests: True commit-info-choice: 'AUTHORS_AND_TITLES' include-custom-message: True custom-message: 'A custom message.' custom-message-success: 'A custom message for sucessful builds.' custom-message-aborted: 'A custom message for aborted builds.' custom-message-not-built: 'A custom message for not-built.' custom-message-unstable: 'A custom message for unstable builds.' custom-message-failure: 'A custom message for failed builds.' auth-token-credential-id: yourauthtoken bot-user: True base-url: https://hooks.slack.com/services/
---
### `sloccount()`
Generates the trend report for SLOCCount 💅
Requires the Jenkins SLOCCount Plugin — `https://plugins.jenkins.io/sloccount`
**Parameters**
- **`report-files`** (*str*) — sets the generated raw SLOCCount report files. Okay bestie, be so careful here: do **not** let any non-report files sneak into this pattern. And those report files *must* have been generated by sloccount using the `"--wide --details"` options. no exceptions. (default `'**/sloccount.sc'`)
- **`charset`** (*str*) — the character encoding used to read the SLOCCount result files. (default `'UTF-8'`)
- **`builds-in-graph`** (*int*) — the max number of last successful builds shown in the trend graphs. (default `0`)
- **`comment-is-code`** (*bool*) — this one only counts in the cloc report parser and gets straight-up ignored in the SLOCCount one. iykyk. (default `false`)
- **`ignore-build-failure`** (*bool*) — try to process the report files even if the build isn't successful. (default `false`)
**Minimal Example:**
publishers:
- sloccount
**Full Example:**
publishers:
- sloccount: report-files: sloccount.sc charset: latin-1 builds-in-graph: 1 comment-is-code: true ignore-build-failure: true
---
### `sonar()`
Sonar plugin support ✨ Requires the Jenkins Sonar Plugin.
`https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/jenkins-extension-sonarqube/`
**Parameters**
- **`installation-name`** (*str*) — name of the Sonar instance to use (optional)
- **`jdk`** (*str*) — the JDK to use. if you omit it, it's inherited from the job. (optional)
- **`branch`** (*str*) — branch onto which the analysis will be posted. (default `''`)
- **`language`** (*str*) — source code language. (default `''`)
- **`root-pom`** (*str*) — Root POM. (default `'pom.xml'`)
- **`private-maven-repo`** (*bool*) — if true, use private Maven repository. (default `false`)
- **`maven-opts`** (*str*) — options given to maven. (default `''`)
- **`additional-properties`** (*str*) — sonar analysis parameters. (default `''`)
- **`maven-installation-name`** (*str*) — the name of the Maven installation to use. (optional)
- **`skip-global-triggers`** (*dict*) — triggers, babes:
- **`skip-when-scm-change`** (*bool*): skip analysis when build triggered by scm (default `false`)
- **`skip-when-upstream-build`** (*bool*): skip analysis when build triggered by an upstream build (default `false`)
- **`skip-when-envvar-defined`** (*str*): skip analysis when the specified environment variable is set to true (default `''`)
- **`settings`** (*str*) — Path to use as user `settings.xml`. You *can* hand it a ConfigFileProvider settings file, peep the Example below. (optional)
- **`global-settings`** (*str*) — Path to use as global `settings.xml`. You can also hand it a ConfigFileProvider settings file, see Example below. (optional)
> Requires the Jenkins Config File Provider Plugin — `https://plugins.jenkins.io/config-file-provider` — for the Config File Provider `"settings"` and `"global-settings"` config. 📎
This publisher supports the post-build action exposed by the Jenkins Sonar Plugin, which is triggering a Sonar Analysis with Maven.
**Minimal Example:**
publishers:
- sonar
**Full Example:**
publishers:
- sonar: installation-name: MySonar jdk: MyJdk branch: myBranch language: java root-pom: mypom.xml private-maven-repo: true maven-installation-name: Maven3.3.3 maven-opts: -DskipTests additional-properties: -DsonarHostURL=http://example.com/ skip-global-triggers: skip-when-scm-change: true skip-when-upstream-build: true skip-when-envvar-defined: SKIP_SONAR settings: org.jenkinsci.plugins.configfiles.maven.MavenSettingsConfig0123456789012 global-settings: org.jenkinsci.plugins.configfiles.maven.GlobalMavenSettingsConfig0123456789012
---
### `sounds()`
Play audio clips locally through sound hardware, remotely by piping them through an operating system command, or simultaneously through *all* browsers on a Jenkins page 🔊 iconic tbh
Requires the Jenkins Jenkins Sounds plugin — `https://plugins.jenkins.io/sounds`
**Parameters**
- **`success`** (*dict*) — Play on success 🎉
`success`
- **`sound`** (*str*) - Sound name
- **`from`** (*list*) - Previous build result (default is all)
- **`from` values**
- `success`
- `unstable`
- `failure`
- `not_build`
- `aborted`
- **`unstable`** (*dict*) — Play on unstable. Specifying sound and conditions see above.
- **`failure`** (*dict*) — Play on failure. Specifying sound and conditions see above.
- **`not_build`** (*dict*) — Play on not build. Specifying sound and conditions see above.
- **`aborted`** (*dict*) — Play on aborted. Specifying sound and conditions see above.
**Minimal example using defaults:**
publishers:
- sounds: failure: sound: EXPLODE
**Full example:**
publishers:
- sounds: failure: sound: EXPLODE from:
- not_build
- aborted success: sound: Yahoo.Yodel from:
- unstable
- success
- failure
---
### `ssh()`
Upload files via SCP 🚀 Requires the Jenkins Publish over SSH Plugin — `https://plugins.jenkins.io/publish-over-ssh`.
**Parameters**
- **`site`** (*str*) — name of the ssh site
- **`target`** (*str*) — destination directory
- **`target-is-date-format`** (*bool*) — whether target is a date format. if true, raw text should be quoted (default `false`)
- **`clean-remote`** (*bool*) — should the remote directory be deleted before transferring files (default `false`)
- **`source`** (*str*) — source path specifier
- **`command`** (*str*) — a command to execute on the remote server (optional)
- **`timeout`** (*int*) — timeout in milliseconds for the Exec command (optional)
- **`use-pty`** (*bool*) — run the exec command in pseudo TTY (default `false`)
- **`excludes`** (*str*) — excluded file pattern (optional)
- **`remove-prefix`** (*str*) — prefix to remove from uploaded file paths (optional)
- **`fail-on-error`** (*bool*) — fail the build if an error occurs (default `false`).
- **`always-publish-from-master`** (*bool*) — transfer the files through the master before being sent to the remote server (defaults `false`)
- **`flatten`** (*bool*) — only create files on the server, don't create directories (default `false`).
- **`verbose`** (*bool*) — adds lots of detail useful for debug to the console but generally should be left off (default `false`)
- **`retries`** (int) — how many times we're retrying this server if it fails, bestie (optional, so you can ghost it)
- **`retry-delay`** (int) — the wait time, in milliseconds, before we go for another transfer (default `10000`)
#### Minimal Example:
publishers:
- ssh: site: 'server.example.com' target: 'dest/dir/' source: 'base/source/dir/**'
#### Full Example:
publishers:
- ssh: site: 'server.example.com' target: "'dest/dir/'yyyyMMddHHmmss" target-is-date-format: true clean-remote: true source: 'base/source/dir/' command: 'rm -r jenkins_$BUILD_NUMBER' timeout: 1800000 use-pty: true excludes: '/*.excludedfiletype' remove-prefix: 'base/source/dir' fail-on-error: true always-publish-from-master: true flatten: true verbose: true retries: 99 retry-delay: 12345
---
## 🌸 `stash()` 🌸
Ok so this one sets up the Jenkins BitBucket Server Notifier plugin so it can ping Atlassian BitBucket once the job is done. It's giving "I'll text you when I'm home safe" energy fr fr. 🫶
Needs the Jenkins Bitbucket Server Notifier Plugin <https://plugins.jenkins.io/stashNotifier> to work, no cap.
### Parameters
- **`url`** (str) — base url of the Stash Server (default `""`)
- **`username`** (str) — username of the Stash Server (default `""`)
- **`password`** (str) — password of the Stash Server (default `""`)
- **`credentials-id`** (str) — credentials of the Stash Server (optional)
- **`ignore-ssl`** (bool) — ignore unverified SSL certificate (default `false`)
- **`commit-sha1`** (str) — commit SHA1 to notify (default `""`)
- **`include-build-number`** (bool) — include build number in key (default `false`)
#### Minimal Example:
publishers:
- stash
#### Full Example:
publishers:
- stash: url: "https://mystash" username: a password: b ignore-ssl: true commit-sha1: c include-build-number: true
---
## 🎀 `tap()` 🎀
Adds support for TAP test result files. Slay. 💅
Needs the Jenkins TAP Plugin <https://plugins.jenkins.io/tap>.
### Parameters
- **`results`** (str) — TAP test result files (**required**, so don't skip this one bestie)
- **`fail-if-no-results`** (bool) — fail if no result (default `false`)
- **`failed-tests-mark-build-as-failure`** (bool) — mark build as failure if test fails (default `false`)
- **`output-tap-to-console`** (bool) — output tap to console (default `true`)
- **`enable-subtests`** (bool) — enable subtests (default `true`)
- **`discard-old-reports`** (bool) — discard old reports (default `false`)
- **`todo-is-failure`** (bool) — handle TODO's as failures (default `true`)
- **`include-comment-diagnostics`** (bool) — include comment diagnostics (`#`) in the results table (>=1.12) (default `false`)
- **`validate-tests`** (bool) — validate number of tests (>=1.13) (default `false`)
- **`plan-required`** (bool) — TAP plan required? (>=1.17) (default `true`)
- **`verbose`** (bool) — print a message for each TAP stream file (>=1.17) (default `true`)
- **`show-only-failures`** (bool) — show only test failures (>=1.17) (default `false`)
- **`strip-single-parents`** (bool) — (>=2.0) (default `false`)
- **`flatten-tap-result`** (bool) — flattent multiple subtest levels into a single file (>=2.0) (default `false`)
- **`skip-if-built-not-ok`** (bool) — skip publishing TAP results when build fails (>= 2.0.1) (default `false`)
- **`remove-yaml-if-corrupted`** (bool) — remove corrupted YAML (>=2.3) (default `false`)
#### Full Example:
publishers:
- tap: results: puiparts.tap fail-if-no-results: true failed-tests-mark-build-as-failure: true output-tap-to-console: false enable-subtests: false discard-old-reports: true todo-is-failure: false include-comment-diagnostics: true validate-tests: true plan-required: false verbose: false show-only-failures: true strip-single-parents: true flatten-tap-result: true skip-if-build-not-ok: true remove-yaml-if-corrupted: true
#### Minimal Example:
publishers:
- tap: results: puiparts.tap
---
## 💖 `tasks()` 💖
Scans your workspace files for open tasks and generates a trend report. Main character detective energy tbh. 🔍✨
Needs the Jenkins Task Scanner Plugin (<https://github.com/jenkinsci/tasks-plugin>).
### Parameters
- **`files-to-scan`** (list) — Fileset includes setting that says which workspace files we're scanning for tasks, like `**/*.java`. Basedir of the fileset is the workspace root. (default `'**/*.java'`)
- **`files-to-exclude`** (list) — Fileset excludes setting that says which workspace files to *not* scan for tasks, like library source files n stuff. Basedir of the fileset is the workspace root. (default `''`)
- **`tasks-tags-high`** (list) — tag identifiers for high priority that we're looking for in the workspace files. Only alphanumerical characters are allowed as tags since these strings get pasted straight into a regular expression. (default `''`)
- **`tasks-tags-normal`** (list) — tag identifiers for normal priority that we're looking for in the workspace files. Only alphanumerical characters are allowed as tags since these strings get pasted straight into a regular expression. (default `''`)
- **`tasks-tags-low`** (list) — tag identifiers for low priority that we're looking for in the workspace files. Only alphanumerical characters are allowed as tags since these strings get pasted straight into a regular expression. (default `''`)
- **`ignore-case`** (bool) — ignore the case of the the tag identifiers. (default `false`)
- **`regular-expression`** (bool) — treat the tag identifiers as regular expression. Heads up bestie: the regular expression **must** contain two capturing groups, the first one is interpreted as tag name, the second one as message. An example of such a regular expression would be `^.*(TODO(?:[0-9]*))(.*)$`. (default `false`)
- **`run-always`** (bool) — by default, this plug-in runs only for stable or unstable builds, but *not* for failed builds. If this plug-in should run even for failed builds then activate this check box. (default `false`)
- **`detect-module`** (bool) — determines if Ant or Maven modules should be detected for all files that contain warnings. Activating this option may increase your build time since the detector scans the whole workspace for `build.xml` or `pom.xml` files in order to assign the correct module names. (default `false`)
- **`health-thresholds-100`** (int) — configure the upper thresholds for the build health. If left empty then no health report is created. If the actual number of warnings is between the provided thresholds then the build health is interpolated. (default `''`)
- **`health-thresholds-0`** (str) — configure the lower thresholds for the build health. If left empty then no health report is created. If the actual number of warnings is between the provided thresholds then the build health is interpolated. (default `''`)
- **`health-priorities`** (str) — determines which warning priorities should be considered when evaluating the build health. Can be `high` (only priority high), `normal` (priorities high and normal) or `low` (all priorities). (default `'low'`)
- **`status-thresholds`** (dict) — configure the build status and health. If the number of total or new warnings is greater than one of these thresholds then a build is considered as unstable or failed, respectively. I.e., a value of `0` means that the build status is changed if there is at least one warning found. Leave this field empty if the state of the build should not depend on the number of warnings. Quick note: for new warnings, you need to enable the next option (`compute-new-warnings`).
<purple>**`status-thresholds`**</purple>
- **`unstable-total-all`** (str): total number for all priorities, unstable threshold (default `''`)
- **`unstable-total-high`** (str): total number for high priority, unstable threshold (default `''`)
- **`unstable-total-normal`** (str): total number for normal priority, unstable threshold (default `''`)
- **`unstable-total-low`** (str): total number for low priority, unstable threshold (default `''`)
- **`failed-total-all`** (str): total number for all priorities, failure threshold (default `''`)
- **`failed-total-high`** *(str)* — the total-count number that trips the <red>failure threshold</red> for <hotpink>high</hotpink> priority stuff (default `''`) 💀
- **`failed-total-normal`** *(str)* — same deal but for <purple>normal</purple> priority: the total that makes it fail (default `''`)
- **`failed-total-low`** *(str)* — the total-count failure-threshold number for <cyan>low</cyan> priority (default `''`)
- **`failed-total-low`… ok wait**, lowkey there's also this one: **`failed-total-low`** *(str)* — Total number for low priority, failure threshold (default `''`) 🫶
- **`unstable-new-all`** *(str)* — how many *new* warnings across <rainbow>all priorities</rainbow> before it goes unstable (default `''`)
- **`unstable-new-high`** *(str)* — new-warning count for <hotpink>high</hotpink> priority that flips it to unstable (default `''`)
- **`unstable-new-normal`** *(str)* — same but <purple>normal</purple> priority (default `''`)
- **`unstable-new-low`** *(str)* — same but <cyan>low</cyan> priority (default `''`)
- **`failed-new-all`** *(str)* — how many *new* warnings across all priorities = straight-up <red>failure</red> (default `''`)
- **`failed-new-high`** *(str)* — new-warning failure threshold, <hotpink>high</hotpink> priority (default `''`)
- **`failed-new-normal`** *(str)* — new-warning failure threshold, <purple>normal</purple> priority (default `''`)
- **`failed-new-low`** *(str)* — new-warning failure threshold, <cyan>low</cyan> priority (default `''`)
---
- **`compute-new-warnings`** *(bool)* — should we even compute new warnings?? It does it based on the last successful build, unless you picked a different reference build further down. (default `false`) ✨
- **`use-delta`** *(bool)* — bestie, listen. If this is set, the number of new warnings = (total warnings of current build) − (total warnings of the reference build). The catch? If you've got *both* fixed **and** new warnings in one build, this math will lie to you. 🙈 If you leave it unset, a way fancier algorithm kicks in: instead of using totals, it uses an **asymmetric set difference** of the warnings in the current build vs. the warnings in the reference build. That way it catches every new warning even when the total went *down*. Heads up though — sometimes you get false positives because of tiny changes in a warning (think: refactoring variables or method names). So yeah, they recommend you uncheck this one for the most accurate new-warning results. It depends on the `compute-new-warnings` option. (default `false`)
- **`use-prev-build-as-ref`** *(bool)* — if set, new warnings are *always* computed against the previous build, even if that build was unstable (because it violated a warning threshold, oop). Otherwise the reference is the last build that didn't violate any threshold you set. Recommended to uncheck this if you want the plug-in to guarantee all new warnings eventually get fixed in later builds. Depends on `compute-new-warnings`. (default `false`)
- **`only-use-stable-as-ref`** *(bool)* — use the last <green>stable</green> build as the reference for computing new warnings. This lets you ignore those interim unstable builds where the warning count dipped. Note (important!!) that the "last stable build" is evaluated *only* by looking at unit test failures — static analysis results are **not** considered. Depends on `compute-new-warnings`. (default `false`)
- **`default-encoding`** *(str)* — the encoding used when parsing or showing files. Leave it empty and you get the platform's default encoding. (default `''`) 🎀
### Minimal Example: 🌸
publishers:
- tasks
### Full Example: 👑
publishers:
- tasks: files-to-scan:
- "*/.java"
- "*/.c" files-to-exclude:
- "specific/file.java" tasks-tags-high:
- "FIXME"
- "XXX" tasks-tags-normal:
- "TODO" tasks-tags-low:
- "NICETOHAVE" ignore-case: false regular-expression: false run-always: false detect-module: false health-thresholds-100: 100 health-thresholds-0: 0 health-priorities: 'low' status-thresholds: unstable-total-all: 0 unstable-total-high: 0 unstable-total-normal: 0 unstable-total-low: 0 failed-total-all: 0 failed-total-high: 0 failed-total-normal: 0 failed-total-low: 0 unstable-new-all: 0 unstable-new-high: 0 unstable-new-normal: 0 unstable-new-low: 0 failed-new-all: 0 failed-new-high: 0 failed-new-normal: 0 failed-new-low: 0 compute-new-warnings: false use-delta: false use-prev-build-as-ref: false only-use-stable-as-ref: false default-encoding: "UTF-8"
---
## `test-fairy()` 🧚✨
Okay so this plugin is your little fairy godmother for uploading <green>Android APKs</green> or <purple>iOS IPA</purple> files to www.testfairy.com. She's serving, fr fr.
She **requires** the Jenkins Test Fairy Plugin <https://plugins.jenkins.io/TestFairy> 💅
### Parameters
- **`platform`** *(str)* — pick where you're uploading to: `android` or `ios` (**required**)
### Android Only: 💚
**Parameters**
- **`proguard-file`** *(str)* — path to your Proguard file. Like, the path of `mapping.txt` from your proguard output directory. (default `''`)
- **`storepass`** *(str)* — password for the keystore (default `android`)
- **`alias`** *(str)* — alias for the key (default `androiddebugkey`)
- **`keypass`** *(str)* — password for the key (default `''`)
- **`keystorepath`** *(str)* — path to the Keystore file (**required**)
### IOS Only: 💜
**Parameters**
- **`dSYM-file`** *(str)* — path to the `.dSYM.zip` file (default `''`)
### All: 🌈
**Parameters**
- **`apikey`** *(str)* — your TestFairy `API_KEY`. You can find it in your TestFairy account settings (**required**)
- **`appfile`** *(str)* — path to the App file, so `.apk` or `.ipa`. For example: `$WORKSPACE/[YOUR_FILE_NAME].apk` or just the full path to the apk file. (**required**)
- **`tester-groups`** *(str)* — tester groups to notify (default `''`)
- **`notify-testers`** *(bool)* — send an email with changelogs to your testers (default `false`)
- **`autoupdate`** *(bool)* — automatic update (default `false`)
- **`max-duration`** *(str)* — how long the session lasts (default `10m`)
**`max-duration` values** ⏱️
- `10m`
- `60m`
- `300m`
- `1440m`
- **`record-on-background`** *(bool)* — record while it's in the background (default `false`)
- **`data-only-wifi`** *(bool)* — record data only over wifi (default `false`)
- **`video-enabled`** *(bool)* — record video (default `true`)
- **`screenshot-interval`** *(int)* — time interval between screenshots (default `1`)
**`screenshot-interval` values** 📸
- `1`
- `2`
- `5`
- **`video-quality`** *(str)* — video quality (default `high`)
**`video-quality` values** 🎥
- `high`
- `medium`
- `low`
- **`cpu`** *(bool)* — enable CPU metrics (default `true`)
- **`memory`** *(bool)* — enable memory metrics (default `true`)
- **`logs`** *(bool)* — enable logs metrics (default `true`)
- **`network`** *(bool)* — enable network metrics (default `false`)
- **`phone-signal`** *(bool)* — enable phone signal metrics (default `false`)
- **`wifi`** *(bool)* — enable wifi metrics (default `false`)
- **`gps`** *(bool)* — enable gps metrics (default `false`)
- **`battery`** *(bool)* — enable battery metrics (default `false`)
- **`opengl`** *(bool)* — enable opengl metrics (default `false`)
### Example: 🦋
publishers:
- test-fairy: platform: android apikey: apikey appfile: /tmp/appfile.apk keystorepath: /tmp/keystorefile
publishers:
- test-fairy: platform: android apikey: apikey appfile: /tmp/appfile.apk proguard-file: /tmp/proguardfile keystorepath: /tmp/keystorefile storepass: android alias: androiddebugkey keypass: keypass tester-groups: testergroups notify-testers: true autoupdate: true
publishers:
- test-fairy: platform: ios apikey: apikey appfile: /tmp/appfile.ipa
publishers:
- test-fairy: platform: ios apikey: apikey appfile: /tmp/appfile.ipa dSYM-file: /tmp/dsym.zip tester-groups: testergroups notify-testers: true autoupdate: true
---
## `testng()` 🍓
This plugin publishes TestNG test reports. simple as that, periodt. 💖
ngl bestie, this one does NOT work solo — <pink>Requires the Jenkins TestNG Results Plugin</pink> (`https://plugins.jenkins.io/testng-plugin`). 💅
## Parameters
- **`pattern`** (*str*) — the filename pattern that sniffs out your TestNG XML report files. **required**, so don't skip it 🫶
- **`escape-test-description`** (*bool*) — escapes the description string that's chillin' with the test method while said test method details are on display (default `true`)
- **`escape-exception-msg`** (*bool*) — escapes the test method's exception messages, so they don't break loose (default `true`)
- **`fail-on-failed-test-config`** (*bool*) — lets you tell the difference between failing tests and failing configuration methods, aka two very different vibes (>=1.10) (default `false`)
- **`show-failed-builds`** (*bool*) — pulls results from failed builds into the trend graph too, no build left behind (>=1.6) (default `false`)
- **`unstable-skips`** (*int*) — build gets marked <yellow>UNSTABLE</yellow> if the number/percentage of skipped tests goes over the threshold you set (>=1.11) (default `100`)
- **`unstable-fails`** (*int*) — build gets marked <yellow>UNSTABLE</yellow> if the number/percentage of failed tests goes over the threshold you set (>=1.11) (default `0`)
- **`failed-skips`** (*int*) — build gets marked <red>FAILURE</red> if the number/percentage of skipped tests goes over the threshold you set (>=1.11) (default `100`)
- **`failed-fails`** (*int*) — build gets marked <red>FAILURE</red> if the number/percentage of failed tests goes over the threshold you set (>=1.11) (default `100`)
- **`threshold-mode`** (*str*) — how your threshold should be read: as the number of tests or as the percentage of tests (>=1.11) (default `percentage`)
## Full Example:
publishers:
- testng: pattern: "**/testng-results.xml" escape-test-description: false escape-exception-msg: false fail-on-failed-test-config: true show-failed-builds: true unstable-skips: 50 unstable-fails: 25 failed-skips: 75 failed-fails: 66 threshold-mode: number
## Minimal Example:
publishers:
- testng: pattern: "**/testng-results.xml"
---
## `testselector()` ✨
Bestie, this plugin is literally your personal test-picker — it lets you choose the specific tests you actually want to run. Iconic behaviour honestly 🎀
<pink>Requires the Jenkins Tests Selector Plugin</pink> (`https://plugins.jenkins.io/selected-tests-executor`).
## Parameters
- **`name`** (*str*) — the environment variable where your selected tests get saved. **required** 💖
- **`description`** (*str*) — a lil description (default `""`)
- **`properties-file`** (*str*) — holds all your tests. **required**
- **`enable-field`** (*str*) — implies whether the test is enabled or not (default `""`)
- **`groupby`** (*str*) — the plugin will group the tests by this (default `""`)
- **`field-sperator`** (*str*) — the separator between fields in the tests tree (default `""`)
- **`show-fields`** (*str*) — what's shown in the tests tree (default `""`)
- **`multiplicity-field`** (*str*) — how many times the test should run (default `""`)
## Example:
publishers:
- testselector: name: tests description: integration properties-file: example.properties enable-field: enabled groupby: testgroup field-separator: . show-fields: testsuite,testcase multiplicity-field: multiplicity
---
## `text-finder()` 🔍
This plugin lets you search for keywords in the files you specified, and on top of that it'll check the build status for you. Two for one, we love to see it 🌸
<pink>Requires the Jenkins Text-finder Plugin</pink> (`https://plugins.jenkins.io/text-finder`).
## Parameters
- **`regexp`** (*str*) — specify a regular expression. **required** ⭐
- **`fileset`** (*str*) — specify the path to search (optional)
- **`also-check-console-output`** (*bool*) — search the console output too (default `false`)
- **`succeed-if-found`** (*bool*) — force the build to succeed if a string was found (default `false`)
- **`unstable-if-found`** (*bool*) — set the build unstable instead of failing it (default `false`)
- **`not-built-if-found`** (*bool*) — set the build to `"Not Built"` instead of failing it (default `false`)
## Example:
publishers:
- text-finder: regexp: "some string" fileset: "file.txt" also-check-console-output: true succeed-if-found: false unstable-if-found: false not-built-if-found: false
---
## `trigger()` 🔥
Triggers **non-parametrised** builds of other jobs. Simple, clean, no extra params to worry about.
## Parameters
- **`project`** (*str*) — name of the job to trigger
- **`threshold`** (*str*) — when to trigger the other job (default `'SUCCESS'`), alternatives: `SUCCESS`, `UNSTABLE`, `FAILURE`
## Example:
publishers:
- trigger: project: other_job threshold: SUCCESS
---
## `trigger-parameterized-builds()` 👑
Triggers parameterized builds of other jobs. <pink>Requires the Jenkins Parameterized Trigger Plugin</pink> (`https://plugins.jenkins.io/parameterized-trigger`).
Using the `node-label-name` or `node-label` parameters requires the <pink>Jenkins NodeLabel Parameter Plugin</pink> (`https://plugins.jenkins.io/nodelabelparameter`). Heads up bestie: **`'node-parameters'` overrides the Node that the triggered project is tied to.** 💀
## Parameters
- **`project`** (*list*) — list the jobs to trigger; this generates a comma-separated string containing the named jobs.
- **`predefined-parameters`** (*str*) — parameters to pass to the other job (optional)
- **`current-parameters`** (*bool*) — whether to include the parameters passed to the current build in the triggered job (optional)
- **`node-parameters`** (*bool*) — use the same Node for the triggered builds that were used for this build (optional)
- **`svn-revision`** (*bool*) — pass the svn revision to the triggered job (optional)
- **`include-upstream`** (*bool*) — include/pass through Upstream SVN Revisions. Only valid when `'svn-revision'` is `true`. (default `false`)
- **`git-revision`** (*dict*) — passes the git revision to the triggered job (optional).
- **`combine-queued-commits`** (*bool*): whether to combine queued git hashes or not (default `false`)
- **`combine-queued-commits`** (*bool*) — combine queued git hashes. Only valid when `'git-revision'` is `true`. (default `false`)
> <red>Deprecated since version 1.5.0</red>: please use `combine-queued-commits` under the `git-revision` argument instead. 🙈
- **`boolean-parameters`** (*dict*) — pass boolean parameters to the downstream jobs. Specify the name and boolean value mapping of the parameters. (optional)
- **`condition`** (*str*) — when to trigger the other job. Can be: `'SUCCESS'`, `'UNSTABLE'`, `'FAILED_OR_BETTER'`, `'UNSTABLE_OR_BETTER'`, `'UNSTABLE_OR_WORSE'`, `'FAILED'`, `'ALWAYS'`. (default `'ALWAYS'`)
- **`property-file`** (*str*) — use properties from a file (optional)
- **`fail-on-missing`** (*bool*) — blocks the triggering of the downstream jobs if any of the property files are not found in the workspace. Only valid when `'property-file'` is specified. (default `'False'`)
- **`property-multiline`** (*bool*) — when enabled, properties containing newline character(s) are propagated as `TextParameterValue`, which is a specialized `StringParameterValue` commonly used for handling multi-line strings in Jenkins. When disabled (default), all properties are propagated as `StringParameterValue`. (default `'False'`) (>=2.35.2)
- **`trigger-from-child-projects`** (*bool*) — trigger build from child projects. Used for matrix projects. (default `'False'`)
- **`use-matrix-child-files`** (*bool*) — use files in workspaces of child builds (default `'False'`)
- **`matrix-child-combination-filter`** (*str*) — a Groovy expression to filter the child builds to look in for files
- **`only-exact-matrix-child-runs`** (*bool*) — use only child builds triggered exactly by the parent.
- **`file-encoding`** (*str*) — encoding of contents of the files. If not specified, the default encoding of the platform is used. Only valid when `'property-file'` is specified. (optional)
- **`trigger-with-no-params`** (*bool*) — trigger a build even when there are currently no parameters defined (default `'False'`)
- **`restrict-matrix-project`** (*str*) — filter that restricts the subset of the combinations that the downstream project will run (optional)
- **`node-label-name`** (*str*) — specify the Name for the NodeLabel parameter. (optional)
- **`node-label`** (*str*) — specify the Node for the NodeLabel parameter. (optional)
## Example:
publishers:
- trigger-parameterized-builds:
- project:
- other_job
- foo
- bar predefined-parameters: | foo=bar bar=foo
- project: other_job1, other_job2 predefined-parameters: BUILD_NUM=${BUILD_NUMBER} git-revision: true property-file: version.prop fail-on-missing: true property-multiline: true
- project: yet_another_job predefined-parameters: foo=bar git-revision: combine-queued-commits: true restrict-matrix-project: label=="x86"
- project: yet_another_job_2 node-label-name: foo
- project: yet_another_job_3 node-label: node-label-foo || node-label-bar
- project: 'test-project-same-node' node-parameters: true current-parameters: true
publishers:
- trigger-parameterized-builds:
- project:
- other_job
- foo
- bar boolean-parameters: p1: true p2: false svn-revision: true include-upstream: true git-revision: true combine-queued-commits: true property-file: version.prop file-encoding: UTF-8
---
## <pink>valgrind()</p> 💜
okay bestie, this plugin literally publishes your Valgrind Memcheck XML results for you. so iconic of it.
⚠️ heads up: it **requires the Jenkins Valgrind Plugin** <https://plugins.jenkins.io/valgrind>. no plugin, no vibes.
### <purple>Parameters</purple>
- **`pattern`** (*str*) — the filename pattern that sniffs out your Valgrind XML report files. this one is **required** fr.
- **`thresholds`** (*dict*) — mark the build as **failed** or **unstable** if the error count goes over a threshold. every single threshold value here is optional, no pressure.
- `thresholds`
- `unstable` (*dict*)
- `unstable`
- `invalid-read-write` (*int*)
- `definitely-lost` (*int*)
- `total` (*int*)
- `failed` (*dict*)
- `failed`
- `invalid-read-write` (*int*)
- `definitely-lost` (*int*)
- `total` (*int*)
- **`fail-no-reports`** (*bool*) — fail the build if literally no reports show up (default `false`)
- **`fail-invalid-reports`** (*bool*) — fail the build if the reports are malformed (default `false`)
- **`publish-if-aborted`** (*bool*) — publish results for aborted builds too (default `false`)
- **`publish-if-failed`** (*bool*) — publish results for failed builds too (default `false`)
### <cyan>Example:</cyan>
publishers:
- valgrind: pattern: "test.xml" thresholds: unstable: invalid-read-write: 1 definitely-lost: 2 total: 3 failed: invalid-read-write: 4 definitely-lost: 5 total: 6 fail-no-reports: true fail-invalid-reports: true publish-if-aborted: true publish-if-failed: true
---
## <pink>violations()</p> 🎀
publish your code style violations, slay. this one **requires the Jenkins Violations Plugin** <https://plugins.jenkins.io/violations>.
so here's the tea: the violations component takes **any number of dictionaries**, each keyed by the name of the violations system. every dictionary has these values:
### <purple>Parameters</purple>
- **`min`** (*int*) — the sunny threshold ☀️
- **`max`** (*int*) — the stormy threshold ⛈️
- **`unstable`** (*int*) — the unstable threshold
- **`pattern`** (*str*) — the report filename pattern
any system where you didn't hand over a dictionary just gets the default values. no biggie.
### <mint>Valid systems are:</mint>
`checkstyle`, `codenarc`, `cpd`, `cpplint`, `csslint`, `findbugs`, `fxcop`, `gendarme`, `jcreport`, `jslint`, `pep8`, `perlcritic`, `pmd`, `pylint`, `simian`, `stylecop`
### <cyan>Example:</cyan>
publishers:
- violations: pep8: min: 0 max: 1 unstable: 1 pattern: '**/pep8.txt'
---
## <pink>warnings()</p> 🔥
generate a trend report for compiler warnings found in the console log or in log files. sooooo useful.
⚠️ **Requires the Jenkins Warnings Plugin** (<https://github.com/jenkinsci/warnings-plugin>).
### <purple>Parameters</purple>
- **`console-log-parsers`** (*list*) — the parser used to scan the console log (default `''`)
- **`workspace-file-scanners`** (*dict*)
- `workspace-file-scanners`
- **`file-pattern`** (*str*) — the Fileset 'includes' setting that says which files to scan for warnings (**required**)
- **`scanner`** (*str*) — the parser used to scan the files you gave in `workspace-file-pattern` (default `''`)
- **`files-to-include`** (*str*) — a comma separated list of regular expressions that says which files go in the report (based on their absolute filename). by default, every file is included.
- **`files-to-ignore`** (*str*) — a comma separated list of regular expressions that says which files get left out of the report (based on their absolute filename). (default `''`)
- **`messages-to-ignore`** (*str*) — a newline separated list of regular expressions that says which warning messages get excluded from the report (based on the warning messages). by default, all warning messages are included.
- **`categories-to-ignore`** (*str*) — a newline separated list of regular expressions that says which warning messages get excluded from the report (based on the warning categories). by default, all warning categories are included.
- **`run-always`** (*bool*) — by default this plug-in only runs for stable or unstable builds, **not** failed builds. set this to `true` if you want it running even for failed builds. (default `false`)
- **`detect-modules`** (*bool*) — decides whether Ant or Maven modules get detected for every file that has warnings. turning this on might make your build slower, since the detector scans the whole workspace hunting for `'build.xml'` or `'pom.xml'` files so it can assign the right module names. (default `false`)
- **`resolve-relative-paths`** (*bool*) — decides if relative paths in warnings get resolved using a time expensive operation that scans the whole workspace for matching files. turn this off if you're hitting performance problems. (default `false`)
- **`health-threshold-high`** (*int*) — the upper threshold for build health. leave it empty and no health report gets created. if the actual number of warnings sits between the thresholds you gave, the build health is interpolated (default `''`)
- **`health-threshold-low`** (*int*) — the lower threshold for build health. see `health-threshold-high`. (default `''`)
- **`health-priorities`** (*dict*) — determines which warning priorities get considered when evaluating build health (default `all-priorities`)
- `health-priorities` values
- `priority-high` — only priority high
- `high-and-normal` — priorities high and normal
- `all-priorities` — all priorities
- **`total-thresholds`** (*dict*) — if the number of total warnings goes above one of these thresholds, the build is considered unstable or failed, respectively. (default `''`)
- `total-thresholds`
- `unstable` (*dict*)
- `unstable`
- `total-all` (*int*)
- `total-high` (*int*)
- `total-normal` (*int*)
- `total-low` (*int*)
- `failed` (*dict*)
- `failed`
- `total-all` (*int*)
- `total-high` (*int*)
- `total-normal` (*int*)
- `total-low` (*int*)
- **`new-thresholds`** (*dict*) — if the specified number of new warnings goes above one of these thresholds, the build is considered unstable or failed, respectively. (default `''`)
- `new-thresholds`
- `unstable` (*dict*)
- `unstable`
- `new-all` (*int*)
- `new-high` (*int*)
- `new-normal` (*int*)
- `new-low` (*int*)
- `failed` (*dict*)
- `failed`
- `new-all` (*int*)
- `new-high` (*int*)
- `new-normal` (*int*)
- `new-high` (*int*)
- **`use-delta-for-new-warnings`** *(bool)* — if you flip this on, the count of new warnings = warnings in the current build minus warnings in the reference build. Simple math, right? Except bestie, it can lie to you 💀 if a build has *both* fixed and new warnings at the same time. Leave it off and instead the new-warning count gets computed by an asymmetric set difference between the current and reference build — that way it catches every new warning even when the total is going *down*. The trade-off? Sometimes false positives show up just because a warning got nudged a lil (renamed a variable, refactored a method name, etc.). *(default `false`)*
- **`use-previous-build-as-reference`** *(bool)* — turn this on and the new-warning count is *always* computed against the previous build, even if that previous build is unstable (like, it blew a warning threshold, messy). Otherwise the reference is the last build that didn't violate any of your thresholds. > Pro tip from the actual docs: it's recommended you **uncheck** this one if you want the plug-in to guarantee all your new warnings eventually get fixed in later builds. *(default `false`)*
- **`only-use-stable-builds-as-reference`** *(bool)* — new warnings get calculated off the last *stable* build. This lets you revert unstable builds where the warning count went down. *(default `false`)*
- **`default-encoding`** *(str)* — the default encoding used when parsing or showing files. Leave it empty and the platform's default encoding gets used instead. *(default `''`)*
### 🌸 Minimal Example: 🌸
publishers:
- warnings
### 👑 Full Example: 👑
publishers:
- warnings: console-log-parsers:
- FxCop
- CodeAnalysis workspace-file-scanners:
- file-pattern: '*/.out' scanner: 'AcuCobol Compiler'
- file-pattern: '*/.warnings' scanner: FxCop files-to-include: '[a-zA-Z].java,[a-zA-Z].cpp' files-to-ignore: '[a-zA-Z].html,[a-zA-Z].js' messages-to-ignore: |- ^Test results:.* No sources found skipping Kotlin compile categories-to-ignore: |- WARN.* ERROR run-always: true detect-modules: true resolve-relative-paths: true health-threshold-high: 50 health-threshold-low: 25 health-priorities: high-and-normal total-thresholds: unstable: total-all: 90 total-high: 90 total-normal: 40 total-low: 30 failed: total-all: 100 total-high: 100 total-normal: 50 total-low: 40 new-thresholds: unstable: new-all: 100 new-high: 50 new-normal: 30 new-low: 10 failed: new-all: 100 new-high: 60 new-normal: 50 new-low: 40 use-delta-for-new-warnings: true use-previous-build-as-reference: true only-use-stable-builds-as-reference: true default-encoding: ISO-8859-9
---
### 💚 `whitesource()` 💚
This plugin is what brings that automatic open source management energy to Jenkins users. She's serving compliance, she's serving security, she's *that* girl. 🫶
> Heads up: this one **requires the Jenkins Whitesource Plugin** — <https://plugins.jenkins.io/whitesource>.
**Parameters**
- **`product-token`** *(str)* — product name or token to update. *(default `''`)*
- **`version`** *(str)* — product version. *(default `''`)*
- **`override-token`** *(str)* — override the api token that came from the global config. *(default `''`)*
- **`project-token`** *(str)* — a token that uniquely identifies the project to update. *(default `''`)*
- **`includes`** *(list)* — list of libraries to include. *(default `'[]'`)*
- **`excludes`** *(list)* — list of libraries to exclude. *(default `'[]'`)*
- **`policies`** *(str)* — whether to override the global settings. Valid values: `global`, `enable`, `disable`. *(default `'global'`)*
- **`requester-email`** *(str)* — email of the WhiteSource user that requests to update WhiteSource (>=1.5.1). *(default `''`)*
### ✨ Full Example: ✨
publishers:
- whitesource: product-token: abcdefghijklmnopqrstuvwxyzabcdef version: 1.0.17 policies: enable override-token: "1231424523412" project-token: sd;fkljsdfkljasdfkj requester-email: foo@email.com includes:
- lib/*.jar
- test/lib/*.jar excludes:
- lib/ant*.jar
- test/lib/ant*.jar
### 🌈 Minimal Example: 🌈
publishers:
- whitesource
---
### 🧹 `workspace-cleanup (post-build)()` 🧹
> Requires the Jenkins Workspace Cleanup Plugin — <https://plugins.jenkins.io/ws-cleanup>.
Quick note bestie: the *pre-build* `workspace-cleanup` lives over in the **wrapper** section instead. This one here is post-build, so she tidies up *after* the party. 🎀
**Parameters**
- **`include`** *(list)* — list of files to be included.
- **`exclude`** *(list)* — list of files to be excluded.
- **`dirmatch`** *(bool)* — apply pattern to directories too. *(default `false`)*
- **`clean-if`** *(list)* — clean depending on build status.
**`clean-if` values**
- **`success`** *(bool)* *(default `true`)*
- **`unstable`** *(bool)* *(default `true`)*
- **`failure`** *(bool)* *(default `true`)*
- **`aborted`** *(bool)* *(default `true`)*
- **`not-built`** *(bool)* *(default `true`)*
- **`fail-build`** *(bool)* — fail the build if the cleanup itself fails. *(default `true`)*
- **`clean-parent`** *(bool)* — cleanup the matrix parent workspace. *(default `false`)*
- **`external-deletion-command`** *(str)* — external deletion command to run against files and directories.
- **`disable-deferred-wipeout`** *(bool)* — disable the improved deferred wipeout method. *(default `false`)*
### 💜 Minimal Example: 💜
publishers:
- workspace-cleanup
### ⭐ Full Example: ⭐
publishers:
- workspace-cleanup: include:
- "*.zip" exclude:
- "*.txt" clean-if:
- success: false
- unstable: false
- failure: false
- aborted: false
- not-built: false dirmatch: true fail-build: false clean-parent: true external-deletion-command: 'command' disable-deferred-wipeout: true
---
### 📋 `xml-summary()` 📋
Adds support for the Summary Display Plugin. She's here to show off the receipts. 💅
> Requires the Jenkins Summary Display Plugin — <https://plugins.jenkins.io/summary_report>.
**Parameters**
- **`files`** *(str)* — files to parse. **Required**, babes, no skipping this one.
- **`shown-on-project-page`** *(bool)* — display summary on the project page. *(default `false`)*
### 🦋 Minimal Example: 🦋
publishers:
- xml-summary: files: '*_summary_report.xml'
### 🌸 Full Example: 🌸
publishers:
- xml-summary: files: '*_summary_report.xml' shown-on-project-page: true
---
### 🎀 `xunit()` 🎀
Publish test results. Obsessed with how organized this gets. 🫶
> Requires the Jenkins xUnit Plugin — <https://plugins.jenkins.io/xunit>.
**Parameters**
- **`thresholdmode`** *(str)* — whether thresholds represent an absolute number of tests or a percentage. Either `'number'` or `'percent'`. *(default `'number'`)*
- **`thresholds`** *(list)* — thresholds for both `'failed'` and `'skipped'` tests.
**`threshold`** *(dict)*
The threshold values to set — where anything's missing, xUnit defaults to an internal value of `0`. Each test threshold should contain the following:
- **`unstable`** *(int)*
- **`unstablenew`** *(int)*
- **`failure`** *(int)*
- **`failurenew`** *(int)*
- **`test-time-margin`** *(int)* — give the report a time margin value in ms, before failing if it's not new — unless the option `requireupdate` is set for the configured framework. *(default `3000`)*
- **`types`** *(list)* — frameworks to configure, plus their options. Supports the following: `aunit`, `boosttest`, `checktype`, `cpptest`, `cppunit`, `ctest`, `dotnettest`, `embunit`, `fpcunit`, `gtest`, `junit`, `mstest`, `nunit`, `phpunit`, `tusar`, `unittest`, and `valgrind`.
> Not me being the bearer of bad news: the `'custom'` type is **not** supported. 😭
**`type`** *(dict)*
Each type can be configured using the following:
- **`pattern`** *(str)*: an Ant pattern to look for Junit result files, relative to the workspace root. *(default `''`)*
- **`requireupdate`** *(bool)*: fail the build whenever fresh tests results have not been found. *(default `true`)*
- **`deleteoutput`** *(bool)*: delete temporary JUnit files. *(default `true`)*
- **`skip-if-no-test-files`** *(bool)*: skip parsing this xUnit type report if there are no test reports files. *(default `false`)*
- **`stoponerror`** (*bool*) — bestie, flip this on and the build gets *yeeted* the moment any error shows up while it's processing a result file (default `true`).
Example:
publishers:
- xunit: thresholdmode: 'percent' thresholds:
- failed: unstable: 0 unstablenew: 0 failure: 0 failurenew: 0
- skipped: unstable: 0 unstablenew: 0 failure: 0 failurenew: 0 types:
- phpunit: pattern: "junit.log" stoponerror: true
- cppunit: pattern: "cppunit.log"
- gtest: pattern: "gtest.log"
---
### zulip()
Slap the build status onto zulip 🦋. You need the Jenkins Humbug Plugin for this one <https://plugins.jenkins.io/humbug>.
Example:
publishers:
- zulip
---
## <purple>Reporters</purple> 💖
Okay so reporters are literally publishers' Maven-only cousin — same energy, but they only work on Maven projects ✨.
Component: `reporters`
- Macro — `reporter`
- Entry Point — `jenkins_jobs.reporters`
Example:
job: name: test_job project-type: maven
reporters:
- email: recipients: breakage@example.com
### class `reporters.Reporters(registry)`
- **`component_list_type = 'reporters'`** — the component list type is what gets used to look up all the possible implementations of this component type through entry points (and since entry points hand back a *list* of components, bestie, it's gotta be plural 💅). Set <italic>both</italic> `component_type` and `component_list_type` to `None` if the module doesn't have components at all.
- **`component_type = 'reporter'`** — the component type for everything in this module. This is what's used to hunt down macros (they're defined singularly, so no pluralizing, periodt). Again: set <italic>both</italic> `component_type` and `component_list_type` to `None` if the module has no components.
- **`gen_xml(xml_parent, data)`** — updates that XML element tree based on the YAML data. Override this method to add elements to the XML output. Make new `Element` objects and add them to `xml_parent`. And listen — the YAML data structure must **not** be modified, no cap 🚫.
`:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure`
- **`sequence = 55`** — the sequence number for the module. Modules get invoked in order of their sequence number so the XML output comes out consistently ordered, iykyk ⭐.
### email()
Email notifications on build failure 📧.
Parameters
- *recipients* (*str*) — recipient email addresses
- *notify-every-unstable-build* (*bool*) — send an email for every unstable build (default `true`)
- *send-to-individuals* (*bool*) — send an email to the individual who broke the build (default `false`)
- *notify-for-each-module* (*bool*) — send an email for each module (e.g. failed, unstable) (default `true`)
Example:
reporters:
- email: recipients: breakage@example.com
### findbugs()
FindBugs reporting for builds 🐛.
Requires the Jenkins FindBugs Plugin (<https://github.com/jenkinsci/findbugs-plugin>).
Parameters
- *rank-priority* (*bool*) — use rank as priority (default `false`)
- *include-files* (*str*) — comma separated list of files to include (optional)
- *exclude-files* (*str*) — comma separated list of files to exclude (optional)
- *can-run-on-failed* (*bool*) — weather or not to run plug-in on failed builds (default `false`)
- *healthy* (*int*) — Sunny threshold (optional)
- *unhealthy* (*int*) — Stormy threshold (optional)
- *health-threshold* (*str*) — threshold priority for health status (`'low'`, `'normal'` or `'high'`, defaulted to `'low'`)
- *dont-compute-new* (*bool*) — if set to `false`, computes new warnings based on the reference build (default `true`)
- *use-delta-values* (*bool*) — use delta for new warnings (default `false`)
- *use-previous-build-as-reference* (*bool*) — if set, then the number of new warnings will *always* be calculated based on the previous build. Otherwise the reference build (default `false`)
- *use-stable-build-as-reference* (*bool*) — the number of new warnings will be calculated based on the last stable build, which lets you revert unstable builds where the number of warnings was decreased (default `false`)
- *thresholds* (*dict*) — `.INDENT 2.0`
- `thresholds`
- `unstable` (*dict*)
- `unstable`
- *total-all* (*int*)
- *total-high* (*int*)
- *total-normal* (*int*)
- *total-low* (*int*)
- *new-all* (*int*)
- *new-high* (*int*)
- *new-normal* (*int*)
- *new-low* (*int*)
- `failed` (*dict*)
- `failed`
- *total-all* (*int*)
- *total-high* (*int*)
- *total-normal* (*int*)
- *total-low* (*int*)
- *new-all* (*int*)
- *new-high* (*int*)
- *new-normal* (*int*)
- *new-low* (*int*)
Minimal Example:
project-type: maven reporters:
- findbugs
Full Example:
project-type: maven reporters:
- findbugs: rank-priority: true include-files: 'f,d,e,.' exclude-files: 'a,c,d,.' can-run-on-failed: true healthy: 80 unhealthy: 10 use-delta-values: true health-threshold: 'high' thresholds: unstable: total-all: 90 total-high: 80 total-normal: 50 total-low: 20 new-all: 95 new-high: 85 new-normal: 55 new-low: 25 failed: total-all: 80 total-high: 70 total-normal: 40 total-low: 10 new-all: 85 new-high: 75 new-normal: 45 new-low: 15 dont-compute-new: false use-delta-values: true use-previous-build-as-reference: true use-stable-build-as-reference: true
---
## <cyan>SCM</cyan> 🌈
The SCM module is how you tell the project where the source code actually lives 👑. It adds the `scm` attribute to the `Job <#job>` definition, and that thing takes any number of scm definitions. You can also throw `[]` at the `scm` attribute — which slays when you've got a set of configs with a global default scm but you want one specific job to override that default with *no* SCM at all 🙈.
Component: `scm`
- Macro — `scm`
- Entry Point — `jenkins_jobs.scm`
The `scm` module lets you reference multiple repositories inside one Jenkins job. Heads up though: adding more than one scm definition requires the Jenkins Multiple SCMs plugin <https://plugins.jenkins.io/multiple-scms>.
Example of multiple repositories in a single job:
- scm: name: first-scm scm:
- git: url: ssh://jenkins@review.openstack.org:29418/first.git branches:
- origin/master
- git: url: ssh://jenkins@review.openstack.org:29418/first.git branches:
- scm: name: second-scm scm:
- git: url: ssh://jenkins@review.openstack.org:29418/second.git branches:
- origin/master
- git: url: ssh://jenkins@review.openstack.org:29418/second.git branches:
- scm: name: first-and-second scm:
- first-scm
- second-scm
- job: name: my-job scm:
- first-and-second
Example of an empty scm:
scm: []
### class `scm.PipelineSCM(registry)`
- **`component_list_type = 'pipeline-scm'`** — this list type is what's used to look up possible implementations of the component type via entry points (entry points give back a list of components, so plural it is 💅). Set <italic>both</italic> `component_type` and `component_list_type` to `None` if the module doesn't have components.
- **`component_type = 'pipeline-scm'`** — the component type for components of this module. This is what's used to find macros (they're defined singularly and should *not* be plural). Set <italic>both</italic> `component_type` and `component_list_type` to `None` if the module doesn't have components.
- **`gen_xml(xml_parent, data)`** — okay so this one's the glow-up method 💅 it updates the XML element tree using the YAML data. Wanna add stuff to your XML output? Override this bad boy. You make brand-new `Element` objects and yeet them onto the `xml_parent`. And bestie, <red>do not touch the YAML data structure</red> — it stays exactly as it is. 🫶
- `:arg class:xml.etree.ElementTree xml_parent:` — the parent XML element
- `:arg dict data:` — the YAML data structure
- **`sequence = 30`** — the sequence number for this module ✨ modules get invoked in the order of their sequence number, so your XML output comes out consistently ordered. It's giving organized. 🎀
---
## <purple>class `scm.SCM(registry)`</purple> 🦋
- **`component_list_type = 'scm'`** — this component list type is what gets used to look up all the possible implementations of the component type via entry points (entry points hand you a *list* of components, so yeah, it's plural, periodt). So if your module has literally no components, set <cyan>both</cyan> `component_type` and `component_list_type` to `None`. 💀
- **`component_type = 'scm'`** — the component type for the components of this module. This is what's used to hunt down macros (macros are defined singularly, so they should *not* be plural, no cap). And again — if your module has no components, set <cyan>both</cyan> `component_type` and `component_list_type` to `None`. 🌸
- **`gen_xml(xml_parent, data)`** — updates the XML element tree based on the YAML data, same vibe as before. Override it to add elements to your XML output. Make new `Element` objects, add them to `xml_parent`. And <red>the YAML data structure must not be modified</red> — I'm so serious. 😭
- `:arg class:xml.etree.ElementTree xml_parent:` — the parent XML element
- `:arg dict data:` — the YAML data structure
- **`sequence = 30`** — sequence number for the module, again 💫 modules fire off in sequence-number order so the XML output stays consistently ordered. Iconic behavior, honestly. ⭐
---
### <mint>`accurev()`</mint> 🧚
Specifies the AccuRev SCM repository for this job, bestie.
Requires the Jenkins AccuRev Plugin `https://plugins.jenkins.io/accurev` — you gotta have it, fr fr.
**Parameters** 🍓
- `depot` (*str*) — the depot you wanna use for the current job (optional)
- `stream` (*str*) — the stream the build will be generated from (optional)
- `server-name` (*str*) — the AccuRev server you're using for your builds (<hotpink>required</hotpink>)
- `ignore-parent-changes` (*bool*) — ignore the possibility of changes in the parent stream (default `false`)
- `clean-reference-tree` (*bool*) — deletes any external files in the reference tree (default `false`)
- `build-from-snapshot` (*bool*) — creates a snapshot of the target stream, then populates and builds from that snapshot (default `false`)
- `do-not-pop-content` (*bool*) — if the checkbox is on, elements are not populating vice versa (default `false`)
- `workspace` (*str*) — name of an existing workspace (optional)
- `reference-tree` (*str*) — name of the reference tree (optional)
- `directory-offset` (*str*) — relative directory path from the default Jenkins workspace location where the files from the stream, workspace, or reference tree should be retrieved from (optional)
- `sub-path` (*str*) — makes a "best effort" to ensure that only the sub-path is populated (optional)
- `filter-poll-scm` (*str*) — specify directories or files you want Jenkins to check before starting a build (optional)
- `snapshot-name-format` (*str*) — naming conventions for the snapshot go in this field (optional)
**Example:**
scm:
- accurev: depot: Test depot stream: Test stream server-name: Test server name ignore-parent-changes: true clean-reference-tree: true build-from-snapshot: true do-not-pop-content: true workspace: Test workspace reference-tree: Test reference tree directory-offset: Test directory offset sub-path: Test sub path filter-poll-scm: Test filter snapshot-name-format: Test snapshot name format
---
### <lavender>`bzr()`</lavender> 🌈
Specifies the bzr SCM repository for this job. She's cute, she's simple.
Requires the Jenkins Bazaar Plugin `https://plugins.jenkins.io/bazaar` — mandatory, no skipping. 🙈
**Parameters** 🎀
- `url` (*str*) — URL of the bzr branch (<hotpink>required</hotpink>)
- `clean-tree` (*bool*) — clean up the workspace (using bzr) before pulling the branch (default `false`)
- `lightweight-checkout` (*bool*) — use a lightweight checkout instead of a full branch (default `false`)
- `browser` (*str*) — the repository browser to use.
- **browsers supported** 👑
- `auto` — (default)
- `loggerhead` — as used by Launchpad
- `opengrok` — `https://opengrok.github.io/OpenGrok/`
- `browser-url` (*str*) — URL for the repository browser (<hotpink>required</hotpink> if `browser` is set).
- `opengrok-root-module` (*str*) — root module for OpenGrok (<hotpink>required</hotpink> if `browser` is `opengrok`).
**Example:**
scm:
- bzr: url: lp:test_project
---
### <peach>`cvs()`</peach> 💖
Specifies the CVS SCM repository for this job. She's long, she's detailed, she ate and left no crumbs.
Requires the Jenkins CVS Plugin `https://plugins.jenkins.io/cvs` — go get it. 🫶
**Parameters** 🌸
- `repos` (*list*) — list of CVS repositories. (<hotpink>required</hotpink>)
- **Repos**
- `root` (*str*) — the CVS connection string Jenkins uses to connect to the server. The format is `:protocol:user@host:path` (<hotpink>required</hotpink>)
- `locations` (*list*) — list of locations. (<hotpink>required</hotpink>)
- **Locations**
- `type` (*str*) — type of location.
- **supported values**
- `HEAD` — (default)
- `BRANCH`
- `TAG`
- `name` (*str*) — name of location. Only valid in case of `'BRANCH'` or `'TAG'` location type. (default `''`)
- `use-head` (*bool*) — use Head if not found. Only valid in case of `'BRANCH'` or `'TAG'` location type. (default `false`)
- `modules` (*list*) — list of modules. (<hotpink>required</hotpink>)
- **Modules**
- `remote` — the name of the module in the repository at `CVSROOT`. (<hotpink>required</hotpink>)
- `local-name` — the name to be applied to this module in the local workspace. If blank, the remote module name will be used. (default `''`)
- `excluded-regions` (*list str*) — patterns for excluding regions. (optional)
- `compression-level` (*int*) — compression level. Must be a number between `-1` and `9` inclusive. Choose `-1` for System Default. (default `-1`)
- `use-update` (*bool*) — if `true`, Jenkins will use `'cvs update'` whenever possible for builds. This makes a build faster. But it also causes the artifacts from the previous build to remain in the file system when a new build starts, making it <red>not a true clean build</red>. (default `true`)
- `prune-empty` (*bool*) — remove empty directories after checkout using the CVS `'-P'` option. (default `true`)
- `skip-changelog` (*bool*) — prevent the changelog from being generated after checkout has completed. (default `false`)
- `show-all-output` (*bool*) — instructs CVS to show all logging output. CVS normally runs in quiet mode but this option disables that. (default `false`)
- `clean-checkout` (*bool*) — perform clean checkout on failed update. (default `false`)
- `clean-copy` (*bool*) — force clean copy for locally modified files. (default `false`)
**Example** 🍓
scm:
- cvs: repos:
- root: ":protocol:user@host1:path" locations:
- modules:
- remote: "remote1"
- remote: "remote2"
- root: ":protocol:user@host2:path" locations:
- modules:
- remote: "remote1"
- root: ":protocol:user@host1:path" locations:
scm:
- cvs: repos:
- root: ":protocol:user@host1:path" compression-level: "1" locations:
- type: TAG name: "tag name" use-head: false modules:
- remote: "remote1" local-name: "localName"
- remote: "remote2" excluded-regions:
- "pattern1"
- "pattern2"
- root: ":protocol:user@host2:path" locations:
- modules:
- remote: "remote1" use-update: false prune-empty: false skip-changelog: true show-all-output: true clean-checkout: true clean-copy: true
---
## <pink>dimensions()</p> 🦋
Okay bestie, this one is for when your job lives in a <purple>Dimensions</purple> repo. It tells the job where the Dimensions SCM repository is, and it's giving very much *enterprise*.
> Heads up: you need the Jenkins Dimensions Plugin for this to work at all — <cyan>`<https://plugins.jenkins.io/dimensionsscm>`</cyan>.
### <lavender>Parameters</lavender>
- **`project`** (*str*) — the project name, and it **has to** be in the format `PRODUCT_ID:PROJECT_NAME`. This one is <hotpink>**required**</hotpink>, no skipping it.
- **`permissions`** (*str*) — the default permissions for updated files (default: `DEFAULT`). The options are:
- `DEFAULT`
- `READONLY`
- `WRITABLE`
- **`eol`** (*str*) — end of line (default: `DEFAULT`). And the end-of-line vibes on offer are:
- `DEFAULT`
- `UNIX`
- `WINDOWS`
- `UNCHANGED`
- **`folders`** (*list*) — the folders to monitor (default `/`).
- **`exclude`** (*list*) — the paths to exclude from monitoring, like a little no-fly zone ✋.
- **`username`** (*str*) — the repository username for this job.
- **`password`** (*str*) — the repository password for this job. 🤫
- **`server`** (*str*) — the Dimensions server for this job.
- **`database`** (*str*) — the Dimensions database for this job. The format **must** be `<database@dsn>`.
- **`update`** (*bool*) — use update (default `false`).
- **`clear-workspace`** (*bool*) — clear the workspace *before* the build happens (default `false`).
- **`force-build`** (*bool*) — force the build even if the repository SCM checkout operation fails (default `false`). Yeah, it just powers through 💀.
- **`overwrite-modified`** (*bool*) — overwrite files in the workspace with files from the repository (default `false`).
- **`expand-vars`** (*bool*) — expand substitution variables (default `false`).
- **`no-metadata`** (*bool*) — checkout files with no metadata (default `false`).
- **`maintain-timestamp`** (*bool*) — maintain the file timestamp from Dimensions (default `false`).
- **`slave-checkout`** (*bool*) — force slave based checkout (default `false`).
- **`timezone`** (*str*) — the server timezone.
- **`web-url`** (*str*) — the Dimensions Web URL.
### <mint>Examples:</mint>
The bare minimum, just the required bit:
scm:
- dimensions: project: myProduct:myProject
And the ✨full glow-up✨, every knob turned:
scm:
- dimensions: project: myProduct:myProject permissions: WRITABLE eol: UNIX folders:
- src
- test exclude:
- excluded_dir
- excluded_other_dir username: johnd password: passw0rd server: my.dmscm.server:1234 database: myDatabase@myDsn update: true clear-workspace: true force-build: true overwrite-modified: true expand-vars: true no-metadata: true maintain-timestamp: true slave-checkout: true timezone: Europe/Berlin web-url: https://my.dmscm.weburl
---
## <pink>git()</p> 🎀
The one, the only, the main character of SCMs: **git**. This says "this job pulls from a git repository", which, yeah, iconic.
> You need the Jenkins Git Plugin for this — <cyan>`<https://plugins.jenkins.io/git>`</cyan>.
### <lavender>Parameters</lavender>
- **`url`** (*str*) — the URL of the git repository.
- **`credentials-id`** (*str*) — the ID of the credential to use for connecting. It's the last field (a 32-digit hexadecimal code) of the path of the URL, the one you can see after you clicked the credential under Jenkins Global credentials. Optional 🫶.
- **`refspec`** (*str*) — the refspec to fetch (default `'+refs/heads/*:refs/remotes/remoteName/*'`).
- **`name`** (*str*) — the name to fetch (default `'origin'`).
- **`remotes`** (*list(str)*) — a list of remotes to set up. Optional, and only needed if you've got multiple remotes to set up. Each Remote has:
- `url` (*string*) — url of remote repo
- `refspec` (*string*) — refspec to fetch (optional)
- `credentials-id` — ID of credential to use to connect, which is the last field of the path of URL (a 32-digit hexadecimal code) visible after you clicked credential under Jenkins Global credentials. (optional)
- **`branches`** (*list(str)*) — the list of branch specifiers to build (default `'**'`).
- **`skip-tag`** (*bool*) — skip tagging (default `true`).
> <red>Deprecated since version 2.0.0.</red> Please use the per-build-tag extension instead — it means the exact opposite, so be careful, bestie 😭.
- **`clean`** (*bool*) — clean after checkout (default `false`).
> <red>Deprecated since version 1.1.1.</red> Please use the clean extension format instead.
- **`fastpoll`** (*bool*) — use fast remote polling (default `false`).
- **`disable-submodules`** (*bool*) — disable submodules (default `false`).
> <red>Deprecated since version 1.1.1.</red> Please use the submodule extension instead.
- **`recursive-submodules`** (*bool*) — recursively update submodules (default `false`).
> <red>Deprecated since version 1.1.1.</red> Please use the submodule extension instead.
- **`git-tool`** (*str*) — the name of the Git installation to use (default `'Default'`).
- **`reference-repo`** (*str*) — path of the reference repo to use during clone (optional).
- **`browser`** (*str*) — which repository browser to use. The supported ones are:
- `auto` — (default)
- `assemblaweb` — `<https://get.assembla.com/>`
- `bitbucketweb` — `<https://bitbucket.org/>`
- `cgit` — `<https://git.zx2c4.com/cgit/about/>`
- `fisheye` — `<https://www.atlassian.com/software/fisheye>`
- `gitblit` — `<http://gitblit.com/>`
- `githubweb` — `<https://github.com/>`
- `gitiles` — `<https://code.google.com/archive/p/gitiles/>`
- `gitlab` — `<https://about.gitlab.com/>`
- `gitlist` — `<https://gitlist.org/>`
- `gitoriousweb` — `<https://gitorious.org/>`
- `gitweb` — `<https://git-scm.com/docs/gitweb>`
- `kiln` — `<https://ignitetech.com/softwarelibrary/fogbugz>`
- `microsoft-tfs-2013` — `<https://azure.microsoft.com/en-us/products/devops/server/>`
- `phabricator` — `<https://www.phacility.com/>`
- `redmineweb` — `<https://www.redmine.org/>`
- `rhodecode` — `<https://rhodecode.com/>`
- `stash` — `<https://www.atlassian.com/software/bitbucket/enterprise/data-center>`
- `viewgit`
- **`browser-url`** (*str*) — url for the repository browser. It's **required** if `browser` isn't `'auto'`, and there's no default, so don't come crying when it errors 💅.
- **`browser-version`** (*str*) — version of the repository browser (GitLab only, default `'0.0'`).
- **`project-name`** (*str*) — project name in Gitblit and ViewGit repobrowser (optional).
- **`repo-name`** (*str*) — repository name in phabricator repobrowser (optional).
- **`git-config-name`** (*str*) — configure name for Git clone (optional).
- **`git-config-email`** (*str*) — configure email for Git clone (optional).
### <mint>Extensions</mint>
- **`basedir`** (*string*) — location relative to the workspace root to clone to (default workspace).
- **`changelog-against`** (*dict*)
- `remote` (*string*) — name of repo that contains branch to create changelog against (default `'origin'`)
- `branch` (*string*) — name of the branch to create changelog against (default `'master'`)
- **`choosing-strategy:`** (*string*) — the Jenkins class for selecting what to build. Can be one of `default`, `inverse`, or `gerrit` (default `'default'`).
- **`clean`** (*dict*)
- `after` (*dict*) — clean the workspace after checkout
- `remove-stale-nested-repos` (*bool*) — deletes untracked submodules and any other subdirectories which contain `.git` directories (default `false`)
- `before` (*dict*) — clean the workspace before checkout
- **`remove-stale-nested-repos`** (bool) — deletes untracked submodules <pink>*and*</pink> any other subdirectories that contain `.git` directories in them (default `false`). Ngl bestie this one is giving spring cleaning but make it permanent, it <red>deletes</red> stuff 💀🧹
- **`committer`** (dict) — who gets the credit for brand new commits, as a lil dict 🫶
- **`name`** (str) — name to use as author of new commits ✍️
- **`email`** (str) — e-mail address to use for new commits 📧
- **`excluded-users`**: (list(string)) — a list of users to ignore revisions from when polling for changes. (if polling is enabled, optional) 🚫👻
- **`included-regions`**: (list(string)) — list of file/folders to include (optional) ✅📂
- **`excluded-regions`**: (list(string)) — list of file/folders to exclude (optional) ❌📂
- **`ignore-commits-with-messages`** (list(str)) — revisions committed with messages matching these patterns will be ignored. (optional) 🤐
- **`ignore-notify`**: (bool) — ignore `notifyCommit` URL accesses (default `false`) 🙈
- **`force-polling-using-workspace`** (bool) — force polling using workspace (default `false`) 🏋️
- **`local-branch`** (string) — checkout/merge to local branch (optional) 🌿
- **`merge`** (dict) — the merge settings, all cozy in one dict:
- **`remote`** (string) — name of repo that contains branch to merge to (default `'origin'`) 🌍
- **`branch`** (string) — name of the branch to merge to 🌱
- **`strategy`** (string) — merge strategy. Can be one of `'default'`, `'resolve'`, `'recursive'`, `'octopus'`, `'ours'`, `'subtree'`. (default `'default'`) 🐙
- **`fast-forward-mode`** (string) — merge fast-forward mode. Can be one of `'FF'`, `'FF_ONLY'` or `'NO_FF'`. (default `'FF'`) ⏩
- **`per-build-tag`** (bool) — create a tag in the workspace for every build. (default is inverse of `skip-tag` if set, otherwise `false`) 🏷️✨
- **`prune`** (bool) — prune remote branches (default `false`) ✂️
- **`scm-name`** (string) — the unique scm name for this Git SCM (optional) 🏷️
- **`shallow-clone`** (bool) — perform shallow clone (default `false`) 🏊
- **`depth`** (int) — set shallow clone depth (default `1`) 📏
- **`do-not-fetch-tags`** (bool) — perform a clone without tags (default `false`) 🚫🏷️
- **`honor-refspec`** (bool) — perform initial clone using the refspec defined for the repository (default `false`) 🎯
- **`skip-notifications`** (bool) — skip build status notifications (default `false`). Requires the Jenkins Skip Notifications Trait Plugin, which lives at <cyan>`https://plugins.jenkins.io/skip-notifications-trait`</cyan>. 🔕
- **`sparse-checkout`** (dict) — the "I only want *some* of the files" bundle:
- **`paths`** (list) — list of paths to sparse checkout. (optional) 🧺
- **`submodule`** (dict) — the submodule situation, and wow does it have opinions:
- **`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`). ⏰
- **`threads`** (int) — number of parallel processes to be used when updating submodules. Default is to use a single thread for submodule updates. 🧵
- **`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`) 🐘
---
### Example: 📝
Ok so here's what it looks like all put together, and honestly? slay:
scm:
- git: url: https://example.com/project.git branches:
- master
- stable browser: githubweb browser-url: http://github.com/foo/example.git timeout: 20
---
### `hg()` 🧜♀️
Specifies the mercurial SCM repository for this job.
Requires the Jenkins Mercurial Plugin at <cyan>`https://plugins.jenkins.io/mercurial`</cyan>. Don't forget it bestie or nothing works 💖
**Parameters** 🌸
- **`url`** (str) — URL of the hg repository (required) 🔗
- **`credentials-id`** (str) — ID of credentials to use to connect (optional) 🔑
- **`revision-type`** (str) — revision type to use (default `'branch'`) 🌿
- **`revision`** (str) — the branch or tag name you would like to track (default `'default'`) 📌
- **`modules`** (list(str)) — reduce unnecessary builds by specifying a list of "modules" within the repository. A module is a directory name within the repository that this project lives in. (default `''`) 📦
- **`clean`** (bool) — wipe any local modifications or untracked files in the repository checkout (default `false`) 🧼
- **`subdir`** (str) — check out the Mercurial repository into this subdirectory of the job's workspace (optional) 📁
- **`disable-changelog`** (bool) — do not calculate the Mercurial changelog for each build (default `false`) 📜🚫
- **`browser`** (str) — what repository browser to use 🖥️
**browsers supported** 👑
- **`auto`** — (default) ✨
- **`bitbucketweb`** — <cyan>`https://bitbucket.org/`</cyan> 🪣
- **`fisheye`** — <cyan>`https://www.atlassian.com/software/fisheye`</cyan> 🐟
- **`googlecode`** — <cyan>`https://code.google.com/`</cyan> 🔍
- **`hgweb`** — <cyan>`https://repo.mercurial-scm.org/hg/help/hgweb`</cyan> 🌐
- **`kilnhg`** — <cyan>`https://ignitetech.com/softwarelibrary/fogbugz`</cyan> 🐛
- **`rhodecode`** — <cyan>`https://rhodecode.com/`</cyan> (versions >= 1.2) 🏝️
- **`rhodecode-pre-1.2.0`** — <cyan>`https://rhodecode.com/`</cyan> (versions < 1.2) 🏝️💀
- **`browser-url`** (str) — url for the repository browser (required if browser is set) 🔗
### Example: 🌈
scm:
- hg: revision: feature url: ssh://hg@hg/repo credentials-id: "abcdef01234567890" modules:
- module1
- module2 clean: true subdir: my/sources disable-changelog: true browser: hgweb browser-url: http://hg/repo
---
### `openshift-img-streams()` 🛸
Rather than a Build step extension plugin, this is an extension of the Jenkins SCM plugin, where this baked-in polling mechanism provided by Jenkins is leveraged by exposing some of the common semantics between OpenShift ImageStreams (which are abstractions of Docker repositories) and SCMs — versions / commit IDs of related artifacts (images vs. programmatics files). Like, it's the same vibe check, different species, iykyk 💅
Requires the Jenkins OpenShift Pipeline Plugin at <cyan>`https://plugins.jenkins.io/openshift-pipeline`</cyan>. 🚀
**Parameters** 🌸
- **`image-stream-name`** (str) — the name of the ImageStream is what shows up in the NAME column if you dump all the ImageStream's with the `oc get is` command invocation. (default `nodejs-010-centos7`) 👀
- **`tag`** (str) — the specific image tag within the ImageStream to monitor. (default `latest`) 🏷️
- **`api-url`** (str) — this would be the value you specify if you leverage the `--server` option on the OpenShift `oc` command. (default `https://openshift.default.svc.cluster.local`) 🌐
- **`namespace`** (str) — the value here should be whatever was the output form `oc project` when you created the BuildConfig you want to run a Build on. (default `test`) 📂
- **`auth-token`** (str) — the value here is what you supply with the `--token` option when invoking the OpenShift `oc` command. (default `''`) 🔑
- **`verbose`** (bool) — this flag is the toggle for turning on or off detailed logging in this plug-in. (default `false`) 🔊
**Full Example:**
scm:
- openshift-img-streams: image-stream-name: nodejs-010-fedora tag: prod api-url: https://openshift.example.local.url/ namespace: test-scm auth-token: ose-key-img-streams1 verbose: true
And if you just want the absolute bare minimum, bestie, it's literally this:
scm:
- openshift-img-streams
---
## 🎀 `p4()` — the Perforce girlie
Specifies the Perforce (P4) repository for this job.
Requires the Jenkins P4 Plugin <https://plugins.jenkins.io/p4>.
> ok so this one's short and sweet, she doesn't need a whole paragraph of parameters. just drop her in and let her cook. 💅
---
## 🦋 `repo()` — the multi-repo manifest queen
Specifies the repo SCM repository for this job.
Requires the Jenkins Repo Plugin <https://plugins.jenkins.io/repo>.
### ✨ Parameters ✨
- **`manifest-url`** (*str*) — URL of the repo manifest (**required**, no goofing around on this one)
- **`manifest-branch`** (*str*) — The branch of the manifest to use (optional)
- **`manifest-file`** (*str*) — Initial manifest file to use when initialising (optional)
- **`manifest-group`** (*str*) — Only retrieve those projects in the manifest tagged with the provided group name (optional)
- **`ignore-projects`** (*list(str)*) — a list of projects in which changes would not be considered to trigger a build when pooling (optional)
- **`destination-dir`** (*str*) — Location relative to the workspace root to clone under (optional)
- **`repo-url`** (*str*) — custom url to retrieve the repo application (optional)
- **`mirror-dir`** (*str*) — Path to mirror directory to reference when initialising (optional)
- **`jobs`** (*int*) — Number of projects to fetch simultaneously (default `0`)
- **`depth`** (*int*) — Specify the depth in history to sync from the source. The default is to sync all of the history. Use `1` to just sync the most recent commit (default `0`)
- **`current-branch`** (*bool*) — Fetch only the current branch from the server (default `true`)
- **`reset-first`** (*bool*) — Remove any commits that are not on the repositories by running the following command before anything else (default `false`): `repo forall -c "git reset --hard"`
- **`clean-first`** (*bool*) — Remove any files that are not tracked in the repositories by running the following command before anything else (default `false`): `repo forall -c "git clean -fdx"`
- **`quiet`** (*bool*) — Make repo more quiet (default `true`)
- **`force-sync`** (*bool*) — Continue sync even if a project fails to sync (default `false`)
- **`no-tags`** (*bool*) — Don't fetch tags (default `false`)
- **`trace`** (*bool*) — Trace git command execution into the build logs. (default `false`)
- **`show-all-changes`** (*bool*) — When this is checked `--first-parent` is no longer passed to `git log` when determining changesets (default `false`)
- **`local-manifest`** (*str*) — Contents of `.repo/local_manifest.xml`, written prior to calling sync (optional)
### 🌸 Example 🌸
scm:
- repo: manifest-url: https://example.com/project/ manifest-branch: stable manifest-file: repo.xml manifest-group: drivers ignore-projects:
- static-project
- unimportant-project destination-dir: build repo-url: https://internal.net/projects/repo mirror-dir: ~/git/project/ jobs: 3 current-branch: false reset-first: true clean-first: true quiet: false force-sync: true no-tags: true trace: true show-all-changes: true local-manifest: | <?xml version="1.0" encoding="UTF-8"?> <manifest> <project path="external/project" name="org/project" remote="gerrit" revision="master" /> </manifest>
---
## 💜 `store()` — Visualworks Smalltalk Store, she's niche but she ate
Specifies the Visualworks Smalltalk Store repository for this job.
Requires the Jenkins Visualworks Smalltalk Store Plugin <https://plugins.jenkins.io/visualworks-store>.
### ✨ Parameters ✨
- **`script`** (*str*) — name of the Store script to run
- **`repository`** (*str*) — name of the Store repository
- **`version-regex`** (*str*) — regular expression that specifies which pundle versions should be considered (optional)
- **`minimum-blessing`** (*str*) — minimum blessing level to consider (optional)
- **`parcel-builder-file`** (*str*) — name of the file to generate as input to a later parcel building step (optional — if not specified, then no parcel builder file will be generated)
- **`pundles`** (*list*) — the actual pundle situation:
- *(package or bundle)* (*dict*): A package or bundle to check
> ngl the `.INDENT 2.0` energy of that last one is a whole vibe, the pundles list just nests a dict in there and you either get package or bundle, pick your fighter 🫶
### 🌈 Example 🌈
scm:
- store: script: someStoreScript repository: StoreRepository version-regex: "[0-9]+" minimum-blessing: Integrated parcel-builder-file: parcelBuilderInput pundles:
- package: SomePackage
- package: AnotherPackage
- bundle: SomeBundle
---
## 💅 `svn()` — the OG, still showing up and still iconic
Specifies the svn SCM repository for this job.
### ✨ Parameters ✨
- **`url`** (*str*) — URL of the svn repository
- **`basedir`** (*str*) — location relative to the workspace root to checkout to (default `'.'`)
- **`credentials-id`** (*str*) — optional argument to specify the ID of credentials to use
- **`repo-depth`** (*str*) — Repository depth. Can be one of `'infinity'`, `'empty'`, `'files'`, `'immediates'` or `'unknown'`. (default `'infinity'`)
- **`ignore-externals`** (*bool*) — Ignore Externals. (default `false`)
- **`workspaceupdater`** (*str*) — optional argument to specify
- **`workspaceupdater`** — optional argument to specify how to update the workspace (default `wipeworkspace`)
supported values:
- `wipeworkspace` — deletes the workspace before checking out
- `revertupdate` — do an `svn revert` then an `svn update`
- `emulateclean` — delete unversioned/ignored files then update
- `update` — do an `svn update` as much as possible
- **`excluded-users`** (*list(str)*) — list of users to ignore revisions from when polling for changes (if polling is enabled; parameter is optional)
- **`included-regions`** (*list(str)*) — list of file/folders to include (optional)
- **`excluded-regions`** (*list(str)*) — list of file/folders to exclude (optional)
- **`excluded-commit-messages`** (*list(str)*) — list of commit messages to exclude (optional)
- **`exclusion-revprop-name`** (*str*) — revision svn-property to ignore (optional)
- **`ignore-property-changes-on-directories`** (*bool*) — ignore svn-property only changes of directories (default `false`)
- **`filter-changelog`** (*bool*) — If set Jenkins will apply the same inclusion and exclusion patterns for displaying changelog entries as it does for polling for changes (default `false`)
- **`repos`** (*list*) — list of repositories to checkout (optional)
- **`additional-credentials`** (*list*) — list of additional credentials (optional) `:Additional-Credentials:`
- **`realm`** (*str*) — realm to use
- **`credentials-id`** (*str*) — optional ID of credentials to use
- **`viewvc-url`** (*str*) — URL of the svn web interface (optional)
Repo:
- **`url`** (*str*) — URL for the repository
- **`basedir`** (*str*) — Location relative to the workspace root to checkout to (default `'.'`)
- **`credentials-id`** — optional ID of credentials to use
- **`repo-depth`** — Repository depth. Can be one of `'infinity'`, `'empty'`, `'files'`, `'immediates'` or `'unknown'`. (default `'infinity'`)
- **`ignore-externals`** — Ignore Externals. (default `false`)
> lowkey yes `workspaceupdater` shows up twice in the list above. that's just how the manpage rolls, bestie, I'm not the one who wrote it. 💀
### 🌸 Multiple repos example 🌸
scm:
- svn: workspaceupdater: update repos:
- url: http://svn.example.com/repo basedir: . credentials-id: "abcdef01234567890" repo-depth: files ignore-externals: true
- url: http://svn.example.com/repo2 basedir: repo2
### 🌟 Advanced commit filtering example 🌟
scm:
- svn: url: http://svn.apache.org/repos/asf/spamassassin/trunk credentials-id: "abcdef01234567890" repo-depth: empty ignore-externals: true workspaceupdater: wipeworkspace included-regions:
- /region1/.*.cpp
- /region2 excluded-regions:
- /region3/.*.jpg
- /region4 excluded-users:
- user1
- user2 excluded-commit-messages:
- test-msg
- test-msg2 exclusion-revprop-name: propname filter-changelog: true ignore-property-changes-on-directories: true viewvc-url: http://svn.apache.org/viewvc/spamassassin/trunk
---
### 🌈 `tfs()`
okay bestie, this one sets up the <hotpink>Team Foundation Server</hotpink> repo for your job 💖
You need the Jenkins Team Foundation Server Plugin for it (`https://github.com/jenkinsci/tfs-plugin`).
> <red>⚠️ NOTE:</red> TFS Password has to be typed in *by hand* on the project if you specify a user name. The password gets <bold>overwritten with an empty value</bold> every single time the job is rebuilt with Jenkins Job Builder. So yeah. Heads up 🫠
**Parameters**
- **`server-url`** (*str*) — The name or URL of the team foundation server. If the server is already registered on the machine, you literally just need the name. No cap.
- **`project-path`** (*str*) — The name of the project as it's registered on the server.
- **`login`** (*str*) — The user name registered on the server. It must contain the name *and* the domain name. Entered as `domain\\user` or `user@domain` (optional).
> <yellow>NOTE:</yellow> You must enter in at least two slashes for the `domain\\user` format in JJB YAML. It will be rendered normally. fr fr, two slashes, don't fight it 💅
- **`use-update`** (*str*) — If true, Hudson will not delete the workspace at end of each build. This causes the artifacts from the previous build to remain when a new build starts. (default `true`)
- **`local-path`** (*str*) — The folder where all files will be retrieved into. The folder name is a relative path, under the workspace of the current job. (default `.`)
- **`workspace`** (*str*) — The name of the workspace under which the source should be retrieved. This workspace is created at the start of a download, and deleted at the end. You can normally omit the property unless you want to name a workspace to avoid conflicts on the server (i.e. when you have multiple projects on one server talking to a Team Foundation Server). (default `Hudson-${JOB_NAME}-${NODE_NAME}`)
The TFS plugin supports the following macros that are replaced in the workspace name:
- `${JOB_NAME}` — The name of the job.
- `${USER_NAME}` — The user name that the Hudson server or slave is running as.
- `${NODE_NAME}` — The name of the node/slave that the plugin currently is executed on. Note that this is <bold>not</bold> the hostname, this value is the Hudson configured name of the slave/node.
- `${ENV}` — The environment variable that is set on the master or slave.
- **`web-access`** (*dict*) — Adds links in "changes" views within Jenkins to an external system for browsing the details of those changes. The "Auto" selection attempts to infer the repository browser from other jobs, if supported by the SCM and a job with matching SCM details can be found. (optional, default `Auto`).
**web-access value**
- `web-url` — Enter the URL to the TSWA server. The plugin will strip the last path (if any) of the URL when building URLs for change set pages and other pages. (optional, default uses `server-url`)
**Examples:**
scm:
- tfs: server-url: "tfs.company.com" project-path: "$/myproject" login: "mydomain\\jane" use-update: false local-path: "../foo/" workspace: "Hudson-${JOB_NAME}" web-access:
- web-url: "http://TFSMachine:8080"
scm:
- tfs: server-url: "tfs.company.com" project-path: "$/myproject" login: "jane@mydomain" use-update: false local-path: "../foo/" workspace: "Hudson-${JOB_NAME}" web-access:
---
### 🔗 `url()`
Watch for changes in, and download an artifact from a particular url. it's giving "keep an eye on this link for me bestie" energy ✨
Requires the Jenkins URL SCM `https://plugins.jenkins.io/URLSCM`.
**Parameters**
- **`url-list`** (*list*) — List of URLs to watch. (required)
- **`clear-workspace`** (*bool*) — If set to true, clear the workspace before downloading the artifact(s) specified in `url-list`. (default `false`)
**Examples:**
scm:
- url: url-list:
- 'http://jenkins.domain.local/jnlpJars/jenkins-cli.jar'
scm:
- url: url-list:
- 'http://jenkins.domain.local/jnlpJars/jenkins-cli.jar'
- 'http://code.jquery.com/jquery-1.11.3.min.js' clear-workspace: true
---
### 🧬 `workspace()`
Specifies the cloned workspace for this job to use as a SCM source. reusing the vibes of a whole other job, iconic 💜
Requires the Jenkins Clone Workspace SCM Plugin `https://plugins.jenkins.io/clone-workspace-scm`.
The job the workspace is cloned from **must** be configured with an `clone-workspace` publisher.
**Parameters**
- **`parent-job`** (*str*) — The name of the parent job to clone the workspace from.
- **`criteria`** (*str*) — Set the criteria to determine what build of the parent project to use. Can be one of `'Any'`, `'Not Failed'` or `'Successful'`. (default `Any`)
**Example:**
scm:
- workspace: parent-job: my-upstream-job criteria: Any
---
# ⚡ Triggers ⚡
Triggers define what causes a Jenkins job to start building. like, the whole reason your job wakes up and does its little thing 🦋
<purple>Component:</purple> `triggers`
| Macro `trigger`
**Entry Point**
`jenkins_jobs.triggers`
**Example:**
job: name: test_job
triggers:
- timed: '@daily'
### 🎀 `class triggers.Triggers(registry)`
- **`component_list_type = 'triggers'`** — 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 = 'trigger'`** — 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.
`:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure`
- **`sequence = 50`** — The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
---
### 🏭 `artifactory()`
Artifactory trigger. Trigger if files are added or modified in configured path(s) to watch on chosen Artifactory server. so basically your job gets pinged the second something new drops 📦✨
Requires the Jenkins Artifactory Plugin `https://plugins.jenkins.io/Artifactory`.
**Parameters**
- **`artifactory-server`** (*str*) — Artifactory server where the configured path(s) are monitored from. Available Artifactory servers **must** be configured on Jenkins Global Configuration in advance. (default `''`)
- **`schedule`** (*str*) — cron syntax of when to poll. (default `''`)
- **`paths`** (*str*) — Paths in Artifactory to poll for changes. Multiple paths can be configured by the `';'` separator. (default `''`)
**Example with Single Path to Monitor:**
triggers:
- artifactory: artifactory-server: my-artifactory schedule: H/15 * * * * paths: myrepo/myfolder/latest
**Example with Multiple Paths to Monitor:**
triggers:
- artifactory: artifactory-server: my-artifactory schedule: H 0,8,16 * * * paths: myrepo/myfolder/latest;myrepo/myfolder/commit
---
### 🪣 `bitbucket()`
Trigger a job when bitbucket repository is pushed to. push = build, periodt 💅
Requires the Jenkins BitBucket Plugin `https://plugins.jenkins.io/bitbucket`.
**Example:**
triggers:
- bitbucket
---
### 📊 `build-result()`
Configure jobB to monitor jobA build result. A build is scheduled if there is a new build result that matches your criteria (unstable, failure, ...). it's giving "not me watching my ex-job's every move" 😭
Requires the Jenkins BuildResultTrigger Plugin `https://plugins.jenkins.io/buildresult-trigger`.
**Parameters**
- **`groups`** (*list*) — the groups of jobs + results you wanna keep an eye on
- **`jobs`** (*list*) — the jobs to monitor (**required** — like, you actually need this one, bestie)
- **`results`** (*list*) — which build results to watch for (default is `success`)
- **`combine`** (*bool*) — smash all the job info together. A build only gets scheduled if **every single** condition is met (default `false`)
- **`cron`** (*str*) — the cron syntax you use to poll the jobs for the result you asked for (default `''`)
**Full Example:**
triggers:
- build-result: cron: H/15 * * * * combine: true groups:
- jobs:
- test
- test2 results:
- success
- not-built
- jobs:
- test3 results:
- unstable # Use default results (success):
- jobs:
- test4
- jobs:
**Minimal Example:**
triggers:
- build-result: groups:
- jobs:
- test results:
- aborted
- jobs:
---
### 🐳 `dockerhub-notification()`
The job gets triggered whenever Docker Hub/Registry pings over to say that some Docker image(s) used in this job got rebuilt. very "someone's watching you" of them. 💅
Requires the Jenkins CloudBees Docker Hub Notification plugin: `https://plugins.jenkins.io/dockerhub-notification`.
**Parameters**
- **`referenced-image`** (*bool*) — trigger the job based on the repositories that any compatible docker plugin in this job is using. (default `true`)
- **`repositories`** (*list*) — the specific repositories you want to trigger the job. (default `[]`)
**Minimal Example:**
triggers:
- dockerhub-notification
**Full Example:**
triggers:
- dockerhub-notification: referenced-image: true repositories:
- repo1
- repo2
---
### 🪝 `generic-webhook-trigger()`
Generic webhook trigger. It fires when a set of parameters gets submitted.
Requires the Jenkins Generic Webhook Trigger plugin: `https://plugins.jenkins.io/generic-webhook-trigger`.
**Parameters**
- **`token`** (*str*) — a token to use to trigger the job. (default `''`)
- **`token-credential-id`** (*str*) — a token credential id to use to trigger the job. (default `''`)
- **`print-post-content`** (*bool*) — print post content in the job log.
- **`print-contrib-var`** (*bool*) — print contributed variables in the job log.
- **`silent-response`** (*bool*) — avoid responding with info about the triggered jobs.
- **`cause`** (*str*) — this will be displayed in any triggered job.
- **`regex-filter-expression`** (*str*) — the regular expression to test on the evaluated text you specified in `regex-filter-text`
- **`regex-filter-text`** (*str*) — the text to test against the given `regexp-filter-expression`.
- **`post-content-params`** (*list*) —
parameters to use from the posted JSON/XML. here's the shape of each one:
- **`type`** (*str*) — `JSONPath` or `XPath`
- **`key`** (*str*) — variable name
- **`value`** (*str*) — the expression to evaluate in the POST content. Use JSONPath for JSON or XPath for XML.
- **`regex-filter`** (*str*) — anything in the evaluated value that matches this regular expression gets removed. (optional)
- **`default-value`** (*str*) — this value gets used if the expression doesn't match anything. (optional)
- **`request-params`** (*list*) —
parameters to use passed in as request arguments. each one looks like:
- **`key`** (*str*) — name of the request parameter
- **`regex-filter`** (*str*) — anything in the evaluated value that matches this regular expression gets removed. (optional)
- **`header-params`** (*list*) —
parameters to use passed in as headers. each one looks like:
- **`key`** (*str*) — name of the request header in lowercase. the resulting variable name swaps the `-` characters for `_` instead.
- **`regex-filter`** (*str*) — anything in the evaluated value that matches this regular expression gets removed. (optional)
**Example:**
triggers:
- generic-webhook-trigger: post-content-params:
- type: JSONPath key: action value: $.action regex-filter: value_filter default-value: default_value
- type: XPath key: blah value: whooga regex-filter: value_filer default-value: default_something regex-filter-text: $action regex-filter-expression: ^(opened|reopened|synchronize)$ request-params:
- key: request_test_1 regex-filter: requesT_value_1 header-params:
- key: header_test1 regex-filter: header_value1 print-post-content: true print-contrib-var: true cause: Generic Cause token: blah token-credential-id: token_credential_id silent-response: true
---
### 🧚 `gerrit()`
Trigger on a Gerrit event. ✨
Requires the Jenkins Gerrit Trigger Plugin `https://plugins.jenkins.io/gerrit-trigger` version >= 2.6.0.
**Parameters**
- **`trigger-on`** (*list*) —
the events to react to. pls pick **either** the new `trigger-on`, **or** the old `trigger-on-*` event definitions. you cannot use both at once, that's a vibe clash. 🙈
**Trigger on**
- **`patchset-created-event`** (*dict*) — trigger upon patchset creation.
**Patchset created**
- **`exclude-drafts`** (*bool*) — exclude drafts (default `false`)
- **`exclude-trivial-rebase`** (*bool*) — exclude trivial rebase (default `false`)
- **`exclude-no-code-change`** (*bool*) — exclude no code change (default `false`)
- **`exclude-private`** (*bool*) — exclude private change (default `false`)
- **`exclude-wip`** (*bool*) — exclude wip change (default `false`)
- **`commit-message-contains-regex`** (*str*) — commit message contains regular expression. (default `''`) Requires Gerrit Trigger Plugin >= 2.32.0
> `exclude-private`|`exclude-wip` needs Gerrit Trigger v2.29.0. Exclude drafts|trivial-rebase|no-code-change needs Gerrit Trigger v2.12.0.
- **`patchset-uploaded-event`** — trigger upon patchset creation (this is a alias for `patchset-created-event`).
Deprecated since version 1.1.0: please use `trigger-on`.
- **`change-abandoned-event`** — trigger on patchset abandoned. Requires Gerrit Trigger Plugin version >= 2.8.0.
- **`change-merged-event`** — trigger on change merged
- **`change-restored-event`** — trigger on change restored. Requires Gerrit Trigger Plugin version >= 2.8.0
- **`draft-published-event`** — trigger on draft published event.
- **`ref-updated-event`** — trigger on ref-updated. Gerrit Trigger Plugin version >= 2.29.0
- **`topic-changed-event`** — trigger on topic-changed. Gerrit Trigger Plugin version >= 2.26.0
- **`private-state-changed-event`** — trigger on private state changed event.
- **`wip-state-changed-event`** — trigger on wip state changed event. Gerrit Trigger Plugin version >= 2.8.0
- **`comment-added-event`** (*dict*) — trigger on comment added.
**Comment added**
- **`approval-category`** (*str*) — approval (verdict) category (for example `'APRV'`, `'CRVW'`, `'VRIF'` — see Gerrit access control `https://gerrit-review.googlesource.com/Documentation/access-control.html#access_categories`)
- **`approval-value`** — approval value for the comment added.
- **`comment-added-contains-event`** (*dict*) — trigger on comment added contains Regular Expression.
**Comment added contains**
- **`comment-contains-value`** (*str*) — the Comment has to contain this Regular Expression value, bestie.
- **`trigger-on-patchset-uploaded-event`** (*bool*) — trigger on patchset upload.
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-on-change-abandoned-event`** (*bool*) — trigger on change abandoned. Needs Gerrit Trigger Plugin version >= 2.8.0 ✨
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-on-change-merged-event`** (*bool*) — trigger on change merged.
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-on-change-restored-event`** (*bool*) — trigger on change restored. Needs Gerrit Trigger Plugin version >= 2.8.0 ✨
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-on-comment-added-event`** (*bool*) — trigger on comment added.
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-on-draft-published-event`** (*bool*) — trigger on draft published event.
> Deprecated since version 1.1.0: Please use `trigger-on`.
- **`trigger-on-ref-updated-event`** (*bool*) — trigger on ref-updated.
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-approval-category`** (*str*) — the approval category for comment added.
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`trigger-approval-value`** (*int*) — the approval value for comment added.
> Deprecated since version 1.1.0.: Please use `trigger-on`.
- **`override-votes`** (*bool*) — override the default vote values 🗳️
- **`gerrit-build-started-verified-value`** (*int*) — the started `''Verified''` value.
- **`gerrit-build-successful-verified-value`** (*int*) — the successful `''Verified''` value.
- **`gerrit-build-failed-verified-value`** (*int*) — the failed `''Verified''` value.
- **`gerrit-build-unstable-verified-value`** (*int*) — the unstable `''Verified''` value.
- **`gerrit-build-notbuilt-verified-value`** (*int*) — the not built `''Verified''` value.
- **`gerrit-build-aborted-verified-value`** (*int*) — the aborted `''Verified''` value. Needs Gerrit Trigger Plugin version >= 2.31.0 ✨
- **`gerrit-build-started-codereview-value`** (*int*) — the started `''CodeReview''` value.
- **`gerrit-build-successful-codereview-value`** (*int*) — the successful `''CodeReview''` value.
- **`gerrit-build-failed-codereview-value`** (*int*) — the failed `''CodeReview''` value.
- **`gerrit-build-unstable-codereview-value`** (*int*) — the unstable `''CodeReview''` value.
- **`gerrit-build-notbuilt-codereview-value`** (*int*) — the not built `''CodeReview''` value.
- **`gerrit-build-aborted-codereview-value`** (*int*) — the aborted `''CodeReview''` value. Needs Gerrit Trigger Plugin version >= 2.31.0 ✨
- **`failure-message`** (*str*) — the message to leave on failure (default `''`).
- **`successful-message`** (*str*) — the message to leave on success (default `''`).
- **`unstable-message`** (*str*) — the message to leave when unstable (default `''`).
- **`notbuilt-message`** (*str*) — the message to leave when not built (default `''`).
- **`aborted-message`** (*str*) — the message to leave when aborted (default `''`).
- **`failure-message-file`** (*str*) — sets the filename **within the workspace** from which to retrieve the unsuccessful review message. (optional) 📄
- **`projects`** (*list*) — the list of projects to match, duh.
**Project**
- **`project-compare-type`** (*str*) — `''PLAIN''`, `''ANT''` or `''REG_EXP''`
- **`project-pattern`** (*str*) — the project name pattern to match
- **`branch-compare-type`** (*str*) — `''PLAIN''`, `''ANT''` or `''REG_EXP''` (not used if the branches list is specified)
> Deprecated since version 1.1.0: Please use `branches`.
- **`branch-pattern`** (*str*) — the branch name pattern to match (not used if the branches list is specified)
> Deprecated since version 1.1.0: Please use `branches`.
- **`branches`** (*list*) — the list of branches to match (optional)
**Branch**
- **`branch-compare-type`** (*str*) — `''PLAIN''`, `''ANT''` or `''REG_EXP''` (optional) (default `''PLAIN''`)
- **`branch-pattern`** (*str*) — the branch name pattern to match
- **`file-paths`** (*list*) — the list of file paths to match (optional)
**File Path**
- **`compare-type`** (*str*) — `''PLAIN''`, `''ANT''` or `''REG_EXP''` (optional) (default `''PLAIN''`)
- **`pattern`** (*str*) — the file path pattern to match
- **`forbidden-file-paths`** (*list*) — the list of file paths to skip triggering for (optional) 🚫
**Forbidden File Path**
- **`compare-type`** (*str*) — `''PLAIN''`, `''ANT''` or `''REG_EXP''` (optional) (default `''PLAIN''`)
- **`pattern`** (*str*) — the file path pattern to match
- **`topics`** (*list*) — the list of topics to match (optional)
**Topic**
- **`compare-type`** (*str*) — `''PLAIN''`, `''ANT''` or `''REG_EXP''` (optional) (default `''PLAIN''`)
- **`pattern`** (*str*) — the topic name pattern to match
- **`disable-strict-forbidden-file-verification`** (*bool*) — turning this on lets an event trigger a build if the event contains **BOTH** one or more wanted file paths **AND** one or more forbidden file paths. In other words, with this option, the build will **not** get triggered if the change contains *only* forbidden files, otherwise it *will* get triggered. Needs plugin version >= 2.16.0 (default `false`) 👀
- **`skip-vote`** (*dict*) — a map of build outcomes for which Jenkins must skip voting. Needs Gerrit Trigger Plugin version >= 2.7.0 ✨
**Outcome**
- **`successful`** (*bool*)
- **`failed`** (*bool*)
- **`unstable`** (*bool*)
- **`notbuilt`** (*bool*)
- **`aborted`** (*bool*) — Needs Gerrit Trigger Plugin version >= 2.31.0 ✨
- **`silent`** (*bool*) — when silent mode is on there will be **no** communication back to Gerrit, i.e. no build started/failed/successful approve messages etc. If other non-silent jobs are triggered by the same Gerrit event as this job, the result of this job's build will not be counted in the end result of the other jobs. (default `false`) 🤫
- **`silent-start`** (*bool*) — sets silent start mode to on or off. When silent start mode is on there will be no `'build started'` messages sent back to Gerrit. (default `false`)
- **`escape-quotes`** (*bool*) — escape quotes in the values of Gerrit change parameters (default `true`)
- **`build-cancellation-policy`** (*dict*) — if you use this, rules for cancelling builds can be set right here when patchsets of the same change come in. This setting overrides the global server configuration. If `build-cancellation-policy` isn't present in the YAML, the global server configuration is used instead. Needs Gerrit Trigger Plugin version >= 2.32.0 💅
**Options**
- **`abort-new-patchsets`** (*bool*) — only running jobs get cancelled if a new patch version is pushed over (default `false`).
- **`abort-manual-patchsets`** (*bool*) — builds triggered manually get aborted when a new patch set arrives (default `false`).
- **`abort-same-topic`** (*bool*) — builds triggered with a topic get aborted when a new patch set with the same topic arrives (default `false`).
- **`no-name-and-email`** (*bool*) — do not pass the compound `'name and email'` parameters (default `false`)
> Deprecated since version 3.5.0: Please use the `name-and-email-parameter-mode` parameter instead.
- **`readable-message`** (*bool*) — whether parameters that involve multiline text, like the commit message, should be human readable or not. If `false`, those parameters get Base64 encoded to keep your environment variables clean. (default `false`) 🧼
> **Deprecated since version 3.5.0:** bestie please use the `commit-message-parameter-mode` parameter instead 💅
- **`name-and-email-parameter-mode`** (*str*) — this one's the parameter mode for the compound **"name and email"** parameters (think `GERRIT_PATCHSET_UPLOADER` or `GERRIT_CHANGE_OWNER`). You got three choices: `'NONE'` so it just... does not pass the parameter at all, `'PLAIN'` so it passes the parameter in human readable form, or `'BASE64'` so it passes the parameter in base64 encoded form. Default is `'PLAIN'`. Needs Gerrit Trigger Plugin version >= 2.18.0 ✨
- **`commit-message-parameter-mode`** (*str*) — the parameter mode for the `GERRIT_CHANGE_COMMIT_MESSAGE` parameter. Same three options: `'NONE'` (skip passing the parameter all together), `'PLAIN'` (human readable form), or `'BASE64'` (base64 encoded form). Default is `'BASE64'`. Requires Gerrit Trigger Plugin version >= 2.18.0 🫶
- **`change-subject-parameter-mode`** (*str*) — the parameter mode for the `GERRIT_CHANGE_SUBJECT` parameter. Yep, again: `'NONE'` to not pass it at all, `'PLAIN'` for human readable, `'BASE64'` for base64 encoded. Default `'PLAIN'`. Requires Gerrit Trigger Plugin version >= 2.18.0 🌸
- **`comment-text-parameter-mode`** (*str*) — the parameter mode for the `GERRIT_EVENT_COMMENT_TEXT` parameter. Same trio of vibes: `'NONE'`, `'PLAIN'`, or `'BASE64'`. Default `'BASE64'`. Requires Gerrit Trigger Plugin version >= 2.18.0 💖
- **`dependency-jobs`** (*str*) — literally every job this job depends on. If one commit should trigger both a dependency *and* this job, the dependency gets built first, no skipping the line. Separate job names with commas. ⚠️ Beware of cyclic dependencies, that's giving infinite-loop nightmare fuel. (optional)
- **`notification-level`** (*str*) — decides who gets the email notifications. Pick your fighter: `'NONE'` (nobody), `'OWNER'` (the change owner), `'OWNER_REVIEWERS'` (reviewers plus the change owner), `'ALL'` (all interested users, i.e. owning, reviewing, watching, and starring) or `'SERVER_DEFAULT'` (the server default). Default is `'SERVER_DEFAULT'` 📧
- **`dynamic-trigger-enabled`** (*bool*) — turn the dynamic trigger on or off. Default is false.
- **`dynamic-trigger-url`** (*str*) — if you specify this option, the Gerrit trigger configuration gets fetched from there on a regular interval 🔁
- **`trigger-for-unreviewed-patches`** (*bool*) — this one triggers `patchset-created` events for changes that were uploaded while the connection to Gerrit was down. Default is false. Requires Gerrit Trigger Plugin version >= 2.11.0.
> **Deprecated since version 3.5.0:** only supported for Gerrit Trigger Plugin versions < 2.14.0. Go peep the Missed Events Playback Feature at `https://plugins.jenkins.io/gerrit-trigger/#plugin-content-missed-events-playback-feature-available-from-v-2140` 👀
- **`custom-url`** (*str*) — a custom URL for a message sent to Gerrit. If it's empty, the build details URL gets used instead. Default is `''`.
- **`server-name`** (*str*) — the name of the server to trigger on, or `''__ANY__''` to trigger on any configured Gerrit server (default `'__ANY__'`). Requires Gerrit Trigger Plugin version >= 2.11.0 💜
---
You may select one or more Gerrit events upon which to trigger, bestie — pick as many as your heart desires. You must also supply at least one project and branch, optionally more. And if you select the `comment-added` trigger, you should also indicate which approval category and value you want to trigger the job. ikyk 😌
Okay so real talk: until version 0.4.0 of Jenkins Job Builder, `camelCase` keys were used to configure Gerrit Trigger Plugin instead of hyphenated-keys. While still supported, camedCase keys are deprecated and should not be used. Support for this will be removed after 1.0.0 is released. So stop using them, fr fr 🙈
Example:
triggers:
- gerrit: trigger-on:
- patchset-created-event: exclude-drafts: true exclude-trivial-rebase: true exclude-no-code-change: true exclude-private: true exclude-wip: true commit-message-contains-regex: "regex"
- comment-added-event: approval-category: 'APRV' approval-value: 1 projects:
- project-compare-type: 'PLAIN' project-pattern: 'test-project' branches:
- branch-compare-type: 'PLAIN' branch-pattern: 'master'
- branch-compare-type: 'PLAIN' branch-pattern: 'stable' file-paths:
- compare-type: ANT pattern: subdirectory/** topics:
- compare-type: ANT pattern: refactor-xy** skip-vote: successful: true failed: true unstable: true notbuilt: true aborted: true build-cancellation-policy: abort-new-patchsets: false abort-manual-patchsets: true abort-same-topic: true silent: false silent-start: true escape-quotes: false dependency-jobs: 'job1, job2' name-and-email-parameter-mode: PLAIN notification-level: ALL dynamic-trigger-enabled: true dynamic-trigger-url: http://myhost/mytrigger server-name: my-server failure-message-file: path/to/filename
### 🌈 github() 🌈
Trigger a job when a github repository is pushed to. That's it, that's the whole vibe 🫶
Requires the Jenkins GitHub Plugin — `https://plugins.jenkins.io/github`.
Example:
triggers:
- github
### 💅 github-pull-request() 💅
Build pull requests in github and report results. Main character energy for your PRs ✨
Requires the Jenkins GitHub Pull Request Builder Plugin — `https://plugins.jenkins.io/ghprb`.
**Parameters**
- **`admin-list`** (*list*) — the users with admin rights (optional) 👑
- **`white-list`** (*list*) — users whose pull requests build (optional)
- **`org-list`** (*list*) — orgs whose users should be white listed (optional)
- **`allow-whitelist-orgs-as-admins`** (*bool*) — members of white listed orgs will have admin rights. Default is false.
- **`cron`** (*str*) — cron syntax of when to run (optional) ⏰
- **`trigger-phrase`** (*str*) — when filled, commenting this phrase in the pull request will trigger a build (optional)
- **`only-trigger-phrase`** (*bool*) — only commenting the trigger phrase in the pull request will trigger a build. Default is false.
- **`skip-build-phrase`** (*str*) — when filled, adding this phrase to the pull request title or body will **not** trigger a build (optional) 🚫
- **`black-list-commit-author`** (*list*) — when filled, pull request commits from this user(s) will not trigger a build (optional)
- **`black-list-labels`** (*str*) — list of GitHub labels for which the build should not be triggered (optional)
- **`white-list-labels`** (*str*) — list of GitHub labels for which the build should only be triggered. (Leave blank for `'any'`) (optional)
- **`github-hooks`** (*bool*) — use github hook. Default is false.
- **`permit-all`** (*bool*) — build every pull request automatically without asking. Default is false.
- **`auto-close-on-fail`** (*bool*) — close failed pull request automatically. Default is false.
- **`display-build-errors-on-downstream-builds`** (*bool*) — Display build errors on downstream builds. Default is false.
- **`white-list-target-branches`** (*list*) — adding branches to this whitelist allows you to selectively test pull requests destined for these branches only. Supports regular expressions (e.g. `'master'`, `'feature-.*'`). (optional) 🌿
- **`black-list-target-branches`** (*list*) — adding branches to this blacklist allows you to selectively prevent pull requests builds destined for these branches. Supports regular expressions (e.g. `'master'`, `'feature-.*'`). (optional)
- **`auth-id`** (*str*) — the auth id to use (optional)
- **`build-desc-template`** (*str*) — the template for build descriptions in jenkins (optional)
- **`status-context`** (*str*) — the context to include on PR status comments (optional)
- **`triggered-status`** (*str*) — the status message to set when the build has been triggered (optional)
- **`started-status`** (*str*) — the status comment to set when the build has been started (optional)
- **`status-url`** (*str*) — the status URL to set (optional)
- **`status-add-test-results`** (*bool*) — add test result one-liner to status message (optional) 🎀
- **`secret-token`** (str) — the secret token for build trigger ✨
- **`force-build-labels`** (str) — labels that launch a build if they're added (comma-separated) 🏷️
- **`merge-request-label-filter-config`** (dict) — if you use it, it lets you filter merge requests by labels 💅
**Options**
- **`include`** (str) — run for specified labels.
- **`exclude`** (str) — do <red>not</red> run for specified labels.
- <purple>**`All`**</purple> — every single branch is allowed to trigger this job. no gatekeeping, bestie 💅
- <cyan>**`NameBasedFilter`**</cyan> — filters branches by *name*. you list the source branches that are allowed to trigger a build from a Push event or a Merge Request event. if you leave <rainbow>both</rainbow> fields empty, all branches get to trigger this job. lowkey generous of you. and for Merge Request events, only the *target* branch name gets filtered out by the `include-branches` and `exclude-branches` lists. iykyk 🦋
- <pink>**`RegexBasedFilter`**</pink> — filters branches by regex. the target branch regex lets you limit the execution of this job to certain branches only. any branch that matches the specified pattern in `target-branch-regex` and `source-branch-regex` triggers the job. no filtering happens at all if the field is left empty. periodt ✨
---
<purple>**Example (version < 1.1.26):**</purple>
triggers:
- gitlab: trigger-push: true trigger-merge-request: true trigger-open-merge-request-push: true ci-skip: true set-build-description: true add-note-merge-request: true add-vote-merge-request: true add-ci-message: true allow-all-branches: true include-branches:
- 'master'
- 'master2'
- 'local-test' exclude-branches:
- 'broken-test'
- 'master-foo'
<purple>**Minimal example (version >= 1.1.26):**</purple>
triggers:
- gitlab
<purple>**Full example (version >= 1.1.26):**</purple>
triggers:
- gitlab: trigger-push: false trigger-merge-request: false trigger-only-if-new-commits-pushed: false trigger-open-merge-request-push: both ci-skip: false set-build-description: false add-note-merge-request: false add-vote-merge-request: false add-ci-message: true allow-all-branches: true include-branches:
- 'master'
- 'master2'
- 'local-test' exclude-branches:
- 'broken-test'
- 'master-foo' pending-build-name: 'test'
---
### 💖 `gitlab-merge-request()` 💖
Builds merge requests in gitlab and reports the results back. she's giving *communication* 🫶
<pink>Needs the Jenkins Gitlab MergeRequest Builder Plugin</pink> <https://plugins.jenkins.io/ghprb>.
<bold>Parameters</bold>
- **`cron`** (*str*) — Cron syntax of when to run (**required**, bestie, you *have* to give her this one)
- **`project-path`** (*str*) — Gitlab-relative path to project (**required**)
- **`target-branch-regex`** (*str*) — Allow execution of this job for certain branches only (default `''`). Requires Gitlab MergeRequest Builder Plugin >= 2.0.0
- **`use-http-url`** (*str*) — Use the HTTP(S) URL to fetch/clone repository (default `false`)
- **`assignee-filter`** (*str*) — Only MRs with this assigned user will trigger the build automatically (default `'jenkins'`)
- **`tag-filter`** (*str*) — Only MRs with this label will trigger the build automatically (default `'Build'`)
- **`trigger-comment`** (*str*) — Force build if this comment is the last in merge reguest (default `''`)
- **`publish-build-progress-messages`** (*str*) —
Publish build progress messages (except build failed) (default `true`)
> <red>Deprecated since version 2.0.0.</red> she's retired, don't come for her 💀
- **`auto-close-failed`** (*str*) — On failure, auto close the request (default `false`)
- **`auto-merge-passed`** (*str*) — On success, auto merge the request (default `false`)
<purple>**Example (version < 2.0.0):**</purple>
triggers:
- gitlab-merge-request: cron: '* * * * *' project-path: 'test/project' use-http-url: false assignee-filter: 'jenkinsbot' tag-filter: 'fix' trigger-comment: 'rebuild' publish-build-progress-messages: true auto-close-failed: false auto-merge-passed: false
<purple>**Example (version >= 2.0.0):**</purple>
triggers:
- gitlab-merge-request: cron: '* * * * ' project-path: 'test/project' target-branch-regex: '(.release.|.hotfix.*)' use-http-url: false assignee-filter: 'jenkinsbot' tag-filter: 'fix' trigger-comment: 'rebuild' auto-close-failed: false auto-merge-passed: false
---
### 🌸 `gogs()` 🌸
Trigger a job when gogs repository is pushed to. she's *watching* 👀
<pink>Needs the Jenkins Gogs Plugin</pink> <https://plugins.jenkins.io/gogs-webhook>.
<bold>Example:</bold>
triggers:
- gogs
---
### ✨ `groovy-script()` ✨
Triggers the job using a groovy script. scripted queen behavior, honestly 👑
<pink>Needs the Jenkins ScriptTrigger Plugin</pink> <https://plugins.jenkins.io/scripttrigger>.
<bold>Parameters</bold>
- **`system-script`** (*bool*) — If `true`, run the groovy script as a system script, the script will have access to the same variables as the Groovy Console. If `false`, run the groovy script on the executor node, the script will not have access to the hudson or job model. (default `false`)
- **`script`** (*str*) — Content of the groovy script. If the script result is evaluated to `true`, a build is scheduled. (default `''`)
- **`script-file-path`** (*str*) — Groovy script path. (default `''`)
- **`property-file-path`** (*str*) — Property file path. All properties will be set as parameters for the triggered build. (default `''`)
- **`enable-concurrent`** (*bool*) — Enable concurrent build. (default `false`)
- **`label`** (*str*) — Restrict where the polling should run. (default `''`)
- **`cron`** (*str*) — cron syntax of when to run (default `''`)
<bold>Full Example:</bold>
triggers:
- groovy-script: script: groovy-content script-file-path: path/to/filename property-file-path: /path/to/properties/file cron: H/15 * * * * enable-concurrent: true label: master system-script: true
<bold>Minimal Example:</bold>
triggers:
- groovy-script
---
### 🎀 `ivy()` 🎀
Poll with an Ivy script. polling era, we love her 🦋
<pink>Needs the Jenkins IvyTrigger Plugin</pink> <https://plugins.jenkins.io/ivytrigger>.
<bold>Parameters</bold>
- **`path`** (*str*) — Path of the ivy file. (optional)
- **`settings-path`** (*str*) — Ivy Settings Path. (optional)
- **`properties-file`** (*list*) — List of properties file path. Properties will be injected as variables in the ivy settings file. (optional)
- **`properties-content`** (*str*) — Properties content. Properties will be injected as variables in the ivy settings file. (optional)
- **`debug`** (*bool*) — Active debug mode on artifacts resolution. (default `false`)
- **`download-artifacts`** — Download artifacts for dependencies to see if they have changed. (default `true`)
- **`enable-concurrent`** (*bool*) — Enable Concurrent Build. (default `false`)
- **`label`** (*str*) — Restrict where the polling should run. (default `''`)
- **`cron`** (*str*) — cron syntax of when to run (default `''`)
<bold>Example:</bold>
triggers:
- ivy: path: path/to/file settings-path: path/to/settings/file properties-file:
- 'filename1'
- 'filename2' debug: true cron: 'H/15 * * * *' enable-concurrent: False label: master
---
### 💜 `jira-changelog()` 💜
Sets up a trigger that listens to JIRA issue changes. she's *perched*, she hears everything 🧚
- **`jql-filter`** (*str*) — the JQL that has to match the updated issues for a build to even pop off. <purple>(default `''`)</purple> ✨
- **`changelog-matchers`** (*list*) — your lil' set of who-changed-what detectors 👀
### 💅 Custom Field Matcher
- **`custom-field-name`** (*str*) — the custom field name that got changed while the issue was being updated. <purple>(default `''`)</purple>
- **`compare-new-value`** (*bool*) — like, actually compare the *new* value of the updated field? <purple>(default `false`)</purple>
- **`new-value`** (*str*) — the new value of the updated field. <purple>(default `''`)</purple>
- **`compare-old-value`** (*bool*) — compare the *old* value of the updated field? <purple>(default `false`)</purple>
- **`old-value`** (*str*) — the value from *before* the field got updated, bestie. <purple>(default `''`)</purple>
### 🌸 JIRA Field Matcher
- **`jira-field-ID`** (*str*) — the JIRA Field ID that got changed during the issue update. <purple>(default `''`)</purple>
- **`compare-new-value`** (*bool*) — compare the new value of the updated field. <purple>(default `false`)</purple>
- **`new-value`** (*str*) — the new value of the updated field. <purple>(default `''`)</purple>
- **`compare-old-value`** (*bool*) — compare the old value of the updated field. <purple>(default `false`)</purple>
- **`old-value`** (*str*) — the value before the field got updated. <purple>(default `''`)</purple>
- **`parameter-mapping`** (*list*) — mapping time, no cap 🗺️
### 🎀 Issue Attribute Path
- **`jenkins-parameter`** (*str*) — the Jenkins parameter name. <purple>(default `''`)</purple>
- **`issue-attribute-path`** (*str*) — the attribute path. <purple>(default `''`)</purple>
---
<pink>Minimal Example:</pink> (the bare-minimum slay 💅)
triggers:
- jira-changelog
<pink>Full Example:</pink> (main character energy, all the options out 🫶)
triggers:
- jira-changelog: jql-filter: filter changelog-matchers:
- field-type: 'CUSTOM' field: name new-value: val1 old-value: val2 compare-new-value: true compare-old-value: true
- field-type: 'JIRA' field: versions new-value: val3 old-value: val4 compare-new-value: true compare-old-value: true parameter-mapping:
- jenkins-parameter: param issue-attribute-path: path
---
### 🌈 `jira-comment-trigger()`
Trigger builds the *moment* a comment gets dropped onto JIRA. 💬✨
Requires the Jenkins JIRA Trigger Plugin <https://plugins.jenkins.io/jira-trigger>.
**Parameters**
- **`jql-filter`** (*str*) — must match the updated issues to trigger a build. <purple>(default `''`)</purple>
- **`comment-pattern`** (*str*) — only pops off a build when the comment added to JIRA matches this pattern. <purple>(default `'(?i)build this please'`)</purple> (she really said "build this please" fr fr 😌)
- **`parameter-mapping`** (*list*) — mapping time again 🗺️
### 🎀 Issue Attribute Path
- **`jenkins-parameter`** (*str*) — Jenkins parameter name. <purple>(default `''`)</purple>
- **`issue-attribute-path`** (*str*) — attribute path. <purple>(default `''`)</purple>
<pink>Minimal Example:</pink>
triggers:
- jira-comment-trigger
<pink>Full Example:</pink>
triggers:
- jira-comment-trigger: jql-filter: filter comment-pattern: comment parameter-mapping:
- jenkins-parameter: param1 issue-attribute-path: 'path/to/attribute'
---
### 🦋 `jms-messaging()`
The JMS Messaging Plugin is giving *so many* features, bestie, it literally provides all of this:
- A build trigger to submit jenkins jobs upon receipt of a matching message. 📨
- A builder that may be used to submit a message to the topic upon the completion of a job. 🏗️
- A post-build action that may be used to submit a message to the topic upon the completion of a job. 🏁
JMS Messaging provider types supported (the VIP list 👑):
- ActiveMQ
- FedMsg
Requires the Jenkins JMS Messaging Plugin <https://plugins.jenkins.io/jms-messaging>.
**Parameters**
- **`no-squash`** (*bool*) — `true` = schedule a new job for every single triggering message. <purple>(default `false`)</purple> Normally if a job is queued and another triggering message comes through, a new job is *not* submitted and the job gets "squashed" into the job that's already queued. Setting this option to `'True'` forces a brand-new job to be submitted for every triggering message that arrives. No squashing, no folding, no compressing — periodt. 💅
- **`override-topic`** (*str*) — if you need to override the default topic. <purple>(default `''`)</purple>
- **`selector`** (*str*) — the JSON or YAML formatted text that conforms to the schema for defining the various OpenShift resources. <purple>(default `''`)</purple> note: topic needs to be in double quotes ex. `topic = "org.fedoraproject.prod.fedimg.image.upload"` 🧚
- **`provider-name`** (*str*) — name of the message provider setup in the global config. <purple>(default `''`)</purple>
- **`checks`** (*list*) — list of checks to monitor. <purple>(default `[]`)</purple>
- **`field`** (*str*) — check the body of messages for a field. <purple>(default `''`)</purple>
- **`expected-value`** (*str*) — expected value for the field. regex <purple>(default `''`)</purple>
<pink>Full Example:</pink>
triggers:
- jms-messaging: no-squash: True selector: topic = "org.fedoraproject.prod.fedimg.image.upload" provider-name: fedmsg checks:
- field: compose expected-value: .+compose_id.+Fedora-Atomic.+
- field: image_name expected-value: .+Fedora-Atomic.+
<pink>Minimal Example:</pink>
triggers:
- jms-messaging: selector: topic = "org.fedoraproject.prod.fedimg.image.upload" provider-name: fedmsg
---
### 🎀 `monitor-files()`
Configure Jenkins to monitor files. 👀📁 Requires the Jenkins Filesystem Trigger Plugin <https://plugins.jenkins.io/fstrigger>.
**Parameters**
- **`files`** (*list*) — list of files to monitor 📂
### 🌸 File
- **`path`** (*str*) — file path to monitor. You can use a pattern that specifies a set of files if you don't know the real file path. **(required)** ⚠️
- **`strategy`** (*str*) — choose your strategy if there's more than one matching file. Can be one of Ignore file (`'IGNORE'`) or Use the most recent (`'LATEST'`). <purple>(default `'LATEST'`)</purple>
- **`check-content`** (*list*) — list of content changes of the file to monitor 🔍
### 💜 Content Nature
- **`simple`** (*bool*) — trigger on change in content of the specified file (whatever the type file). <purple>(default `false`)</purple>
- **`jar`** (*bool*) — trigger on change in content of the specified JAR file. <purple>(default `false`)</purple>
- **`tar`** (*bool*) — trigger on change in content of the specified Tar file. <purple>(default `false`)</purple>
- **`zip`** (*bool*) — trigger on change in content of the specified ZIP file. <purple>(default `false`)</purple>
- **`source-manifest`** (*list*) — trigger on change to MANIFEST files. 📜
### 🦋 MANIFEST File
- **`keys`** (*list*) — list of keys to inspect. (optional)
- **`all-keys`** (*bool*) — if true, take into account all keys. <purple>(default `true`)</purple>
- **`jar-manifest`** (*list*) — trigger on change to MANIFEST files (contained in jar files). 🫙
### 🦋 MANIFEST File
- **`keys`** (*list*) — list of keys to inspect. (optional)
- **`all-keys`** (*bool*) — if true, take into account all keys. <purple>(default `true`)</purple>
- **`properties`** (*list*) — monitor the contents of the properties file. 📝
### ⭐ Properties File
- **`keys`** (`list`) — the list of keys you wanna go look at. (<italic>optional</italic>)
- **`all-keys`** (`bool`) — if this is <green>true</green>, bestie, we're taking **all** the keys into account. no leaving anyone out. (default <green>true</green>)
- **`xml`** (`list str`) — trigger a build whenever the listed XPath expressions change. 💅
- **`text`** (`list str`) — trigger a build whenever the listed regular expressions change.
- **`ignore-modificaton-date`** (`bool`) — if it's <green>true</green>, we literally ignore the file modification date. <yellow>heads up:</yellow> this is **only** valid when content changes of the file are being monitored. (default <green>true</green>)
- **`cron`** (`str`) — the cron syntax of when to run. (default `''`)
---
### ✨ the minimal example (fr fr, it's giving minimalist queen) ✨
triggers:
- monitor-files: files:
- path: 'path1'
### 🌸 the full example 🌸
triggers:
- monitor-files: cron: '* * * * *' files:
- path: 'path1' strategy: 'IGNORE'
- path: 'path2' check-content:
- simple: true
- jar: true
- tar: true
- zip: true
- source-manifest:
- all-keys: false keys:
- key1
- key2
- jar-manifest:
- keys:
- key1
- key2
- properties:
- all-keys: false keys:
- prop1
- prop2
- xml:
- 'xpath1'
- 'xpath2'
- text:
- 'regex1' ignore-modificaton-date: false
---
## 🦋 `monitor-folders()` 🦋
Okay so this one configures Jenkins to monitor **folders**. full folder surveillance era. 👑
> <yellow>it needs the Jenkins Filesystem Trigger Plugin</yellow> 👉 <https://plugins.jenkins.io/fstrigger>
### 💖 parameters 💖
- **`path`** (`str`) — the folder path to poll. (default `''`)
- **`includes`** (`list`) — the Fileset includes setting, aka the list of includes files. the basedir of the fileset is relative to the workspace root. if you don't set a value, **all** files get used. slay. (default `''`)
- **`excludes`** (`str`) — the `'excludes'` pattern. a file that matches this mask will <red>not</red> be polled, even if it matches the mask you put in the `'includes'` section. sorry bestie, the exclude wins. (default `''`)
- **`check-modification-date`** (`bool`) — check the last modification date. (default <green>true</green>)
- **`check-content`** (`bool`) — check the content. (default <green>true</green>)
- **`check-fewer`** (`bool`) — check fewer files. (default <green>true</green>)
- **`cron`** (`str`) — the cron syntax of when to run. (default `''`)
### 🔥 full example 🔥
triggers:
- monitor-folders: path: 'pathname' includes:
- 'pattern1'
- 'pattern2' excludes: 'pattern1' check-modification-date: false check-content: false check-fewer: false cron: H/15 * * * *
### 🎀 minimal example 🎀
triggers:
- monitor-folders
---
## ⏰ `parameterized-timer()` ⏰
Trigger builds **with parameters** at certain times. not just any build bestie, a *parameterized* one. required plugin: Jenkins Parameterized Scheduler Plugin 👉 <https://plugins.jenkins.io/parameterized-scheduler>
### parameters
- **`cron`** (`str`) — the cron syntax of when to run **and with which parameters**. (<red>required</red>, so don't you dare skip it)
### example
triggers:
- parameterized-timer: cron: "@midnight % PARAM=value"
---
## 💀 `pollscm()` 💀
Poll the SCM to find out if there's been a change. the classic "are we there yet" energy.
### parameter
- the polling interval (cron syntax)
> <rainbow>Deprecated since version 1.3.0.</rainbow> please just use `cron` instead, babe.
### parameters
- **`cron`** (`str`) — the polling interval (cron syntax, <red>required</red>)
- **`ignore-post-commit-hooks`** (`bool`) — ignore changes notified by SCM post-commit hooks. the `subversion-plugin` supports this since version `1.44`. iykyk. (default <green>false</green>)
### example
triggers:
- pollscm: cron: "*/30 * * * *" ignore-post-commit-hooks: True
---
## 🌈 `pollurl()` 🌈
Trigger when the HTTP response from a URL changes. the URL url-ing differently?? build. 💅 required plugin: Jenkins URLTrigger Plugin 👉 <https://plugins.jenkins.io/urltrigger>
### parameters
- **`cron`** (`str`) — the cron syntax of when to run. (default `''`)
- **`polling-node`** (`str`) — restrict where the polling should run. (<italic>optional</italic>)
- **`urls`** (`list`) — the list of URLs to monitor 👇
### URL
- **`url`** (`str`) — the URL to monitor for changes (<red>required</red>)
- **`proxy`** (`bool`) — activate the Jenkins proxy. (default <green>false</green>)
- **`timeout`** (`int`) — connect/read timeout in seconds. (default `300`)
- **`username`** (`str`) — user name for basic authentication. (<italic>optional</italic>)
- **`password`** (`str`) — password for basic authentication. (<italic>optional</italic>)
- **`check-status`** (`int`) — check for a specific HTTP status code. (<italic>optional</italic>)
- **`check-etag`** (`bool`) — check the HTTP ETag for changes. (default <green>false</green>)
- **`check-date`** (`bool`) — check the last modification date of the URL. (default <green>false</green>)
- **`check-content`** (`list`) — the list of content type changes to monitor 👇
### Content Type
- **`simple`** (`bool`) — trigger on any change to the content of the URL. (default <green>false</green>)
- **`json`** (`list`) — trigger on any change to the listed JSON paths.
- **`text`** (`list`) — trigger on any change to the listed regular expressions.
- **`xml`** (`list`) — trigger on any change to the listed XPath expressions.
### example
triggers:
- pollurl: cron: '* * * * *' polling-node: 'label expression' urls:
- url: 'http://example.com/url1' proxy: false timeout: 442 username: username password: sekr3t check-status: 202 check-etag: false check-date: true check-content:
- simple: true
- json:
- '$..author'
- '$.store..price'
- url: 'http://example.com/url2' proxy: true check-etag: true check-content:
- simple: false
- xml:
- '//author'
- '/store//price'
- text:
- '\d+'
- url: 'http://example.com/url1' proxy: false timeout: 442 username: username password: sekr3t check-status: 202 check-etag: false check-date: true check-content:
---
## 🐰 `rabbitmq()` 🐰
This plugin triggers a build using a remote build message in a RabbitMQ queue. it's giving ✨message queue magic✨.
> <yellow>needs the Jenkins RabbitMQ Build Trigger Plugin</yellow> 👉 <https://plugins.jenkins.io/rabbitmq-build-trigger>
### parameters
- **`token`** (`str`) — the build token expected in the message queue (<red>required</red>)
- **`filters`** (`list`) — the list of filters to apply (<italic>optional</italic>) 👇
### Filter
- **`field`** (`str`) — some field in the message (<red>required</red>)
- **`value`** (`str`) — the value of the specified field (<red>required</red>)
### example
triggers:
- rabbitmq: token: 'build_trigger_token'
### example with filters
triggers:
- rabbitmq: token: 'build_trigger_token' filters:
- field: 'field1' value: 'value1'
- field: 'field2' value: 'value2'
---
## 👑 `reverse()` 👑
Okay bestie, this trigger can be configured in the UI using the checkbox with the following text: `'Build after other projects are built'`. iconic label tbh.
Set up a trigger so that when some other projects finish building, a new build gets scheduled for **this** project. super convenient for running an extensive test after a build is complete, for example. main character downstream energy. 🫶
This configuration complements the `"Build other projects"` section in the `"Post-build Actions"` of an upstream project, but it's preferable when you wanna configure the **downstream** project instead.
### parameters
- **`jobs`** (`str`) — list of jobs to watch. can be either a comma separated list or a list. 👀
- **`result`** (`str`) — the build results to monitor for, between the following options: `success`, `unstable` and `failure`. (default `'success'`)
### example
triggers:
triggers:
- reverse: jobs: 'Fantastic-job' result: 'failure'
Example List:
triggers:
- reverse: jobs:
- 'a'
- 'b'
- 'c' result: 'failure'
### <pink>`script()`</pink> 🎬
Triggers the job using shell or batch script.
Requires the Jenkins ScriptTrigger Plugin <https://plugins.jenkins.io/scripttrigger>.
**Parameters**
- **`label`** (*str*) — Restrict where the polling should run. (default `''`)
- **`script`** (*str*) — A shell or batch script. (default `''`)
- **`script-file-path`** (*str*) — A shell or batch script path. (default `''`)
- **`cron`** (*str*) — cron syntax of when to run (default `''`)
- **`enable-concurrent`** (*bool*) — Enables triggering concurrent builds. (default `false`)
- **`exit-code`** (*int*) — If the exit code of the script execution returns this expected exit code, a build is scheduled. (default `0`)
Full Example:
triggers:
- script: script: 'exit 0' script-file-path: '$WORKSPACE/scripts' cron: 'H/15 * * * *' enable-concurrent: true label: master exit-code: 0
Minimal Example:
triggers:
- script
### <hotpink>`stash-pull-request()`</hotpink> 🍓
Trigger builds via Stash/Bitbucket Server Pull Requests.
Requires the Jenkins Stash Pull Request Builder Plugin <https://plugins.jenkins.io/stash-pullrequest-builder>.
- **`cron`** (*str*) — cron syntax of when to run (**required**)
- **`stash-host`** (*str*) — The HTTP or HTTPS URL of the Stash host (**NOT** ssh). e.g.: <https://example.com> (**required**)
- **`credentials-id`** (*str*) — Jenkins credential set to use. (**required**)
- **`project`** (*str*) — Abbreviated project code. e.g.: `PRJ` or `~user` (**required**)
- **`repository`** (*str*) — Stash Repository Name. e.g.: `Repo` (**required**)
- **`ci-skip-phrases`** (*str*) — CI Skip Phrases. (default `'NO TEST'`)
- **`ci-build-phrases`** (*str*) — CI Build Phrases. (default `'test this please'`)
- **`target-branches`** (*str*) — Target branches to filter. (default `''`)
- **`ignore-ssl`** (*bool*) — Ignore SSL certificates for Stash host. (default `false`)
- **`check-destination-commit`** (*bool*) — Rebuild if destination branch changes. (default `false`)
- **`check-mergable`** (*bool*) — Build only if PR is mergeable. (default `false`)
- **`merge-on-success`** (*bool*) — Merge PR if build is successful. (default `false`)
- **`check-not-conflicted`** (*bool*) — Build only if Stash reports no conflicts. (default `false`)
- **`only-build-on-comment`** (*bool*) — Only build when asked (with test phrase). (default `false`)
- **`delete-previous-build-finish-comments`** (*bool*) — Keep PR comment only for most recent Build. (default `false`)
- **`cancel-outdated-jobs`** (*bool*) — Cancel outdated jobs. (default `false`)
Minimal Example:
triggers:
- stash-pull-request: cron: "* * * * *" stash-host: "https://stash-host.com" credentials-id: default-stash-credentials project: stash-project repository: stash-repo
Full Example:
triggers:
- stash-pull-request: cron: "H 1 2 3 4" stash-host: "https://stash-host.com" credentials-id: default-stash-credentials project: stash-project repository: stash-repo ci-skip-phrases: "test skip phrase" ci-build-phrases: "test build phrase" target-branches: "master" ignore-ssl: true check-destination-commit: true check-mergable: true merge-on-success: true check-not-conflicted: false only-build-on-comment: true delete-previous-build-finish-comments: true cancel-outdated-jobs: true
### <purple>`timed()`</purple> ⏰
Trigger builds at certain times.
**Parameter**
when to run the job (cron syntax)
Example:
triggers:
- timed: "@midnight"
---
## <rainbow>Wrappers</rainbow> 🎀🦋
Wrappers can alter the way the build is run as well as the build output.
Component: `wrappers`
**Macro** `wrapper`
**Entry Point** `jenkins_jobs.wrappers`
- **`class wrappers.Wrappers(registry)`**
- **`component_list_type = 'wrappers'`** — 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 = 'wrapper'`** — 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.
`:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure`
- **`sequence = 80`** — The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
### <mint>`android-emulator()`</mint> 🤖
Automates many Android development tasks including SDK installation, build file generation, emulator creation and launch, APK (un)installation...
Requires the Jenkins Android Emulator Plugin <https://plugins.jenkins.io/android-emulator>.
**Parameters**
- **`avd`** (*str*) — Enter the name of an existing Android emulator configuration. If this is exclusive with the `'os'` arg.
- **`os`** (*str*) — Can be an OS version, target name or SDK add-on
- **`screen-density`** (*str*) — Density in dots-per-inch (dpi) or as an alias, e.g. `"160"` or `"mdpi"`. (default `mdpi`)
- **`screen-resolution`** (*str*) — Can be either a named resolution or explicit size, e.g. `"WVGA"` or `"480x800"`. (default `WVGA`)
- **`locale`** (*str*) — Language and country pair. (default `en_US`)
- **`target-abi`** (*str*) — Name of the ABI / system image to be used. (optional)
- **`sd-card`** (*str*) — sd-card size e.g. `"32M"` or `"10240K"`. (optional)
- **`wipe`** (*bool*) — if true, the emulator will have its user data reset at start-up (default `false`)
- **`show-window`** (*bool*) — if true, the Android emulator user interface will be displayed on screen during the build. (default `false`)
- **`snapshot`** (*bool*) — Start emulator from stored state (default `false`)
- **`delete`** (*bool*) — Delete Android emulator at the end of build (default `false`)
- **`startup-delay`** (*int*) — Wait this many seconds before attempting to start the emulator (default `0`)
- **`commandline-options`** (*str*) — Will be given when starting the Android emulator executable (optional)
- **`exe`** (*str*) — The emulator executable. (optional)
- **`hardware-properties`** (*list*) — Dictionary of hardware properties. Allows you to override the default values for an AVD. (optional)
Example:
wrappers:
- android-emulator: os: android-19 target-abi: x86 sd-card: 16MB hardware-properties: hw.accelerometer: 100 wipe: true show-window: true snapshot: true delete: true startup-delay: 10 commandline-options: "-gpu on -no-audio" exe: emulator-arm
### <cyan>`ansicolor()`</cyan> 🌈
Translate ANSI color codes to HTML in the console log.
Requires the Jenkins Ansi Color Plugin <https://plugins.jenkins.io/ansicolor>.
**Parameters**
`colormap` (*str*) — Color mapping to use (default `xterm`)
Minimal Example:
wrappers:
- ansicolor
Full Example:
wrappers:
- ansicolor: colormap: "gnome-terminal"
### <lavender>`artifactory-generic()`</lavender> 🫶
Wrapper for non-Maven projects.
Requires the Jenkins Artifactory Plugin <https://plugins.jenkins.io/artifactory>
**Parameters**
- **`url`** (*str*) — URL of the Artifactory server. e.g. <https://jfrog.com/artifactory/> (default `''`)
- **`name`** (*str*) — Artifactory user with permissions use for connected to the selected Artifactory Server (default `''`)
- **`repo-key`** (*str*) — Release repository name (plugin < 2.3.0) (default `''`)
- **`snapshot-repo-key`** (*str*) — Snapshots repository name (plugin < 2.3.0) (default `''`)
- **`key-from-select`** (*str*) — the repository key to use, and yes bestie this one needs plugin >= 2.3.0 (default is `''`) 🔑
- **`key-from-text`** (*str*) — a repository key you can configure **dynamically** using Jenkins variables (also plugin >= 2.3.0, she's new here) (default `''`)
- **`upload-spec`** (*str*) — File Spec schema for uploading files, goes like this (default `''`)
- **`download-spec`** (*str*) — File Spec schema for downloading files, goes like this (default `''`)
- **`upload-spec-file`** (*str*) — file location for uploading the Spec schema (default `''`)
- **`download-spec-file`** (*str*) — file location for downloading the Spec schema (default `''`)
- **`deploy-pattern`** (*list*) — list of patterns mapping build artifacts to published artifacts. Supports Ant-style wildcards mapping to target directories. E.g.: `/.zip=>dir` (default `[]`) 🗂️
- **`resolve-pattern`** (*list*) — list of references to other artifacts that this build should use as dependencies.
- **`matrix-params`** (*list*) — list of properties to attach to all deployed artifacts, on top of the default ones (`build.name`, `build.number`, and `vcs.revision`) (default `[]`) ✨
- **`deploy-build-info`** (*bool*) — deploy Jenkins build metadata with artifacts to Artifactory (default `false`)
- **`env-vars-include`** (*bool*) — include environment variables accessible by the build process. Jenkins-specific env variables are **always** included. Use the `env-vars-include-patterns` and `env-vars-exclude-patterns` to filter the environment variables published to artifactory. (default `false`) 🌈
- **`env-vars-include-patterns`** (*list*) — list of environment variable patterns for including env vars as part of the published build info. Environment variables may contain the `*` and the `?` wildcards (default `[]`)
- **`env-vars-exclude-patterns`** (*list*) — list of environment variable patterns that determine the env vars **excluded** from the published build info (default `[]`)
- **`discard-old-builds`** (*bool*) — remove older build info from Artifactory (default `false`) 🗑️
- **`discard-build-artifacts`** (*bool*) — remove older build artifacts from Artifactory (default `false`)
### ✨ Example:
wrappers:
- artifactory-generic: url: http://artifactory.example.net/artifactory name: 'test' deploy-build-info: true repo-key: 'release-repo' snapshot-repo-key: 'snapshot-repo' deploy-pattern:
- '*.zip=>results' resolve-pattern:
- 'libs-release-local:prod/*=>prod-jars' matrix-params:
- 'custom_prop=${PROJECT_ENV_VAR}' env-vars-include: true env-vars-include-patterns:
- 'PROJECT_*'
- 'ORG_*' discard-old-builds: true discard-build-artifacts: true
---
## `artifactory-maven()`
Wrapper for non-Maven projects. 💅
Requires the Jenkins Artifactory Plugin <https://plugins.jenkins.io/artifactory>
### Parameters
- **`url`** (*str*) — URL of the Artifactory server. e.g. <https://jfrog.com/artifactory/> (default `''`)
- **`name`** (*str*) — Artifactory user with permissions use for connected to the selected Artifactory Server (default `''`)
- **`repo-key`** (*str*) — name of the repository to search for artifact dependencies. Provide a single `repo-key` **or** provide separate `release-repo-key` and `snapshot-repo-key`.
- **`release-repo-key`** (*str*) — release repository name. Value of `repo-key` take priority over `release-repo-key` if provided.
- **`snapshot-repo-key`** (*str*) — snapshots repository name. Value of `repo-key` take priority over `release-repo-key` if provided.
### ✨ Example:
wrappers:
- artifactory-maven: url: http://artifactory.example.net/artifactory name: 'test' repo-key: repo
---
## `artifactory-maven-freestyle()`
Wrapper for Free Stype projects. 🧚
Requires the Jenkins Artifactory Plugin <https://plugins.jenkins.io/artifactory>
### Parameters
- **`url`** (*str*) — URL of the Artifactory server. e.g. <https://jfrog.com/artifactory/> (default `''`)
- **`name`** (*str*) — Artifactory user with permissions use for connected to the selected Artifactory Server (default `''`)
- **`release-repo-key`** (*str*) — release repository name (default `''`)
- **`snapshot-repo-key`** (*str*) — snapshots repository name (default `''`)
- **`publish-build-info`** (*bool*) — push build metadata with artifacts (default `false`)
- **`discard-old-builds`** (*bool*) — remove older build info from Artifactory (default `true`)
- **`discard-build-artifacts`** (*bool*) — remove older build artifacts from Artifactory (default `false`)
- **`include-env-vars`** (*bool*) — include **all** environment variables accessible by the build process. Jenkins-specific env variables are always included (default `false`)
- **`run-checks`** (*bool*) — run automatic license scanning check after the build is complete (default `false`) 🔍
- **`include-publish-artifacts`** (*bool*) — include the build's published module artifacts in the license violation checks if they are also used as dependencies for other modules in this build (default `false`)
- **`license-auto-discovery`** (*bool*) — tells Artifactory **not** to try and automatically analyze and tag the build's dependencies with license information upon deployment (default `true`)
- **`enable-issue-tracker-integration`** (*bool*) — when the Jenkins JIRA plugin is enabled, synchronize information about JIRA issues to Artifactory and attach issue information to build artifacts (default `false`)
- **`aggregate-build-issues`** (*bool*) — when the Jenkins JIRA plugin is enabled, include all issues from previous builds up to the latest build status defined in "Aggregation Build Status" (default `false`)
- **`filter-excluded-artifacts-from-build`** (*bool*) — add the excluded files to the `excludedArtifacts` list and remove them from the artifacts list in the build info (default `false`)
- **`scopes`** (*str*) — a list of dependency scopes/configurations to run license violation checks on. If left empty all dependencies from all scopes will be checked (default `''`)
- **`violation-recipients`** (*str*) — recipients that need to be notified of license violations in the build info (default `''`) 📧
- **`matrix-params`** (*list*) — list of properties to attach to all deployed artifacts in addition to the default ones: `build.name`, `build.number`, and `vcs.revision` (default `''`)
- **`black-duck-app-name`** (*str*) — the existing Black Duck Code Center application name (default `''`)
- **`black-duck-app-version`** (*str*) — the existing Black Duck Code Center application version (default `''`)
- **`black-duck-report-recipients`** (*str*) — recipients that will be emailed a report after the automatic Black Duck Code Center compliance checks finished (default `''`)
- **`black-duck-scopes`** (*str*) — a list of dependency scopes/configurations to run Black Duck Code Center compliance checks on. If left empty all dependencies from all scopes will be checked (default `''`)
- **`black-duck-run-checks`** (*bool*) — automatic Black Duck Code Center compliance checks will occur after the build completes (default `false`)
- **`black-duck-include-published-artifacts`** (*bool*) — include the build's published module artifacts in the license violation checks if they are also used as dependencies for other modules in this build (default `false`)
- **`auto-create-missing-component-requests`** (*bool*) — auto create missing components in Black Duck Code Center application after the build is completed and deployed in Artifactory (default `true`)
- **`auto-discard-stale-component-requests`** (*bool*) — auto discard stale components in Black Duck Code Center application after the build is completed and deployed in Artifactory (default `true`) 🦆
- **`deploy-artifacts`** (*bool*) — push artifacts to the Artifactory Server. The specific artifacts to push are controlled using the `deployment-include-patterns` and `deployment-exclude-patterns`. (default `true`)
- **`deployment-include-patterns`** (*list*) — list of patterns for including build artifacts to publish to artifactory. (default`[]'`)
- **`deployment-exclude-patterns`** (*list*) — list of patterns for excluding artifacts from deployment to Artifactory (default `[]`)
- **`env-vars-include`** (*bool*) — include environment variables accessible by the build process. Jenkins-specific env variables are always included. Environment variables can be filtered using the `env-vars-include-patterns` nad `env-vars-exclude-patterns`. (default `false`)
- **`env-vars-include-patterns`** (*list*) — the list of env var patterns that *will* get included in the published build info. And yes bestie, these patterns can use the `*` and the `?` wildcards 💫 (default `[]`)
- **`env-vars-exclude-patterns`** (*list*) — the list of env var patterns that get **excluded** from the published build info, no cap 🙅 (default `[]`)
<cyan>Example:</cyan>
wrappers:
- artifactory-maven-freestyle: url: http://artifactory.example.net/artifactory name: 'test' repo-key: repo matrix-params:
- 'custom_prop=${PROJECT_ENV_VAR}' deployment-include-patterns:
- '*.zip=>results' env-vars-include: true env-vars-include-patterns:
- 'PROJECT_*'
- 'ORG_*'
---
## `build-keeper()` 🌸
Keeps builds around based on a specific policy. Like, it's the bouncer at the club but for your build history 💅
Needs the Jenkins Build Keeper Plugin <https://plugins.jenkins.io/build-keeper-plugin>.
<lavender>**Parameters**</lavender>
- **`policy`** (*str*) — the policy you're using to keep builds.
<peach>`policy` values</peach>
- `by-day`
- `keep-since`
- `build-number`
- `keep-first-failed`
- `run-condition`
- **`build-period`** (*int*) — a number argument used to calculate which build to keep, and it depends on the `policy` you picked. (default `0`)
- **`dont-keep-failed`** (*bool*) — flag that says whether or not to keep failed builds. (default `false`)
- **`number-of-fails`** (*int*) — how many consecutive failed builds it takes to mark the first one as kept forever. This one **only** applies to the `keep-first-failed` policy, jsyk. (default `0`)
- **`keep-build`** (*bool*) — the build *will* be kept if there's a problem evaluating the `RunCondition`. (default `false`)
- **`token`** (*str*) — token value for the boolean condition. (default `''`)
- **`build-cause`** (*list*) — the cause of why the build was triggered. (default `USER_CAUSE`)
- **`exclusive-cause`** (*bool*) — the cause has to be the **only** one that triggered this build. (default `False`)
- **`command`** (*str*) — the contents of your shell script. (default `''`)
- **`allowed-nodes`** (*str*) — the node to be executed on. (default `''`)
- **`expression`** (*str*) — the regular expression used to match the label. (default `''`)
- **`label`** (*str*) — the label that's gonna get tested by that regular expression. (default `''`)
- **`arg1`** (*str*) — first string argument for the `strings-match` condition. (default `''`)
- **`arg2`** (*str*) — second string argument for the `strings-match` condition. (default `''`)
- **`ignore-case`** (*bool*) — ignore the case of the strings when matching the two string arguments. (default `False`)
<cyan>Example:</cyan>
wrappers:
- build-keeper: policy: 'by-day' build-period: 10 dont-keep-failed: true
wrappers:
- build-keeper: policy: 'keep-first-failed' number-of-fails: 1
---
## `build-name()` ✨
Sets the name of the build. Giving your build a whole identity fr 🫶
Needs the Jenkins Build Name Setter Plugin <https://plugins.jenkins.io/build-name-setter>.
<lavender>**Parameters**</lavender>
- **`name`** (*str*) — the name for the build. Normally you'd stick a variable from Jenkins in there, and the syntax for that is `${FOO}` for the `FOO` variable. 🎀
- **`description`** (*str*) — build description for the build (Optional).
- **`run-at-start`** (*str*) — set the build name **before** the build starts (Optional, default: `True`).
- **`run-at-end`** (*str*) — set the build name **after** the build ends (Optional, default: `True`).
<cyan>Example:</cyan>
wrappers:
- build-name: name: Build-${FOO} description: lorem ipsum dolor run-at-start: true run-at-end: false
---
## `build-user-vars()` 💜
Sets environment variables to the value of the user who started the build. Main character identification, we love to see it 👑
Needs the Jenkins Build User Vars Plugin <https://plugins.jenkins.io/build-user-vars-plugin>.
<cyan>Example:</cyan>
wrappers:
- build-user-vars
---
## `ci-skip()` 🦋
Skips making a build for certain pushes. All you gotta do is drop `[ci skip]` into your commit's message and Jenkins will get the memo that you don't wanna run a build for the next push. So polite of you to tell it 💖
Needs the Jenkins Ci Skip Plugin <https://plugins.jenkins.io/ci-skip>.
<cyan>Example:</cyan>
wrappers:
- ci-skip
---
## `config-file-provider()` 🍓
Provides config files (think `settings.xml` for maven, etc.) which then get copied into the job's workspace. Snacks for your build, basically.
Needs the Jenkins Config File Provider Plugin <https://plugins.jenkins.io/config-file-provider>.
<lavender>**Parameters**</lavender>
`files` (*list*) —
List of managed config files, and each one is made up of three parameters.
`files`
- **`file-id`** (*str*) — the identifier for the managed config file.
- **`target`** (*str*) — defines where the file should be created. (default `''`)
- **`variable`** (*str*) — defines an environment variable to be used. (default `''`)
- **`replace-tokens`** (*bool*) — replace tokens in the config file. For example, `"password: ${PYPI_JENKINS_PASS}"` will be replaced with the global variable that's configured in Jenkins.
<hotpink>**Full Example:**</hotpink>
wrappers:
- config-file-provider: files:
- file-id: org.jenkinsci.plugins.configfiles.custom.CustomConfig1234
- file-id: org.jenkinsci.plugins.configfiles.custom.CustomConfig5678 target: /foo.txt variable: varName replace-tokens: true
<hotpink>**Minimal Example:**</hotpink>
wrappers:
- config-file-provider: files:
- file-id: org.jenkinsci.plugins.configfiles.custom.CustomConfig1234
---
## `copy-to-slave()` 🌈
Copies files over to the slave **before** the build runs. Pre-gaming the build fr.
Needs the Jenkins Copy To Slave Plugin <https://plugins.jenkins.io/copy-to-slave>.
<lavender>**Parameters**</lavender>
- **`includes`** (*list*) — list of file patterns to copy (optional).
- **`excludes`** (*list*) — list of file patterns to exclude (optional).
- **`flatten`** (*bool*) — flatten the directory structure (default `false`).
- **`relative-to`** (*str*) — the base location of `includes`/`excludes`. It has to be `home` (`$JENKINS_HOME`), `somewhereElse` (`$JENKINS_HOME/copyToSlave`), `userContent` (`$JENKINS_HOME/userContent`) or `workspace` (default `userContent`).
- **`include-ant-excludes`** (*bool*) — exclude ant's default excludes (default `false`).
<hotpink>**Minimal Example:**</hotpink>
wrappers:
- copy-to-slave
<hotpink>**Full Example:**</hotpink>
wrappers:
- copy-to-slave: includes:
- 'file1'
- 'file2*.txt' excludes:
- 'file2bad.txt' flatten: True relative-to: 'somewhereElse' include-ant-excludes: True
---
## `credentials-binding()` 🔐
Binds credentials to environment variables using the credentials binding plugin for jenkins. Your secrets stay secret but your env vars know them 🤫
Needs the Jenkins Credentials Binding Plugin <https://plugins.jenkins.io/credentials-binding> version `1.1` or greater. Don't try it on an older one bestie, it's giving ✨nothing✨.
<lavender>**Parameters**</lavender>
`binding-type` (*list*) —
List of each binding to create. Bindings may be of type `zip-file`, `file`, `username-password`, `text`, `username-password-separated` or `amazon-web-services`. Here's the tea on what each one does: `username-password` sets a variable to the username and password from the credentials, separated by a colon. `username-password-separated` sets one variable to the username and one variable to the password from the credentials. And `amazon-web-services` sets one variable to the access key and one variable to the secret access key. Requires the AWS Credentials Plugin <https://plugins.jenkins.io/aws-credentials>.
<lavender>**Parameters**</lavender>
- **`credential-id`** (*str*) — UUID of the credential being referenced.
- **`variable`** (*str*) — environment variable where the credential will be stored.
- **`username`** (*str*) — environment variable for the username (Required for binding-type `username-password-separated`).
- **`password`** (*str*) — environment variable for the password (Required for binding-type `username-password-separated`).
- **`access-key`** (*str*) — environment variable for the access key (Required for binding-type `amazon-web-services`).
- **`secret-key`** (*str*) — environment variable for the access secret key (Required for binding-type `amazon-web-services`).
- **`key-file-variable`** (*str*) — environment variable to be set to the temporary path of the SSH key file during the build.
- **`username-variable`** (*str*) — environment variable to be set to the username during the build. (optional)
- **`passphrase-variable`** (*str*) — the env var that gets set to the password during the build. <lavender>totally optional bestie</lavender> ✨
- **`keystore-variable`** (*str*) — the env var that gets set to the temporary keystore location during the build. 🗝️
- **`password-variable`** (*str*) — the env var that gets set to the password during the build. 🔐
- **`alias-variable`** (*str*) — the env var that gets set to the keystore alias name of the certificate during the build. 🏷️
---
**Example:**
wrappers:
- credentials-binding:
- zip-file: credential-id: b3e6f337-5d44-4f57-921c-1632d796caa6 variable: CONFIG_ZIP
- file: credential-id: b3e6f337-5d44-4f57-921c-1632d796caab variable: config_file
- username-password: credential-id: b3e6f337-5d44-4f57-921c-1632d796caac variable: config_username_password
- text: credential-id: b3e6f337-5d44-4f57-921c-1632d796caad variable: config_text
- docker-server-creds-binding: credential-id: b3e6f337-5d44-4f57-921c-1632d796caae variable: config_docker_server
- credentials-binding:
- username-password-separated: credential-id: b3e6f337-5d44-4f57-921c-1632d796caag username: myUsername password: myPassword
- credentials-binding:
- amazon-web-services: credential-id: b3e6f337-5d44-4f57-921c-1632d796caaf access-key: AWS_ACCESS_KEY_ID secret-key: AWS_SECRET_ACCESS_KEY
- credentials-binding:
- ssh-user-private-key: credential-id: b3e6f337-5d44-4f57-921c-1632d796caah key-file-variable: KEY_FILE_VARIABLE username-variable: USER_NAME_VARIABLE passphrase-variable: PASSPHRASE_VARIABLE
- credentials-binding:
- cert-multi-binding: credential-id: b3e6f337-5d44-4f57-921c-1632d796caaj keystore-variable: KEYSTORE_VARIABLE password-variable: PASSWORD_VARIABLE alias-variable: ALIAS_VARIABLE
okay that's a WHOLE lot of credentials at once but look at her go 💅
---
## <pink>`custom-tools()`</p>
Needs the Jenkins Custom Tools Plugin <cyan>`https://plugins.jenkins.io/custom-tools-plugin`</cyan>. 🔧
**Parameters**
- **`tools`** (*list*) — list of custom tools to add <lavender>(optional)</lavender>
- **`skip-master-install`** (*bool*) — skips the install in top level matrix job (default `'false'`)
- **`convert-homes-to-upper`** (*bool*) — converts the home env vars to uppercase (default `'false'`)
**Example:**
wrappers:
- custom-tools: tools:
- my_custom_tool skip-master-install: true convert-homes-to-upper: true
---
## <purple>`delivery-pipeline()`</purple>
If it's enabled, the job will create a version based on the template. That version gets set to the environment variable `PIPELINE_VERSION` and also gets set in the downstream jobs. 🚚✨
Needs the Jenkins Delivery Pipeline Plugin <cyan>`https://plugins.jenkins.io/delivery-pipeline-plugin`</cyan>.
**Parameters**
- **`version-template`** (*str*) — template for the generated version, e.g `1.0.${BUILD_NUMBER}` (default `''`)
- **`set-display-name`** (*bool*) — sets the generated version as the display name for the build (default `false`)
**Minimal Example:**
wrappers:
- delivery-pipeline
**Full Example:**
wrappers:
- delivery-pipeline: version-template: 1.0.0-${BUILD_NUMBER} set-display-name: true
---
## <blue>`docker-custom-build-env()`</blue>
Lets you define a build environment for a job using a Docker container. 🐳 iconic behaviour honestly
Needs the Jenkins CloudBees Docker Custom Build Environment Plugin <cyan>`https://plugins.jenkins.io/docker-custom-build-environment`</cyan>.
**Parameters**
- **`image-type`** (*str*) — Docker image type. The valid values and their extra attributes are described in the `image_types` table (scroll down bestie 👇)
- **`docker-tool`** (*str*) — the name of the docker installation to use (default `'Default'`)
- **`host`** (*str*) — URI to the docker host you are using
- **`credentials-id`** (*str*) — argument to specify the ID of credentials to use for docker host <lavender>(optional)</lavender>
- **`registry-credentials-id`** (*str*) — argument to specify the ID of credentials to use for docker registry <lavender>(optional)</lavender>
- **`volumes`** (*list*) — volumes to bind mound from slave host into container
- **volume**
- **`host-path`** (*str*) — path on host
- **`path`** (*str*) — path inside container
- **`verbose`** (*bool*) — logs the docker commands executed by the plugin on the build log (default `false`)
- **`privileged`** (*bool*) — run in privileged mode (default `false`)
- **`force-pull`** (*bool*) — force pull (default `false`)
- **`group`** (*str*) — the user the build runs as has to be the same as the Jenkins slave user, so that files created in the workspace have an adequate owner and permission set
- **`command`** (*str*) — container start command (default `'/bin/cat'`)
- **`net`** (*str*) — network bridge (default `'bridge'`)
- **`memory-limit`** (*str*) — configure the limit memory constraint (default `''`)
- **`cpu-shares`** (*str*) — configure the CPU shares constraint (default `''`)
### <mint>`image_types`</mint> 🌈
the table, but make it a list, because we're not doing tables here
- **`dockerfile`** — build a docker image from a Dockerfile in the project workspace. With this option, the project can define the build environment as a Dockerfile stored in SCM along with the project source code.
- **`context-path`** (*str*) — path to docker context (default `'.'`)
- **`dockerfile`** (*str*) — use an alternate Dockerfile to build the container hosting this build (default `'Dockerfile'`)
- **`pull`** — pull the specified docker image from a Docker repository.
- **`image`** (*str*) — image id/tag
**Example:**
wrappers:
- docker-custom-build-env: image-type: 'pull' image: 'centos:7' force-pull: true privileged: true verbose: true group: jenkins command: /bin/cat net: bridge memory-limit: memory=L<inf, memory-swap=inf cpu-shares: 2
---
## <yellow>`env-file()`</yellow>
Add or override environment variables to the whole build process. 🌸
Needs the Jenkins Environment File Plugin <cyan>`https://plugins.jenkins.io/envfile`</cyan>.
**Parameters**
- **`properties-file`** (*str*) — path to the properties file <lavender>(optional)</lavender>
**Example:**
wrappers:
- env-file: properties-file: ${WORKSPACE}/foo
---
## <hotpink>`env-script()`</hotpink>
Add or override environment variables to the whole build process.
Requires the Jenkins Environment Script Plugin (`https://plugins.jenkins.io/environment-script`).
**Parameters**
- **`script-content`** — the script you're gonna run (default `''`)
- **`script-type`** (str) — what *kind* of script it is, bestie. Here's what's supported:
- `unix-script` (default)
- `power-shell`
- `batch-script`
- **`only-run-on-parent`** — only relevant for Matrix Jobs. Set it `true` and it runs on the matrix parent job and nowhere else (default `false`)
**Example:**
wrappers:
- env-script: script-content: 'echo foo=bar' only-run-on-parent: true
### exclusion()
Slap a resource on there to use for critical sections so you get a mutex. If another job claims the same resource, the second job just sits there waiting for the blocked resource to free up. Patient queen behavior 💅
Requires the Jenkins Exclusion Plugin (`https://plugins.jenkins.io/Exclusion`).
**Parameters**
- **`resources`** (list) — the list of resources you're adding for exclusion
**Example:**
wrappers:
- exclusion: resources:
- myresource1
- myresource2
### github-pull-request()
Sets the GitHub commit status with a custom context and message. Very "let the PR know what's happening" of it.
Requires the Jenkins GitHub Pull Request Builder Plugin (`https://plugins.jenkins.io/ghprb`).
**Parameters**
- **`show-matrix-status`** (bool) — only post the commit status of the parent matrix job (default `false`)
- **`status-context`** (str) — the context to include on PR status comments (default `''`)
- **`triggered-status`** (str) — the status message to set when the build has been triggered (default `''`)
- **`started-status`** (str) — the status message to set when the build has been started (default `''`)
- **`status-url`** (str) — the status URL to set (default `''`)
- **`status-add-test-results`** (bool) — add a test result one-liner to the status message (default `false`)
- **`statuses`** (list) — list of custom statuses on the commit for when a build is completed
- **`message`** (str) — the message that gets appended to a comment when a build finishes with the desired build status. If you don't want *any* status updates when a build finishes with the indicated build status, use `"--none--"` to alert the trigger. (required)
- **`result`** (str) — build result. Can be one of `'SUCCESS'`, `'ERROR'` or `'FAILURE'`. (required)
**Minimal Example:**
wrappers:
- github-pull-request
**Full Example:**
wrappers:
- github-pull-request: show-matrix-status: true status-context: "my-build" triggered-status: "build was triggered" started-status: "build was started" status-url: "http://1.2.3.4" status-add-test-results: true statuses:
- message: "build has succeeded" result: SUCCESS
- message: "build has failed" result: ERROR
### inject()
Adds or overrides environment variables for the *whole* build process. Iconic, honestly.
Requires the Jenkins EnvInject Plugin (`https://plugins.jenkins.io/envinject`).
**Parameters**
- **`properties-file`** (str) — path to the properties file (optional)
- **`properties-content`** (str) — key value pair of properties (optional)
- **`script-file`** (str) — path to the script file (optional)
- **`script-content`** (str) — contents of a script (optional)
- **`load-from-master`** (bool) — load files from master (default `false`)
- **`groovy-script`** (str) — contents of the groovy script (optional)
- **`groovy-sandbox`** (bool) — use groovy sandbox (default `false`)
**Minimal Example:**
wrappers:
- inject
**Full Example:**
wrappers:
- inject: properties-file: example.prop full properties-content: EXAMPLE=foo-bar full script-file: scriptfull.sh script-content: test script content full groovy-script: test groovy-script location full groovy-sandbox: true
### inject-ownership-variables()
Injects ownership variables into the build as environment variables. Consuming info, slay.
Requires the Jenkins EnvInject Plugin (`https://plugins.jenkins.io/envinject`) **and** the Jenkins Ownership plugin (`https://plugins.jenkins.io/ownership`).
**Parameters**
- **`job-variables`** (bool) — inject job ownership variables into the job (default `false`)
- **`node-variables`** (bool) — inject node ownership variables into the job (default `false`)
**Example:**
wrappers:
- inject-ownership-variables: job-variables: true node-variables: true
### inject-passwords()
Injects passwords into the build as environment variables. No cap, they go straight in as env vars.
Requires the Jenkins EnvInject Plugin (`https://plugins.jenkins.io/envinject`).
**Parameters**
- **`global`** (bool) — inject global passwords into the job
- **`mask-password-params`** (bool) — mask password parameters
- **`job-passwords`** (list) — key value pair of job passwords
- **`name`** (str) — name of password
- **`password`** (str) — encrypted password
**Example:**
wrappers:
- inject-passwords: global: true mask-password-params: true job-passwords:
- name: ADMIN password: 0v8ZCNaHwq1hcx+sHwRLdg9424uBh4Pin0zO4sBIb+U=
### jclouds()
Uses JClouds to give you slave launching on most of the currently usable Cloud infrastructures. Look at her go 🦋
Requires the Jenkins JClouds Plugin (`https://plugins.jenkins.io/jclouds-jenkins`).
**Parameters**
- **`single-use`** (bool) — whether or not to terminate the slave after use (default `false`).
- **`instances`** (list) — the name of the jclouds template to create an instance from, plus its parameters.
- **`cloud-name`** (str) — the name of the jclouds profile containing the specified template.
- **`count`** (int) — how many instances to create (default `1`).
- **`stop-on-terminate`** (bool) — whether or not to suspend instead of terminate the instance (default `false`).
**Example:**
wrappers:
- jclouds: single-use: True instances:
- jenkins-dev-slave: cloud-name: mycloud1 count: 1 stop-on-terminate: True
- jenkins-test-slave: cloud-name: mycloud2 count: 2 stop-on-terminate: False
### job-log-logger()
Turns on writing the job log to the underlying logging system. Genuinely so useful.
Requires the Jenkins Job Log Logger plugin (`https://plugins.jenkins.io/job-log-logger-plugin`).
**Parameters**
- **`suppress-empty`** (bool) — suppress empty log messages (default `true`)
**Example:**
wrappers:
- job-log-logger: suppress-empty: false
### live-screenshot()
Shows live screenshots of running jobs right there in the job list. Obsessed.
Requires the Jenkins Live-Screenshot Plugin (`https://plugins.jenkins.io/livescreenshot`).
**Parameters**
- **`full-size`** (str) — name of screenshot file (default `'screenshot.png'`)
- **`thumbnail`** (str) — name of thumbnail file (default `'screenshot-thumb.png'`)
> File type must be `.png` and they must be located inside the `$WORKDIR`.
**Full Example:**
wrappers:
- live-screenshot: full-size: my_screenshot.png thumbnail: my_screenshot-thumb.png
**Minimal Example:**
wrappers:
- live-screenshot
### locks()
Controls parallel execution of jobs. Mutex but make it Jenkins.
Requires the Jenkins Locks and Latches Plugin (`https://github.com/jenkinsci/locks-and-latches-plugin`).
**Arg** — list of locks to use
**Example:**
wrappers:
- locks:
- FOO
- FOO2
### logfilesize()
Aborts the build if its logfile gets too big. It's giving "we have limits."
Requires the Jenkins Logfilesizechecker Plugin (`https://plugins.jenkins.io/logfilesizechecker`).
**Parameters**
- **`set-own`** (bool) — use a job-specific maximum log size instead of the global config value (default `false`).
- **`fail`** (bool) — make builds aborted by this wrapper be marked as `"failed"` (default `false`).
- **`size`** (int) — abort the build if the logfile size is bigger than this value (in MiB, default `128`). Only applies if `set-own` is `true`.
**Full Example:**
wrappers:
- logfilesize: set-own: true size: 1024 fail: true
**Minimal Example:**
wrappers:
- logfilesize
### logstash build wrapper()
Dumps the Jenkins console output straight to Logstash. Bye console, hello Logstash 💜
Requires the Jenkins logstash plugin (`https://plugins.jenkins.io/logstash`).
**Parameters**
- **`use-redis`** — Boolean, tells the thing whether to use Redis or not. (default `true`) 💅
- **`redis`** — the Redis config params, bestie, here's the whole lil menu:
Parameter
- **`host`** (*str*) — Redis hostname (default `'localhost'`) 🏠
Parameter
- **`port`** (*int*) — Redis port number (default `6397`) 🔌
Parameter
- **`database-number`** (*int*) — Redis database number (default `0`)
Parameter
- **`database-password`** (*str*) — Redis database password (default `''`)
Parameter
- **`data-type`** (*str*) — Redis database type (default `'list'`)
Parameter
- **`key`** (*str*) — Redis key (default `'logstash'`) 🔑
### Example:
wrappers:
- logstash: use-redis: True redis: host: 'localhost' port: 6379 database-number: 0 database-password: 'password' data-type: 'list' key: 'logstash'
## ✨ `m2-repository-cleanup()` ✨
Configure M2 Repository Cleanup, periodt.
Needs the Jenkins M2 Repository Cleanup plugin — <https://plugins.jenkins.io/maven-repo-cleaner>. 🧹
**Parameters**
- `patterns` (*list*) — List of patterns for artifacts to cleanup before building. (optional)
This plugin lets you set up a maven2 job so it cleans some or all of the artifacts out of the repository before it runs. Obsessed, honestly.
### Example:
wrappers:
- m2-repository-cleanup: patterns:
- com/ibm/**
- com/microsoft/**
## 🙈 `mask-passwords()` 🙈
Hide passwords in the console log. no cap, they stay hidden.
Needs the Jenkins Mask Passwords Plugin — <https://plugins.jenkins.io/mask-passwords>.
### Example:
wrappers:
- mask-passwords
## 🦋 `matrix-tie-parent()` 🦋
Tie parent to a node.
Needs the Jenkins Matrix Tie Parent Plugin — <https://plugins.jenkins.io/matrixtieparent>.
> Heads up bestie: from Jenkins version `1.532` this plugin's functionality is available under the "advanced" option of the matrix project configuration. You can use the top level `node` parameter to control where the parent job is tied in Jenkins `1.532` and higher. 👑
**Parameters**
`node` (*str*) — Name of the node (required)
### Example:
project-type: matrix wrappers:
- matrix-tie-parent: node: Unix
## 💜 `maven-release()` 💜
Wrapper for Maven projects.
Needs the Jenkins M2 Release Plugin — <https://plugins.jenkins.io/m2release>.
**Parameters**
- **`release-goals`** (*str*) — Release goals and options (default `''`)
- **`dry-run-goals`** (*str*) — DryRun goals and options (default `''`)
- **`num-successful-builds`** (*int*) — Number of successful release builds to keep (default `1`)
- **`select-custom-scm-comment-prefix`** (*bool*) — Preselect 'Specify custom SCM comment prefix' (default `false`)
- **`select-append-jenkins-username`** (*bool*) — Preselect 'Append Jenkins Username' (default `false`)
- **`select-scm-credentials`** (*bool*) — Preselect 'Specify SCM login/password' (default `false`)
- **`release-env-var`** (*str*) — Release environment variable (default `''`)
- **`scm-user-env-var`** (*str*) — SCM username environment variable (default `''`)
- **`scm-password-env-var`** (*str*) — SCM password environment variable (default `''`)
### Example:
wrappers:
- maven-release: release-goals: -Dresume=false release:prepare release:perform dry-run-goals: -Dresume=false -DdryRun=true release:prepare num-successful-builds: 1 select-custom-scm-comment-prefix: false select-append-jenkins-username: false select-scm-credentials: false release-env-var: IS_M2RELEASEBUILD scm-user-env-var: SCM_USER
## 🍓 `mongo-db build wrapper()` 🍓
Initializes a MongoDB database while running the build. so cute, so useful.
Needs the Jenkins MongoDB plugin — <https://plugins.jenkins.io/mongodb>.
**Parameters**
- **`name`** (*str*) — The name of the MongoDB install to use (required)
- **`data-directory`** (*str*) — Data directory for the server (default `''`)
- **`port`** (*int*) — Port for the server (default `''`)
- **`startup-params`** (*str*) — Startup parameters for the server (default `''`)
- **`start-timeout`** (*int*) — How long to wait for the server to start in milliseconds. `0` means no timeout. (default `0`) ⏳
### Full Example:
wrappers:
- mongo-db: name: 2.4.6 data-directory: /var/tmp/mongo port: 5555 startup-params: "--bind_ip 127.0.0.1" start-timeout: 5000
### Minimal Example:
wrappers:
- mongo-db: name: 2.4.6
## 🧚 `nodejs-installator()` 🧚
Provides Jenkins integration for NodeJS & npm packages. slay.
Needs the Jenkins NodeJS Plugin — <https://plugins.jenkins.io/nodejs>.
**Parameters**
`name` (*str*) — nodejs installation name (required)
### Example:
wrappers:
- nodejs-installator: name: "latest node"
## 🔥 `openstack()` 🔥
Provision slaves from OpenStack on demand. main character cloud energy.
Needs the Jenkins Openstack Cloud Plugin — <https://plugins.jenkins.io/openstack-cloud>.
**Parameters**
- **`instances`** (*list*) —
List of instances to be launched at the beginning of the build.
instances
- **`cloud-name`** (*str*) — The name of the cloud profile which contains the specified cloud instance template (required).
- **`template-name`** (*str*) — The name of the cloud instance template to create an instance from(required).
- **`manual-template`** (*bool*) — If `True`, instance template name will be put in 'Specify Template Name as String' option. Not specifying or specifying `False`, instance template name will be put in 'Select Template from List' option. To use parameter replacement, set this to `True`. (default `false`)
- **`count`** (*int*) — How many instances to create (default `1`).
- **`single-use`** (*bool*) — Whether or not to terminate the slave after use (default `false`).
### Example:
wrappers:
- openstack: instances:
- cloud-name: mycloud1 template-name: jenkins-dev-slave count: 1
- cloud-name: mycloud2 template-name: jenkins-test-slave manual-template: True count: 2 single-use: True
## 👑 `pathignore()` 👑
This plugin allows SCM-triggered jobs to ignore build requests if only certain paths have changed. literally the "not my problem" of build triggers.
Needs the Jenkins Pathignore Plugin — <https://plugins.jenkins.io/pathignore>.
**Parameters**
`ignored` (*str*) — A set of patterns to define ignored changes
### Example:
wrappers:
- pathignore: ignored: "docs, tests"
## 🌈 `port-allocator()` 🌈
Assign unique TCP port numbers. no two jobs fighting over the same port, we love to see it.
Needs the Jenkins Port Allocator Plugin — <https://plugins.jenkins.io/port-allocator>.
**Parameters**
- **`name`** (*str*) — Deprecated, use `names` instead
- **`names`** (*list*) — Variable list of names of the port or list of specific port numbers
> bestie, `name` is **deprecated** — use `names`, okay? don't make me say it twice 💅
### Example:
wrappers:
- port-allocator: names:
- SERVER_PORT
- SERVER_PORT2
## ⭐ `pre-scm-buildstep()` ⭐
Execute a Build Step before running the SCM. yes, *before*. we're going in early.
Needs the Jenkins Pre SCM BuildStep — <https://plugins.jenkins.io/preSCMbuildstep>.
**Parameters**
- **`failOnError`** (*str*) — Specifies if the job should fail on error (plugin >= 0.3) (default `false`).
- **`buildsteps`** (*list*) —
List of build steps to execute
Buildstep
Any acceptable builder, as seen in the example
### Example:
wrappers:
- pre-scm-buildstep: failOnError: true buildsteps:
- shell: | #!/bin/bash echo "Doing something cool"
- shell: | #!/bin/zsh echo "Doing something cool with zsh"
- ant: "target1 target2" ant-name: "Standard Ant"
- inject: properties-file: example.prop properties-content: EXAMPLE=foo-bar
## 🎀 `rbenv()` 🎀
Set the rbenv implementation.
Needs the Jenkins rbenv plugin — <https://plugins.jenkins.io/rbenv>.
All parameters are optional, so no pressure bestie. 🫶
**Parameters**
- **`ruby-version`** (*str*) — Version of Ruby to use (default `1.9.3-p484`)
- **`ignore-local-version`** (*bool*) — If true, ignore local Ruby version (defined in the ".ruby-version" file in workspace) even if it has been defined (default `false`)
- **`preinstall-gem-list`** (*str*) — the gems you want installed up front (default `'bundler,rake'`)
- **`rbenv-root`** (*str*) — `RBENV_ROOT` (default `$HOME/.rbenv`)
- **`rbenv-repo`** (*str*) — which repo we're cloning rbenv from (default `https://github.com/rbenv/rbenv`)
- **`rbenv-branch`** (*str*) — which branch of rbenv we're cloning (default `master`)
- **`ruby-build-repo`** (*str*) — which repo we're cloning ruby-build from (default `https://github.com/rbenv/ruby-build`)
- **`ruby-build-branch`** (*str*) — which branch of ruby-build we're cloning (default `master`)
**Example:**
wrappers:
- rbenv: ruby-version: 2.0.0-p353 ignore-local-version: false preinstall-gem-list: "bundler,rake" rbenv-root: "$HOME/.rbenv" rbenv-repo: "https://github.com/sstephenson/rbenv.git" rbenv-branch: "master" ruby-build-repo: "https://github.com/sstephenson/ruby-build.git" ruby-build-branch: "master"
---
### <pink>`release()`</p> 💜
Bestie this one drops in release build config for you. So slay.
Needs the Jenkins Release Plugin <https://plugins.jenkins.io/release> — no plugin, no party, fr fr.
**Parameters** 🎀
- **`keep-forever`** (*bool*) — keep the build forever (default `true`)
- **`override-build-parameters`** (*bool*) — turn on build-parameter override (default `false`)
- **`version-template`** (*str*) — release version template (default `''`)
- **`parameters`** (*list*) — release parameters (peep the Parameters <#parameters> module)
- **`pre-build`** (*list*) — pre-build steps (peep the Builders <#builders> module)
- **`post-build`** (*list*) — post-build steps (peep Builders <#builders>)
- **`post-success`** (*list*) — steps for after a successful build (peep Builders <#builders>)
- **`post-failed`** (*list*) — steps for after a failed build (peep Builders <#builders>)
**Example:**
wrappers:
- release: keep-forever: false parameters:
- string: name: RELEASE_BRANCH default: '' description: Git branch to release from.
- bool: name: FOO default: false description: "A parameter named FOO, defaults to 'false'." post-success:
- shell: | #!/bin/bash copy_build_artefacts.sh
---
### <purple>`rvm-env()`</purple> 🌸
Sets the RVM implementation. Yes queen.
Needs the Jenkins Rvm Plugin <https://plugins.jenkins.io/rvm> — it's giving dependency, iykyk.
**Parameters** ✨
- **`implementation`** (*str*) — type of implementation. The syntax is `RUBY[@GEMSET]`, like `'1.9.3'` or `'jruby@foo'`.
**Example:**
wrappers:
- rvm-env: implementation: 1.9.3
---
### <hotpink>`sauce-ondemand()`</hotpink> 🔥
Lets you hook Sauce OnDemand up with Jenkins — you can automate the setup *and* the tear down of Sauce Connect, plus pull in those Sauce OnDemand result videos per test. Iconic behaviour honestly.
Needs the Jenkins Sauce OnDemand Plugin <https://plugins.jenkins.io/sauce-ondemand>.
**Parameters** 💅
- **`enable-sauce-connect`** (*bool*) — launches a SSH tunnel from their cloud to your private network (default `false`)
- **`sauce-host`** (*str*) — the name of the selenium host to use. For tests run using Sauce Connect this should be `localhost`. `ondemand.saucelabs.com` can also be used to connect directly to Sauce OnDemand. The value of the host gets stored in the `SAUCE_ONDEMAND_HOST` environment variable. (default `''`)
- **`sauce-port`** (*str*) — the name of the Selenium Port to use. For tests run using Sauce Connect this should be `4445`. If you're using `ondemand.saucelabs.com` for the Selenium Host, then use `4444`. The value of the port gets stored in the `SAUCE_ONDEMAND_PORT` environment variable. (default `''`)
- **`override-username`** (*str*) — if this is set then `api-access-key` must be set too. Overrides the username from the global config. (default `''`)
- **`override-api-access-key`** (*str*) — if this is set then `username` must be set too. Overrides the `api-access-key` set in the global config. (default `''`)
- **`starting-url`** (*str*) — whatever you set here gets stored in the `SELENIUM_STARTING_ULR` environment variable. Only used when type is `selenium`. (default `''`)
- **`type`** (*str*) — the type of test to run (default `selenium`)
- type values
- `selenium`
- `webdriver`
- **`platforms`** (*list*) — the platforms to run the tests on. Supported platforms get pulled dynamically from sauce labs. The value format has *only* the first letter capitalized, no spaces, an underscore between os and version, an underscore in `internet_explorer`, and everything else run together. If there aren't multiple versions of the browser, then just the first version number is used. Examples: `Mac_10.8iphone5.1` or `Windows_2003firefox10` or `Windows_2012internet_explorer10` (default `''`)
- **`launch-sauce-connect-on-slave`** (*bool*) — whether to launch sauce connect on the slave. (default `false`)
- **`https-protocol`** (*str*) — the https protocol to use (default `''`)
- **`sauce-connect-options`** (*str*) — options to pass to sauce connect (default `''`)
**Example:**
wrappers:
- sauce-ondemand: enable-sauce-connect: true sauce-host: foo sauce-port: 8080 override-username: foo override-api-access-key: 123lkj123kh123l;k12323 type: webdriver platforms:
- Linuxandroid4
- Linuxfirefox10
- Linuxfirefox11 launch-sauce-connect-on-slave: true
---
### <cyan>`sonar()`</cyan> 🦋
A lil wrapper for the SonarQube Plugin. So chill.
Needs the SonarQube plugin <https://plugins.jenkins.io/sonar> 💖
**Parameters** 🌈
- **`install-name`** (*str*) — release goals and options (default `''`)
**Minimal Example:**
wrappers:
- sonar
**Full Example:**
wrappers:
- sonar: install-name: test-sonar-installation
---
### <mint>`ssh-agent-credentials()`</mint> 🫶
Sets up the user for the ssh agent plugin for jenkins. Get that ssh sorted, bestie.
Needs the Jenkins SSH-Agent Plugin <https://plugins.jenkins.io/ssh-agent>.
**Parameters** ⭐
- **`users`** (*list*) — a list of Jenkins users credential IDs (**required**)
- **`user`** (*str*) — the user id of the jenkins user credentials (deprecated 👀)
- **`ignore-missing-credentials`** (*bool*) — specifies the option to ignore missing credentials (default `false`)
**Example:**
wrappers:
- ssh-agent-credentials: users:
- '44747833-247a-407a-a98f-a5a2d785111c'
- 'f1c0f777-7ac6-43fd-b5c7-68b420aa1392'
- 'dd647a01-be21-402b-bfc5-a4e89be7d0c4'
> okay so important note: if **both** `users` and `user` parameters are specified, `users` gets preferred and `user` gets ignored. periodt.
**Example:**
wrappers:
- ssh-agent-credentials: user: '49d20745-9889-4c02-b286-fc6fb89c36bd' users:
- '44747833-247a-407a-a98f-a5a2d785111c'
- 'dd647a01-be21-402b-bfc5-a4e89be7d0c4'
**Example:**
wrappers:
- ssh-agent-credentials: users:
- '49d20745-9889-4c02-b286-fc6fb89c36bd'
equals to:
wrappers:
- ssh-agent-credentials: user: '49d20745-9889-4c02-b286-fc6fb89c36bd'
---
### <red>`timeout()`</red> ⏰
Aborts the build if it runs too long. Like, girl, wrap it up. 😭
Needs the Jenkins Build Timeout Plugin <https://plugins.jenkins.io/build-timeout>.
**Parameters** 💀
- **`fail`** (*bool*) — mark the build as failed (default `false`)
- **`abort`** (*bool*) — mark the build as aborted (default `false`)
- **`abort-and-restart`** (*bool*) — mark the build as aborted, then restart. The count of restarts can be set via `max-restarts` (default `false`) (Version >= 1.17).
- **`write-description`** (*bool*) — write a message in the description (default `false`)
- **`max-restarts`** (*int*) — count of maximum restarts. `0` means without a limit (default `0`) (Version >= 1.17).
- **`timeout`** (*int*) — abort the build after this number of minutes (default `3`)
- **`timeout-var`** (*str*) — export an environment variable to reference the timeout value (optional)
- **`type`** (*str*) — timeout type to use (default `absolute`)
- **`elastic-percentage`** (*int*) — percentage of the three most recent builds where to declare a timeout, only applies to `elastic` type. (default `0`)
- **`elastic-number-builds`** (*int*) — number of builds to consider when computing average duration, only applies to `elastic` type. (default `3`)
- **`elastic-default-timeout`** (*int*) — timeout to use if there were no previous builds, only applies to `elastic` type. (default `3`)
- **`deadline-time`** (*str*) — build terminates automatically at next deadline time (`HH:MM:SS`), only applies to `deadline` type. (default `0:00:00`)
- **`deadline-tolerance`** (*int*) — how many minutes after the deadline a job gets before it's immediately aborted. Only does anything for the `deadline` type, bestie. (default `1`)
---
### Example (Version < 1.14):
wrappers:
- timeout: timeout: 90 timeout-var: 'BUILD_TIMEOUT' fail: true type: absolute
wrappers:
- timeout: fail: false type: likely-stuck
wrappers:
- timeout: timeout-var: 'BUILD_TIMEOUT' fail: true elastic-percentage: 150 elastic-default-timeout: 90 type: elastic
### Example (Version >= 1.14):
wrappers:
- timeout: timeout: 90 timeout-var: 'BUILD_TIMEOUT' fail: true type: absolute
wrappers:
- timeout: timeout: 5 timeout-var: 'BUILD_TIMEOUT' type: no-activity abort: true write-description: "Blah Blah Blah"
wrappers:
- timeout: timeout: 90 timeout-var: 'BUILD_TIMEOUT' abort: true type: likely-stuck
wrappers:
- timeout: elastic-percentage: 150 elastic-default-timeout: 3 elastic-number-builds: 14 timeout-var: 'BUILD_TIMEOUT' abort: true type: elastic
wrappers:
- timeout: deadline-time: '0:00:00' deadline-tolerance: 1 timeout-var: 'BUILD_TIMEOUT' type: deadline
---
### `timestamps()`
<rainbow>Adds timestamps to the console log!!!</rainbow> ⏰✨ Like every single line gets a lil timestamp so you can see exactly when things went down. Lowkey the glow-up your build log needed.
Needs the Jenkins Timestamper Plugin — <cyan>`https://plugins.jenkins.io/timestamper`</cyan>.
**Example:**
wrappers:
- timestamps
---
### `vault-secrets()`
Injects environment variables straight out of a HashiCorp Vault secret. 🔐💖
The secrets are generally masked in the build log, so like, your stuff stays your stuff. 🫶
Needs the Jenkins HashiCorp Vault Plugin — <cyan>`https://plugins.jenkins.io/hashicorp-vault-plugin`</cyan>.
**Parameters**
- **`vault-url`** (*str*) — the Vault URL
- **`credentials-id`** (*str*) — the Vault Credential
- **`engine-version`** (*str*) — the Vault K/V Engine version
- **`fail-if-not-found`** (*bool*) — fail if the secret path isn't found
- **`skip-ssl-verification`** (*bool*) — skip verifying the SSL certs
- **`secrets`** (*list*) —
List of secrets
**secrets**
- **`secret-path`** (*str*) — the path of the secret in the vault server
- **`engine-version`** (*str*) — the Vault K/V Engine version
**secret-values**
- **`secret-values`** (*list*) — list of key / value pairs
- **`env-var`** (*str*) — the environment variable to set with the value of the vault key
- **`vault-key`** (*str*) — the vault key whose value populates that environment variable
**Minimal Example:**
wrappers:
- vault-secrets: vault-url: 'http://127.0.0.1:8200' credentials-id: 'myCredentials' secrets:
- secret-path: 'secret/my-token' secret-values:
- env-var: 'TOKEN' vault-key: 'token'
- secret-path: 'secret/my-token' secret-values:
**Full Example:**
wrappers:
- vault-secrets: vault-url: 'http://127.0.0.1:8200' credentials-id: 'myCredentials' fail-if-not-found: 'false' skip-ssl-verification: 'true' engine-version: '2' secrets:
- secret-path: 'secret/my-secret' secret-values:
- env-var: 'USERNAME' vault-key: 'username'
- env-var: 'PASSWORD' vault-key: 'password'
- secret-path: 'secret/my-secret2' engine-version: '2' secret-values:
- env-var: 'USERNAME2' vault-key: 'username2'
- env-var: 'PASSWORD2' vault-key: 'password2'
- secret-path: 'secret/my-secret' secret-values:
---
### `version-number()`
Generates a version number for the build using a format string. 📛✨ The wiki page has way more detailed descriptions of the options if you wanna go deeper, iykyk.
Needs the Jenkins Version number plugin — <cyan>`https://plugins.jenkins.io/versionnumber`</cyan>.
**Parameters**
- **`variable-name`** (*str*) — name of the environment variable to assign the version number to (**required**)
- **`format-string`** (*str*) — the format string used to generate the version number (**required**)
- **`prefix-variable`** (*str*) — variable that contains the version number prefix (optional)
- **`skip-failed-builds`** (*bool*) — if the build fails, <red>DO NOT</red> increment any auto-incrementing component of the version number (default: `false`)
- **`display-name`** (*bool*) — use the version number for the build display name (default: `false`)
- **`start-date`** (*str*) — the date the project began, as a UTC timestamp (default `1970-1-1 00:00:00.0 UTC`)
- **`builds-today`** (*int*) — the number of builds that have been executed today (optional)
- **`builds-this-month`** (*int*) — the number of builds that have been executed since the start of the month (optional)
- **`builds-this-year`** (*int*) — the number of builds that have been executed since the start of the year (optional)
- **`builds-all-time`** (*int*) — the number of builds that have been executed since the start of the project (optional)
**Example:**
wrappers:
- version-number: variable-name: relVersion prefix-variable: relVersion format-string: ${BUILD_DATE_FORMATTED, "yy.M"}.${BUILDS_THIS_MONTH_Z}
---
### `workspace-cleanup (pre-build)()`
Needs the Jenkins Workspace Cleanup Plugin — <cyan>`https://plugins.jenkins.io/ws-cleanup`</cyan>. 🧹✨
Heads up bestie: the *post-build* `workspace-cleanup` is available as a publisher.
**Parameters**
- **`include`** (*list*) — list of files to be included
- **`exclude`** (*list*) — list of files to be excluded
- **`dirmatch`** (*bool*) — apply the pattern to directories too (default `false`)
- **`check-parameter`** (*str*) — boolean environment variable to check to determine whether to actually clean up
- **`external-deletion-command`** (*str*) — external deletion command to run against files and directories
- **`disable-deferred-wipeout`** (*bool*) — disable the improved deferred wipeout method (default `false`)
**Full Example:**
wrappers:
- workspace-cleanup: include:
- "_generated.py" exclude:
- "*.py" dirmatch: true check-parameter: "DO_WS_CLEANUP" external-deletion-command: "shred -u %s" disable-deferred-wipeout: true
**Minimal Example:**
wrappers:
- workspace-cleanup
---
### `xvfb()`
Enables xvfb during the build. 🖥️💅
Needs the Jenkins Xvfb Plugin — <cyan>`https://plugins.jenkins.io/xvfb`</cyan>.
**Parameters**
- **`installation-name`** (*str*) — the name of the Xvfb tool installation (default `'default'`)
- **`auto-display-name`** (*bool*) — uses the `-displayfd` option of Xvfb, by which it chooses its own display name (default `false`)
- **`display-name`** (*str*) — ordinal of the display Xvfb will be running on; if it's left empty it's chosen based on the current build executor number (default `''`)
- **`assigned-labels`** (*str*) — if you want to start Xvfb only on specific nodes, specify its name or label (default `''`)
- **`parallel-build`** (*bool*) — when running multiple Jenkins nodes on the same machine, this setting influences the display number generation (default `false`)
- **`timeout`** (*int*) — a timeout of given seconds to wait before returning control to the job (default `0`)
- **`screen`** (*str*) — resolution and color depth. (default `'1024x768x24'`)
- **`display-name-offset`** (*int*) — offset for display names. (default `1`)
- **`additional-options`** (*str*) — additional options to be added, with the options above, to the Xvfb command line (default `''`)
- **`debug`** (*bool*) — if Xvfb output should appear in the console log of this job (default `false`)
- **`shutdown-with-build`** (*bool*) — should the display be kept until the whole job ends (default `false`)
**Full Example:**
wrappers:
- xvfb: installation-name: default auto-display-name: false display-name: 123 assigned-labels: nodes-xxx parallel-build: false timeout: 10 screen: 1024x768x16 display-name-offset: 100 additional-options: -fbdir /tmp debug: true shutdown-with-build: false
**Minimal Example:**
wrappers:
- xvfb
### 🌈 `xvnc()`
Enable **xvnc** during the build, bestie 💖
This one needs the Jenkins xvnc plugin, fr fr: `https://plugins.jenkins.io/xvnc`
#### Parameters
- **`screenshot`** (*bool*) — take a screenshot when the build finishes up (default `false`)
- **`xauthority`** (*bool*) — make a dedicated Xauthority file for every single build, no sharing (default `true`) ✨
#### Full Example:
wrappers:
- xvnc: screenshot: true xauthority: false
#### Minimal Example:
wrappers:
- xvnc
---
## 🌸 Zuul 🌸
The Zuul module adds jobs parameters so you can manually run a build, like, exactly the way Zuul would have 🙈 It's entirely optional, and heads up: Zuul 2.0+ pass the parameters over Gearman.
### 💜 `class zuul.Zuul(registry)`
- **`amend_job_dict(job)`** — this method gets called **before any XML is generated**. By overriding it, a module may arbitrarily modify a job data structure, which will probably be the JJB Job intermediate data dict representation. If it has changed the data structure *at all*, it **must** return `True`; otherwise it **must** return `False`. no pressure or anything 💅
- **Parameters:** `job` (*dict*) — the intermediate representation of job data loaded from JJB Yaml files after variables interpolation and other yaml expansions.
- **Return type:** `bool`
- **`sequence = 0`** — the sequence number for the module 👑 Modules are invoked in the order of their sequence number, so that the XML output comes out consistently ordered.
### 🦋 `zuul()`
Configure this job to be triggered by Zuul ⭐
Adds parameters describing the change that's triggering the build — stuff like the branch name, change number and patchset. it's giving very detailed ✨
See parameters expected by Zuul: `https://opendev.org/zuul/zuul/src/tag/2.6.0/doc/source/launchers.rst#user-content-zuul-parameters`
**Example:**
triggers:
- zuul
### 🦋 `zuul-post()`
Configure this **post-merge** job to be triggered by Zuul 🌈
Adds parameters describing the reference update that triggers the build — that's the previous and next revisions in full (**40 hexadecimal sha1**) and in short form. obsessed with the precision, honestly 🎀
See parameters expected by Zuul: `https://opendev.org/zuul/zuul/src/tag/2.6.0/doc/source/launchers.rst#user-content-zuul-parameters`
**Example:**
triggers:
- zuul-post
---
## ✨ Module Execution ✨
The jenkins job builder modules are executed **in sequence**, periodt.
Generally the sequence is:
1. parameters/properties
2. scm
3. triggers
4. wrappers
5. prebuilders (**maven only**, configured like **Builders** — `#builders`)
6. builders (**maven**, **freestyle**, **matrix**, etc..) 🔥
7. postbuilders (**maven only**, configured like **Builders** — `#builders`)
8. publishers/reporters/notifications 💖
# 🔧 EXTENDING 🔧
okay bestie so Jenkins Job Builder is <pink>super modular</pink>, like it was literally built to be extended 💖. You can add new attributes to components you already have, drop in a whole new module to support some Jenkins plugin, or even bring your own locally defined methods to wrangle an idiosyncratic build system. It's giving ✨flexibility✨.
## The Builder
The <purple>`Builder`</purple> class is the one holding down the Jenkins jobs. She's the main character responsible for <mint>creating</mint> / <red>deleting</red> / <yellow>updating</yellow> jobs, and you can just call her from your own application. Hand her either a filename or an open file-like object that represents your YAML config and she's ready. For the deets, go peek at the `jenkins_jobs/builder.py` file 🫶.
## XML Processing
So most of the actual work of turning your YAML config into XML? Handled by individual functions, each one implementing a <italic>single</italic> characteristic. For example, look at the `jenkins_jobs/modules/builders.py` file — that's the Python module implementing the standard Jenkins builders 💅. The `shell` function right at the top of that file implements the standard Execute a shell build step. And every single YAML-to-XML function in Jenkins Job Builder has the exact same signature:
component(xml_parent, data) :arg class:xml.etree.ElementTree xml_parent: this attribute's parent XML element :arg dict data: the YAML data structure for this attribute and below
The function is expected to look over that YAML data structure, create new XML nodes, and attach them to the `xml_parent` element. This whole pattern gets applied throughout all the included modules, no cap 🌈.
## Modules
Nearly <hotpink>all</hotpink> of Jenkins Job Builder is implemented in modules. The main program literally has no concept of builders, publishers, properties, or any other aspect of job definition — none of it. Each of those building blocks is defined in a module, and because of setuptools entry points, most modules can be easily extended with new components bestie 💜.
To add a new module, you define a class that inherits from `jenkins_jobs.modules.base.Base`, and then add it to the `jenkins_jobs.modules` entry point in your `setup.py`.
**`class jenkins_jobs.modules.base.Base(registry)`** — the base class for a Jenkins Job Builder Module 👑
The module gets initialized <italic>before</italic> any YAML is parsed.
**Parameters**
- `registry` (`ModuleRegistry <#jenkins_jobs.registry.ModuleRegistry>`) — the global module registry.
**`amend_job_dict(job)`** — this method is called before any XML is generated ✨. By overriding it, a module may arbitrarily modify a job data structure, which will probably be the JJB Job intermediate data dict representation. If it has changed the data structure at all, it **must return `True`**, otherwise it **must return `False`**.
**Parameters**
- `job` (`dict`) — the intermediate representation of job data loaded from JJB Yaml files after variables interpolation and other yaml expansions.
**Return type**
- `bool`
**`component_list_type = None`** — this component list type gets used to look up possible implementations of the component type via entry points (entry points give you a *list* of components, so it should be <italic>plural</italic>, iykyk). Set <pink>both</pink> `component_type` and `component_list_type` to `None` if the module doesn't have components.
**`component_type = None`** — the component type for components of this module. This is what gets used to look for macros (macros are defined <italic>singularly</italic>, so it should <bold>not</bold> be plural). Set <pink>both</pink> `component_type` and `component_list_type` to `None` if the module doesn't have components.
**`dispatch_component_list(component_type, component_list, xml_parent, job_data=None)`**
**`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`. <red>⚠️ The YAML data structure must not be modified.</red>
:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure
**`sequence = 10`** — the sequence number for the module. Modules get invoked in the order of their sequence number so that the XML output comes out consistently ordered, periodt ✨.
## Components
Most of the standard modules supply a bunch of components, and it's <mint>easy</mint> to provide your own for those modules to use. For instance, the Builders module provides several builders — like the `shell` builder and the `trigger_builds` builder 🛠️. So if you wanted to add a new builder, literally all you gotta 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). Slay.
## Module Registry
All modules and their associated components get registered in the module registry 👑. You can access it 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, component_pos=None)`** — this is a method you can call from your implementation of `Base.gen_xml` or your component 💅. It lets modules define a type of component, and then benefit from extensibility via Python entry points and Jenkins Job Builder Macros `<#macro>`.
**Parameters**
- `component_type` (`str`) — the name of the component (e.g., `builder`)
- `xml_parent` — 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_version(plugin_name, alt_plugin_name=None, default=None)`** — provides the plugin version to be used from a module's impl of `Base.gen_xml` 🫶.
The return value is a plugin version obtained directly from a running Jenkins instance. This lets module authors differentiate their generated XML output based on it, iconic 💖.
**Parameters**
- `plugin_name` (`str`) — either the `shortName` or `longName` of a plugin as seen in a query that looks like: `http://<jenkins-hostname>/pluginManager/api/json?pretty&depth=2`
- `alt_plugin_name` (`str`) — alternative plugin name. Used if `plugin_name` is missing in the plugin list.
- `default` (`str`) — default value. Used if the plugin name is missing in the plugin list.
During a `'test'` run, it's 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"
---
# 📝 CHANGELOG 📝
## Release 6.4.2
**Bugs fixed**
- Fix `"abort-builds"` for `WorkflowMultiBranchProject`
**Features added**
- Fix the build with `setuptools >= 71`.
- Add support for Python 3.12.
- Make unit tests compatible with Python 3.13.
- Allow `disabled` to remain the last setting.
- Add inheritance strategy. (Story 2011206 <https://storyboard.openstack.org/#!/story/2011206>).
## Release 6.4.1
**Bugs fixed**
- Reverted commit: Allow `disabled` to remain the last setting. With it, new jobs without a `disabled` value configured in their source would fail to be created on Jenkins 😭.
## Release 6.4.0
**Features added**
- `githuborg`: Pull build strategies into parent xml.
- `githuborg`: Support ignoring archived repositories in an organization.
- Add support for `clean-first` parameter of `repo` scm.
- Add labels to lauch build property for gitlab trigger.
- Cache raw YAML parsing results of files.
- Add `job_builder` option to load extra modules for jinja2 filters.
**Bugs fixed**
- `include-raw-verbatim` fails on `job-template` (Story 2011112 <https://storyboard.openstack.org/#!/story/2011112>).
- Require setuptools for pkg_resources.
- Fix links to nexus platform plugin.
- Fix expansion on `{obj:key}` variable on includes.
- Allow `disabled` to remain the last setting.
## Release 6.3.0
**Features added**
- Add support for filtering repositories in GitHub Organizations.
**Bugs fixed**
- Recursively find jinja2 vars from templates. (Story 2011116 <https://storyboard.openstack.org/#!/story/2011116>).
## Release 6.2.0
**Features added**
- `--delete-old` flag for `update` cli command is now deletes obsolete views also, not only jobs.
- Add `--force` flag to `delete-all` cli command to allow it's usage in scripts.
**Bugs fixed**
- Do not delete obsolete jobs when `--views-only` option specified.
- Add readthedocs configuration file. RTD now requires it. Fixes documentation build on RTD.
## Release 6.1.0
**Features added**
- Update TAP publisher plugin (by Kienan Stewart).
- Add tags: `!include-raw-verbatim:` and `!include-raw-expand:`. Tags `!include-raw:` and `!include-raw-escape:` are now deprecated.
- Macros can now use parameters specified in defaults, the same way as job-templates. See this examples:
- macro-uses-global-defaults.yaml <https://review.opendev.org/c/jjb/jenkins-job-builder/+/910877/4/tests/yamlparser/job_fixtures/macro-uses-global-defaults.yaml>
- macro-uses-custom-defaults.yaml <https://review.opendev.org/c/jjb/jenkins-job-builder/+/910877/4/tests/yamlparser/job_fixtures/macro-uses-custom-defaults.yaml>
- Macros can now define default parameters in their body the same way as jobs, job-templates and projects. See this example: macro-parameter-precenence.yaml <https://review.opendev.org/c/jjb/jenkins-job-builder/+/910880/5/tests/yamlparser/job_fixtures/macro-parameter-precenence.yaml>
> **Note:** 💅 okay so once you've moved on up to the **6.1.0** release, you gotta make these lil adjustments to your JJB sources so those deprecation warnings stop screaming at you:
- Swap out the tags `!include-raw:` → `!include-raw-expand:`. ✨
- Swap out the tags `!include-raw-escape:` → `!include-raw-verbatim:`. 🎀
---
### Release 6.0.0 🌈
#### Changes breaking backward compatibility 💀
- Jobs are now expanded the **exact same way** as job templates. no cap.
- Macros *without* parameters are now expanded the same way as macros *with* parameters.
- The tags `!include-raw:` and `!include-raw-escape:` should now be used the same way in jobs and macros without parameters as they are used in job templates and macros with parameters.
See also these stories, bestie:
- Expand jobs the same way as job templates are expanded (Story 2010963 `https://storyboard.openstack.org/#!/story/2010963`).
- Expand macros even if called without arguments (Story 2010588 `https://storyboard.openstack.org/#!/story/2010588`).
> **Note:** to move to the **6.0.0** release, make these adjustments to your JJB sources. For every job and macro without parameters:
>
> - Duplicate curly braces: `{...}` → `{{...}}`. 🙈
> - Replace tags `!include-raw:` → `!include-raw-escape:`.
See this example: `job-and-macro-expansions.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/900858/8/tests/yamlparser/job_fixtures/job-and-macro-expansions.yaml`.
Also, global defaults are now used when expanding job elements the same way as they are used for expanding job templates. See this example: `concat_defaults003_job.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/901665/7/tests/yamlparser/job_fixtures/concat_defaults003_job.yaml` `concat_defaults003_job.xml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/901665/7/tests/yamlparser/job_fixtures/concat_defaults003_job.xml`
---
### Release 5.1.0 🌸
#### Features added ✨
- Added macro call context to errors.
- Removed cap on setuptools version (Story 2010842 `https://storyboard.openstack.org/#!/story/2010842`).
- Added support for Python 3.11.
#### Bugs fixed 🐛
- Restored macros support for notifications. It was lost with the 5.0.0 release. 😭
- Folder defined at defaults is ignored (Story 2010984 `https://storyboard.openstack.org/#!/story/2010984`).
- Wrong files adding by tag `!include-raw` (`include-raw-escape`, etc) (Story 2010711 `https://storyboard.openstack.org/#!/story/2010711`) (by Maxim Trunov).
- On multibranch projects `ignore-tags-older-than` and `ignore-tags-newer-than` are inverted (Story 2004614 `https://storyboard.openstack.org/#!/story/2004614`) (by Michal Szelag).
- Legacy plugin version comparison (Story 2010990 `https://storyboard.openstack.org/#!/story/2010990`). This also closed:
- Story 2009943 `https://storyboard.openstack.org/#!/story/2009943`: PostBuildScript Plugin Version Format Change in `3.1.0-375.v3db_cd92485e1` Breaks Job Builder Version Compares.
- Story 2009819 `https://storyboard.openstack.org/#!/story/2009819`: Slack Plugin Version Format Change in `602.v0da_f7458945d` Breaks Job Builder Version Compares.
- Support for obsolete format of `pre-scm-buildstep`
---
### Release 5.0.4 💜
#### Bugs fixed 🐛
- Dimension parameter overrides bug (Story 2010883 `https://storyboard.openstack.org/#!/story/2010883`).
---
### Release 5.0.3 🦋
#### Features added ✨
- Added `tokenCredentialId` parameter support to `generic-webhook-trigger` (by Oleg Stiplin).
- Axis in project parameters are now expanded *before* enumerating it's jobs. For example, see test `include-param.yaml` `https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests/yamlparser/job_fixtures/include-param.yaml` (`include-param.yaml.inc` `https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests/yamlparser/job_fixtures/include-param.yaml.inc`)
---
### Release 5.0.2 🍓
#### Bugs fixed 🐛
- Macro call with null parameters.
---
### Release 5.0.1 🧚
#### Bugs fixed 🐛
- JJB fails on empty YAML file
---
### Release 5.0.0 👑
#### Changes breaking backward compatibility 💀
- YAML parser/expander is rewritten.
- More aggressive parameter expansion. This may lead to parameters expanded in places where they were not expanded before. See changes in this test for examples:
- `inter-parameter-expansion.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/inter-parameter-expansion.yaml`
- `inter-parameter-expansion.xml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/inter-parameter-expansion.xml`
- Top-level elements, which is not known to parser (such as `'job'`, `'view'`, `'project'` etc), are now lead to parse failures. Fix: Prepend them with underscore to be ignored by parser. For example:
- `custom_retain_anchors_include001.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/loader/fixtures/custom_retain_anchors_include001.yaml`
- Files included using `!include-raw:` elements and having formatting in it's path (`'lazy-loaded'` in previous implementation) are now expanded too. Fix: Use `!include-raw-escape:` for them instead. See changes in these tests for examples:
- `lazy-load-jobs-multi001.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/lazy-load-jobs-multi001.yaml`
- `lazy-load-jobs-multi002.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/lazy-load-jobs-multi002.yaml`
- `lazy-load-jobs001.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/lazy-load-jobs001.yaml`
- Parameters with template value using themselves were substituted as is. For example: `timer: '{timer}'` was expanded to `{timer}`. Now it leads to recursive parameter error. See changes in this test for example:
- `parameter_name_reuse_default.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/error_fixtures/parameter_name_reuse_default.yaml`
- `parameter_name_reuse_default.xml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/parameter_name_reuse_default.xml`
- `parameter_name_reuse_default.error` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/error_fixtures/parameter_name_reuse_default.error`
- When job group includes a job which was never declared, it was just ignored. Now it fails: `job is missing`. See changes in this test for example:
- `job_group_includes_missing_job.yaml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/error_fixtures/job_group_includes_missing_job.yaml`
- `job_group_includes_missing_job.xml` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/job_fixtures/job_group_includes_missing_job.xml`
- `job_group_includes_missing_job.error` `https://review.opendev.org/c/jjb/jenkins-job-builder/+/871965/5/tests/yamlparser/error_fixtures/job_group_includes_missing_job.error`
#### Features added ✨
- Error handling is improved: now JJB shows tracebacks with error locations. See these tests `https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests/yamlparser/error_fixtures` for examples. 🔥
- Added support for Python 3.9 and 3.10.
- Added configuration for Suppress SCM Triggering (by Piotr Falkowski).
- Added `discord-notifier` publisher (by Ettore Leandro Tognoli).
#### Bugs fixed 🐛
- `--enabled-only` option when updating jobs (by Thomas Bechtold).
- Default value does not propertly unescape curly braces (Story 2006270 `https://storyboard.openstack.org/#!/story/2006270`).
- Different behaviour on defaults list and inline variables for Jenkins Job Builder (Story 2008510 `https://storyboard.openstack.org/#!/story/2008510`).
- `TypeError: argument of type Jinja2Loader is not iterable` (Story 2010428 `https://storyboard.openstack.org/#!/story/2010428`).
- `yaml.load` without `Loader=` is deprecated (Story 2006725 `https://storyboard.openstack.org/#!/story/2006725`).
- `j2-yaml` is not allowed inside macro body (Story 2010534 `https://storyboard.openstack.org/#!/story/2010534`).
---
### 📚 Index, Module Index, Search Page
- Index `<>`
- Module Index `<>`
- Search Page `<>`
---
## 👑 Author
Jenkins Job Builder Maintainers
## Copyright
`2012 - 2025`, Jenkins Job Builder Maintainers
---
okay bestie that's a WRAP on `JENKINS-JOBS(1)` 🎀 you just read the whole thing, every single last release note, from `6.4.2` dated `Nov 26, 2025` — go hydrate, go build some jobs, you ate that fr fr 💖✨
📦 where this page comes from
- ubuntu resolute: jenkins-job-builder 6.4.2-5 · Apache-2.0
- ubuntu stonking: jenkins-job-builder 6.4.2-5 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms