Triggers
Triggers define what causes a Jenkins job to start building.
- Component: triggers
Macro: | trigger |
Entry Point: | jenkins_jobs.triggers |
Example:
job:
name: test_job
triggers:
- timed: '@daily'
-
bitbucket
Trigger a job when bitbucket repository is pushed to.
Requires the Jenkins BitBucket Plugin.
Example:
-
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, ...).
Requires the Jenkins BuildResultTrigger Plugin.
Parameters: |
- groups (list) – List groups of jobs and results to monitor for
- jobs (list) – The jobs to monitor (required)
- results (list) – Build results to monitor for (default success)
- combine (bool) – Combine all job information. A build will be
scheduled only if all conditions are met (default false)
- cron (str) – The cron syntax with which to poll the jobs for the
supplied result (default ‘’)
|
Example:
triggers:
- build-result:
combine: true
cron: '* * * * *'
groups:
- jobs:
- foo
- example
results:
- unstable
- jobs:
- foo2
results:
- not-built
- aborted
-
gerrit
Trigger on a Gerrit event.
Requires the Jenkins Gerrit Trigger Plugin
version >= 2.6.0.
Parameters: |
- trigger-on (list) –
Events to react on. Please use either the new
trigger-on, or the old trigger-on-* events definitions. You
cannot use both at once.
- 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.
Requires 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.
Requires 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) –
Approval category for comment added
Deprecated since version 1.1.0.: Please use trigger-on.
- trigger-approval-value (int) –
Approval value for comment added
Deprecated since version 1.1.0.: Please use trigger-on.
- override-votes (bool) – Override default vote values
- gerrit-build-started-verified-value (int) – Started ‘’Verified’’ value
- gerrit-build-successful-verified-value (int) – Successful ‘’Verified’’
value
- gerrit-build-failed-verified-value (int) – Failed ‘’Verified’’ value
- gerrit-build-unstable-verified-value (int) – Unstable ‘’Verified’’ value
- gerrit-build-notbuilt-verified-value (int) – Not built ‘’Verified’’
value
- gerrit-build-started-codereview-value (int) – Started ‘’CodeReview’’
value
- gerrit-build-successful-codereview-value (int) – Successful
‘’CodeReview’’ value
- gerrit-build-failed-codereview-value (int) – Failed ‘’CodeReview’’ value
- gerrit-build-unstable-codereview-value (int) – Unstable ‘’CodeReview’’
value
- gerrit-build-notbuilt-codereview-value (int) – Not built ‘’CodeReview’’
value
- failure-message (str) – Message to leave on failure (default ‘’)
- successful-message (str) – Message to leave on success (default ‘’)
- unstable-message (str) – Message to leave when unstable (default ‘’)
- notbuilt-message (str) – Message to leave when not built (default ‘’)
- failure-message-file (str) – Sets the filename within the workspace from
which to retrieve the unsuccessful review message. (optional)
- projects (list) –
list of projects to match
Project: |
- project-compare-type (str) – ‘’PLAIN’‘, ‘’ANT’’ or
‘’REG_EXP’‘
- project-pattern (str) – Project name pattern to match
- branch-compare-type (str) – ‘’PLAIN’‘, ‘’ANT’’ or
‘’REG_EXP’’ (not used if branches list is specified)
Deprecated since version 1.1.0: Please use branches.
- branch-pattern (str) – Branch name pattern to match
(not used if branches list is specified)
Deprecated since version 1.1.0: Please use branches.
- branches (list) – List of branches to match
(optional)
Branch: |
- branch-compare-type (str) – ‘’PLAIN’‘,
‘’ANT’’ or ‘’REG_EXP’’ (optional) (default
‘’PLAIN’‘)
- branch-pattern (str) – Branch name pattern
to match
|
- file-paths (list) – List of file paths to match
(optional)
File Path: |
- compare-type (str) – ‘’PLAIN’‘, ‘’ANT’’
or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’‘)
- pattern (str) – File path pattern to
match
|
- forbidden-file-paths (list) – List of file paths to
skip triggering (optional)
Forbidden File Path: |
|
- compare-type (str) –
‘’PLAIN’‘, ‘’ANT’’ or ‘’REG_EXP’’ (optional)
(default ‘’PLAIN’‘)
- pattern (str) – File path pattern to
match
|
- topics (list) – List of topics to match
(optional)
File Path: |
- compare-type (str) – ‘’PLAIN’‘, ‘’ANT’’
or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’‘)
- pattern (str) – Topic name pattern to
match
|
|
- skip-vote (dict) –
map of build outcomes for which Jenkins must skip
vote. Requires Gerrit Trigger Plugin version >= 2.7.0
Outcome: |
- successful (bool)
- failed (bool)
- unstable (bool)
- notbuilt (bool)
|
- 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)
- no-name-and-email (bool) – Do not pass compound ‘name and email’
parameters (default false)
- readable-message (bool) – If parameters regarding multiline text,
e.g. commit message, should be as human readable or not. If false,
those parameters are Base64 encoded to keep environment variables
clean. (default false)
- dependency-jobs (str) – All jobs on which this job depends. If a commit
should trigger both a dependency and this job, the dependency will be
built first. Use commas to separate job names. Beware of cyclic
dependencies. (optional)
- notification-level (str) – Defines to whom email notifications should be
sent. This can either be nobody (‘NONE’), the change owner (‘OWNER’),
reviewers and change owner (‘OWNER_REVIEWERS’), all interested users
i.e. owning, reviewing, watching, and starring (‘ALL’) or server
default (‘SERVER_DEFAULT’). (default ‘SERVER_DEFAULT’)
- dynamic-trigger-enabled (bool) – Enable/disable the dynamic trigger
(default false)
- dynamic-trigger-url (str) – if you specify this option, the Gerrit
trigger configuration will be fetched from there on a regular interval
- trigger-for-unreviewed-patches (bool) – trigger patchset-created events
for changes that were uploaded while connection to Gerrit was down
(default false). Requires Gerrit Trigger Plugin version >= 2.11.0
- custom-url (str) – Custom URL for a message sent to Gerrit. Build
details URL will be used if empty. (default ‘’)
- server-name (str) – 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.
You must also supply at least one project and branch, optionally
more. If you select the comment-added trigger, you should also
indicate which approval category and value you want to trigger the
job.
Until version 0.4.0 of Jenkins Job Builder, camelCase keys were used to
configure Gerrit Trigger Plugin, instead of hyphenated-keys. While still
supported, camedCase keys are deprecated and should not be used. Support
for this will be removed after 1.0.0 is released.
Example:
triggers:
- gerrit:
trigger-on:
- patchset-created-event:
exclude-drafts: true
exclude-trivial-rebase: true
exclude-no-code-change: true
- 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
silent: false
silent-start: true
escape-quotes: false
no-name-and-email: false
dependency-jobs: 'job1, job2'
notification-level: ALL
dynamic-trigger-enabled: true
dynamic-trigger-url: http://myhost/mytrigger
trigger-for-unreviewed-patches: true
server-name: my-server
failure-message-file: path/to/filename
-
github
Trigger a job when github repository is pushed to.
Requires the Jenkins GitHub Plugin.
Example:
-
github-pull-request
Build pull requests in github and report results.
Requires the Jenkins GitHub Pull Request Builder Plugin.
Parameters: |
- admin-list (list) – the users with admin rights (optional)
- 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 false)
- cron (string) – cron syntax of when to run (optional)
- trigger-phrase (string) – 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 false)
- github-hooks (bool) – use github hook (default false)
- permit-all (bool) – build every pull request automatically
without asking (default false)
- auto-close-on-fail (bool) – close failed pull request automatically
(default 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)
- auth-id (string) – the auth id to use (optional)
- build-desc-template (string) – the template for build descriptions in
jenkins (optional)
- status-context (string) – the context to include on PR status comments
(optional)
- triggered-status (string) – the status message to set when the build has
been triggered (optional)
- started-status (string) – the status comment to set when the build has
been started (optional)
- status-url (string) – the status URL to set (optional)
- success-status (string) – the status message to set if the job succeeds
(optional)
- failure-status (string) – the status message to set if the job fails
(optional)
- error-status (string) – the status message to set if the job errors
(optional)
- success-comment (string) – comment to add to the PR on a successful job
(optional)
- failure-comment (string) – comment to add to the PR on a failed job
(optional)
- error-comment (string) – comment to add to the PR on an errored job
(optional)
|
Example:
triggers:
- github-pull-request:
admin-list:
- user1
- user2
white-list:
- user3
- user4
org-list:
- org1
- org2
cron: '* * * * *'
build-desc-template: "build description"
trigger-phrase: 'retest this please'
only-trigger-phrase: true
github-hooks: true
permit-all: false
auto-close-on-fail: false
allow-whitelist-orgs-as-admins: true
white-list-target-branches:
- master
- testing
auth-id: '123-456-789'
-
gitlab
Makes Jenkins act like a GitlabCI server
Requires the Jenkins Gitlab Plugin..
Parameters: |
- trigger-push (bool) – Build on Push Events (default: true)
- trigger-merge-request (bool) – Build on Merge Request Events (default:
True)
- trigger-open-merge-request-push (bool) – Rebuild open Merge Requests on
Push Events (default: True)
- ci-skip (bool) – Enable [ci-skip] (default True)
- set-build-description (bool) – Set build description to build cause
(eg. Merge request or Git Push ) (default: True)
- add-note-merge-request (bool) – Add note with build status on
merge requests (default: True)
- add-vote-merge-request (bool) – Vote added to note with build status
on merge requests (default: True)
- allow-all-branches (bool) – Allow all branches (Ignoring Filtered
Branches) (default: False)
- include-branches (list) – Defined list of branches to include
(default: [])
- exclude-branches (list) – Defined list of branches to exclude
(default: [])
|
Example:
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
allow-all-branches: true
include-branches:
- 'master'
- 'master2'
- 'local-test'
exclude-branches:
- 'broken-test'
- 'master-foo'
-
gitlab-merge-request
Build merge requests in gitlab and report results.
Requires the Jenkins Gitlab MergeRequest Builder Plugin..
Parameters: |
- cron (string) – cron syntax of when to run (required)
- project-path (string) – gitlab-relative path to project (required)
|
Example:
triggers:
- gitlab-merge-request:
cron: '* * * * *'
project-path: 'test/project'
-
groovy-script
Triggers the job using a groovy script.
Requires the Jenkins ScriptTrigger Plugin.
Parameters: |
- 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. (optional)
- 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 ‘’)
|
Example:
triggers:
- groovy-script:
script-file-path: 'path/to/filename'
cron: 'H/15 * * * *'
enable-concurrent: true
label: master
system-script: true
-
ivy
Poll with an Ivy script
Requires the Jenkins IvyTrigger Plugin.
Parameters: |
- path (str) – Path of the ivy file. (optional)
- settings-path (str) – Ivy Settings Path. (optional)
- str 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 ‘’)
|
Example:
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
-
monitor-files
Configure Jenkins to monitor files.
Requires the Jenkins Filesystem Trigger Plugin.
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 dont know the real file
path. (required)
- strategy (str) – Choose your strategy if there is more
than one matching file. Can be one of Ignore file (‘IGNORE’) or
Use the most recent (‘LATEST’). (default ‘LATEST’)
- 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).
(default false)
- jar (bool) – Trigger on change in content of the
specified JAR file. (default false)
- tar (bool) – Trigger on change in content of the
specified Tar file. (default false)
- zip (bool) – Trigger on change in content of the
specified ZIP file. (default false)
- 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. (default true)
|
- 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. (default true)
|
- properties (list) – Monitor the contents of the
properties file.
Properties File: |
|
- keys (list) – List of keys to inspect.
(optional)
- all-keys (bool) – If true, take into
account all keys. (default true)
|
- xml (list str) – Trigger on change to the listed
XPath expressions.
- text (list str) – Trigger on change to the listed
regular expressions.
|
- ignore-modificaton-date (bool) – If true, ignore the file
modification date. Only valid when content changes of the file
are being monitored. (default true)
|
- cron (str) – cron syntax of when to run (default ‘’)
|
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
Configure Jenkins to monitor folders.
Requires the Jenkins Filesystem Trigger Plugin.
Parameters: |
- path (str) – Folder path to poll. (optional)
- includes (list) – Fileset includes setting that specifies the list of
includes files. Basedir of the fileset is relative to the workspace
root. If no value is set, all files are used. (optional)
- excludes (str) – The ‘excludes’ pattern. A file that matches this mask
will not be polled even if it matches the mask specified in ‘includes’
section. (optional)
- check-modification-date (bool) – Check last modification date.
(default true)
- check-content (bool) – Check content. (default true)
- check-fewer (bool) – Check fewer or more files (default true)
- cron (str) – cron syntax of when to run (default ‘’)
|
Example:
triggers:
- monitor-folders:
path: 'pathname'
includes:
- 'pattern1'
- 'pattern2'
excludes: 'pattern1'
check-modification-date: false
check-content: false
check-fewer: false
cron: 'H/15 * * * *'
-
pollscm
Poll the SCM to determine if there has been a change.
Parameter: | the polling interval (cron syntax) |
Deprecated since version 1.3.0.: Please use cron.
Parameters: |
- cron (string) – the polling interval (cron syntax, required)
- ignore-post-commit-hooks (bool) – Ignore changes notified by SCM
post-commit hooks. The subversion-plugin supports this since
version 1.44. (default false)
|
Example:
triggers:
- pollscm:
cron: "*/30 * * * *"
ignore-post-commit-hooks: True
-
pollurl
Trigger when the HTTP response from a URL changes.
Requires the Jenkins URLTrigger Plugin.
Parameters: |
- cron (string) – cron syntax of when to run (default ‘’)
- polling-node (string) – Restrict where the polling should run.
(optional)
- urls (list) –
List of URLs to monitor
URL: |
- url (str) – URL to monitor for changes (required)
- proxy (bool) – Activate the Jenkins proxy (default false)
- timeout (int) – Connect/read timeout in seconds
(default 300)
- username (string) – User name for basic authentication
(optional)
- password (string) – Password for basic authentication
(optional)
- check-status (int) – Check for a specific HTTP status
code (optional)
- check-etag (bool) – Check the HTTP ETag for changes
(default false)
- check-date (bool) – Check the last modification date of
the URL (default false)
- check-content (list) – List of content type changes to
monitor
Content Type: |
- simple (bool) – Trigger on any change to
the content of the URL (default false)
- 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+'
-
reverse
This trigger can be configured in the UI using the checkbox with the
following text: ‘Build after other projects are built’.
Set up a trigger so that when some other projects finish building, a new
build is scheduled for this project. This is convenient for running an
extensive test after a build is complete, for example.
This configuration complements the “Build other projects” section in the
“Post-build Actions” of an upstream project, but is preferable when you
want to configure the downstream project.
Parameters: |
- jobs (str) – List of jobs to watch. Can be either a comma separated
list or a list.
- result (str) – Build results to monitor for between the following
options: success, unstable and failure. (default ‘success’).
|
Example:
triggers:
- reverse:
jobs: 'Fantastic-job'
result: 'failure'
Example List:
triggers:
- reverse:
jobs:
- 'a'
- 'b'
- 'c'
result: 'failure'
-
script
Triggers the job using shell or batch script.
Requires the Jenkins ScriptTrigger Plugin.
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. (optional)
- 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)
|
Example:
-
timed
Trigger builds at certain times.
Parameter: | when to run the job (cron syntax) |
Example:
triggers:
- timed: "@midnight"