Trigger restrictions

This feature requires the Trigger Restrictions Plugin. For more information on how to download a plugin, see Managing plugins.

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:

  1. Freestyle post-build action Build other projects

  2. Freestyle Build step Trigger builds on remote/local jobs

  3. Pipeline build step

  4. Pipeline triggerRemoteJob step

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 **/* (ie. everything 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.

global restrictions

Folder restrictions

Restrictions can also be defined at folder level.

restrictions link

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:


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:

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.

Access control

A new permissions has been added: "Triggers". It grants access to the restrictions configuration in folder. It is implied by Administration, so by default only Administrators will have access to the restrictions configuration.

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.