| This feature requires the Trigger Restrictions plugin. For more information on how to download a plugin, refer to Plugin management. |
This feature allows you to restrict which upstream jobs are allowed to trigger builds of other jobs inside a specific folder or the entire Jenkins instance.
Restrictions are defined in folders and its format is as defined by ANT Glob expressions. A downstream build is allowed to enter the Build Queue if the upstream job name (full name, including folders) matches the restrictions defined in the folder hierarchy, including a global restriction if set.
A build is evaluated for Restrictions compliance only when it is a downstream job triggered by:
-
Freestyle post-build action Build other projects
-
Freestyle Build step Trigger builds on remote/local jobs
-
Pipeline
buildstep -
Pipeline
triggerRemoteJobstep
Global restrictions
The global restriction can be set to restrict build triggers in the whole Jenkins instance (it affects all folders).
The default value for the global restriction is **/*, which indicates that everything is allowed, for backward compatibility. In a Jenkins instance
without this plugin all upstreams are allowed.
It can be overridden in folders to reduce the allowed set of upstreams in specific folders.
To deny any build coming from upstream triggers leave the field empty.
To set the global restriction go to Manage Jenkins >> Configure System >> Default Trigger Restrictions.
Folder restrictions
Restrictions can also be defined at folder level.
When an upstream job tries to trigger a downstream inside a folder, the whole restrictions hierarchy is checked (starting on the folder containing the downstream job and traversing the hierarchy upwards until the global configuration is reached). The downstream job is allowed to enter the build queue if (and only if) the upstream job full name satisfies restrictions in the whole hierarchy.
For example, given the following folder hierarchy:
+-- Jenkins Global (default: "**/*") +-- Folder A (restriction: "Folder A/**/*") |-- Job A |-- Job A1 +-- Folder B (restriction: "Folder B/**/*") |-- Job B |-- Job B1
"Job A" will be able to trigger builds on "Job A1" but not on "Job B" or "Job B1". And "Job B" will be able trigger "Job B1" but not "Job A" or "Job A1". However, if the restriction on "Folder B" is modified to:
Folder B/**/* Folder A/*
Then "Job A" will be able to trigger builds on anything inside "Folder B" (as the upstream full name "Folder A/Job A" matches one of the rules defined in "Folder B").
| restriction expressions are always absolute based on Jenkins root. Using ".." or "." to refer to the parent folder or current folder is not allowed. |
Remote Jenkins restrictions
Upstream triggers coming from other Jenkins instances (using triggerRemoteJob) can also be restricted. For example, to restrict remote incoming triggers from a specific Jenkins instance:
jenkins://ac64e5c73e5102cbc56055d4898c0fd1/**/*
This configuration will allow triggers coming from a Jenkins instance with the instance ID ac64e5c73e5102cbc56055d4898c0fd1 but no other triggers (including the local Jenkins instance).
Remote and local syntax can be combined, for example:
jenkins://ac64e5c73e5102cbc56055d4898c0fd1/**/* Folder A/**/*
If that is set in "Folder A" itself, then it means jobs in the folder only accept triggers coming from the remote Jenkins with the given ID and local triggers within the folder itself. The remote restriction can also contain a path after the ID.
The Jenkins instance ID can be obtained in various ways, the easiest is to look at the license page of your instance (Manage Jenkins >> Manage License).
Note that triggerRemoteJob step will generate remote style upstream references even when it is used on local jobs, so restrictions have to be configured accordingly.
|
Restrictions consistency check
As described above, restrictions are checked in the whole folder hierarchy until reaching the top Jenkins level (the global configuration). A trigger is allowed if it is accepted by all folder restrictions in the path to the root (including the Global restriction). It is assumed restrictions are consistent as in: any given child restriction is, at least, as restrictive as its parent.
For example this configuration would be invalid:
+-- Jenkins Global (default: "**/*") +-- Folder A (restriction: "Folder A/**/*") +-- Sub Folder (restriction: "**/*") |-- Job A
In this case "Sub Folder" is opening up the restriction to "all allowed" whilst its parent is restricting to "Folder A" contents. If an upstream from outside "Folder A" tries to trigger "Job A", then it will be rejected by "Folder A" restrictions and a log message will be printed to point to the inconsistency.
INFO: Rejecting build on [Folder A/Sub Folder/Job A] as the upstream job/s [SomeOther Job] do not match trigger restrictions on [Folder A] WARNING: Trigger restrictions inconsistency found. [Folder A/Sub Folder] restrictions configuration is less restrictive than its parent/ancestor [Folder A]
In general, the most restrictive rule in the folder hierarchy will be enforced and a consistency check is done on every run.