This plugin allows you to distinguish good builds from bad builds by introducing the notion of 'promotion'.

Put simply, a promoted build is a successful build that passed additional criteria (such as more comprehensive tests that are set up as downstream jobs.) The typical situation in which you use promotion is where you have multiple 'test' jobs hooked up as downstream jobs of a 'build' job. You'll then configure the build job so that the build gets promoted when all the test jobs passed successfully. This allows you to keep the build job run fast (so that developers get faster feedback when a build fails), and you can still distinguish builds that are good from builds that compiled but had runtime problems.

Another variation of this usage is to manually promote builds (based on instinct or something else that runs outside Jenkins.) Promoted builds will get a star in the build history view, and it can be then picked up by other teams, deployed to the staging area, etc., as those builds have passed additional quality criteria. In more complicated scenarios, one can set up multiple levels of promotions. This fits nicely in an environment where there are multiple stages of testings (for example, QA testing, acceptance testing, staging, and production.)

Promotion Action

When a build is promoted, you can have Jenkins perform some actions (such as running a shell script, triggering other jobs, etc. — or in Jenkins lingo, you can run build steps.) This is useful for example to copy the promoted build to somewhere else, deploy it to your QA server. You can also define it as a separate job and then have the promotion action trigger that job.

The promotion action uses the workspace of the job as the current directory (and as such the execution of the promotion action is mutually exclusive from any on-going builds of the job.) But by the time promotion runs, this workspace can contain files from builds that are totally unrelated from the build being promoted.

To access the artifacts, use the Copy Artifact Plugin and choose the permalink.


To use this plugin, look for the "Promote builds when..." checkbox, on the Job-configuration page. Define one or a series of promotion processes for the job.

Then, after the promotion processes have been added and another build is run, a 'Promotion Status' menu item will be added to the new build's menu options. Note that this means that builds run before this point cannot be promoted.

How might you use promoted builds in your environment? Here are a few use cases.

Artifact storage -- you may not want to push an artifact to your main artifact repository on each build. With build promotions, you can push only when an artifact meets certain criteria. For example, you might want to push it only after an integration test is run.

Manual Promotions - You can choose a group of people who can run a promotion manually. This gives a way of having a "sign off" within the build system. For example, a developer might validate a build and approve it for QA testing only when a work product is completed entirely. Then another promotion can be added for the QA hand off to production.

Aggregation of artifacts - If you have a software release that consists of several not directly related artifacts that are in separate jobs, you might want to aggregate all the artifacts of a proven quality to a distribution location. To do this, you can create a new job, adding a "Copy artifacts from another job" (available through Copy Artifact plugin") for each item you want to aggregate. To get a certain promotion, select "Use permalink" in the copy artifact step, then your promoted build should show up in the list of items to copy.


On Downstream Promotion Conditions

One of the possible criteria for promoting a build is "When the following downstream projects build successfully", which basically says if all the specified jobs successfully built (say build BD of job JD), the build in the upstream will be promoted (say build BU of job JU.)

This mechanism crucially relies on a "link" between BD and BU, for BU isn't always the last successful build. We say "BD qualifies BU" if there's this link, and the qualification is established by one of the following means:

  1. If BD records fingerprints and one of the fingerprints match some files that are produced by BU (which is determined from the fingerprint records of BU), then BD qualifies BU. Intuitively speaking, this indicates that BD uses artifacts from BU, and thus BD helped verify BU's quality.
  2. If BU triggers BD through a build trigger, then BD qualifies BU. This is somewhat weak and potentially incorrect, as there's no machine-readable guarantee that BD actually used anything from BU, but nonetheless this condition is considered as qualification for those who don't configure fingerprints.

Note that in the case #1 above, JU and JD doesn't necessarily have to have any triggering relationship. All it takes is for BD to use some fingerprinted artifacts from BU, and records those fingerprints in BD. It doesn't matter how those artifacts are retrieved either — it could be via Copy Artifact Plugin, it could be through a maven repository, etc. This also means that you can have a single test job (perhaps parameterized), that can promote a large number of different upstream jobs.

Note that after installing this plugin and configuring a promotion process, the option to promote the build will not be available for builds run before the promotion process was configured.

Available Environment Variables

The following environment variables are added for use in scripts, etc. These were retrieved from github here.


Version 3.3 and newer versions

See https://github.com/jenkinsci/promoted-builds-plugin/releases

Version 3.2 (JUN 4, 2018)
Version 3.1 (Mar 12, 2018)
Version 3.0 (Feb 26, 2018)

Compatibility Notes:

Jobs which have no Manual Promotion Condition 

Authorized actions

Granted Permissions
Overall/AdministerPromotion/PromoteUser/group in the manual condition user listJob/Read


N/AN/AN/AN (new)
Re-executeYYN/AN (new)

Jobs which have Manual Promotion Conditionwithout users/groups defined:

Authorized actions

Granted Permissions
Overall/AdministerPromotion/PromoteUser/group in the manual condition user listJob/Read


YYN/AN (new)
Re-executeYYN/AN (new)

Jobs with a Manual Promotion Condition with a non-empty set of users/groups :

Authorized actions

Granted Permissions
Overall/AdministerPromotion/PromoteUser/group in the manual condition user listJob/Read
ApproveY (new)NYN (new)
Re-executeYN (new)YN (new)
ForceYN (new)Y (new)N
Version 2.31.1 (Feb 13, 2018)
Version 2.31 (Oct 23, 2017)
Version 2.30 (Oct 19, 2017)
Version 2.29.1 (Sep 7, 2017)
Version 2.29 (Jun 16, 2017)
Version 2.28.1 (Jan 31, 2017)
Version 2.28 (Nov 18, 2016)
Version 2.27 (May 25th, 2016)
Version 2.26 (May 9th, 2016)
Version 2.25 (Feb 19th, 2016)
Version 2.24.1 (Dec 17th, 2015)
Version 2.24 (Nov 25th, 2015)
Version 2.23.1 (Nov 2nd, 2015)
Version 2.23 (Sept 15th, 2015)
Version 2.22 (Aug 25th, 2015)

The fix for JENKINS-25011 changes the default behavior for paths without an explicit absolute/relative address specification (e.g. project="myProject"). By default it will resolve relative paths and then falls back to global paths. If you have "myProject" within a folder and on the top level, another project may be returned after the plugin update. In order to restore the legacy behavior, use the hudson.plugins.promoted_builds.util.ItemPathResolver.enableResolutionAgainstRoot Boolean system property

Version 2.21 (Apr 7, 2015)
Version 2.20 (Feb 16, 2015)
Version 2.19 (Oct 10, 2104)
Version 2.18 (Aug 25, 2014)
Version 2.17 (Mar 5, 2014)
Version 2.16 (Mar 5, 2014)
Version 2.15 (Jan 28, 2014)
Version 2.14
Version 2.13
Version 2.12 (Aug 20, 2013)
Version 2.11 (Jun 09, 2013)
Version 2.10 (Mar 30, 2013)
Version 2.9 (Mar 25, 2013)
Version 2.8 (Oct 30, 2012)
Version 2.7 (Sep 26, 2012)
Version 2.6.2 (Aug 6, 2012)
Version 2.6.1 (Jul 2, 2012)
Version 2.6 (Jun 21, 2012)
Version 2.5 (Apr 12, 2012)
Version 2.4 (Nov 3, 2011)
Version 2.3.1 (Oct 14, 2011)
Version 2.3 (Aug 9, 2011)
Version 2.2 (Jul 8, 2011)
Version 2.1 (May 4, 2011)
Version 2.0 (Mar 5 2011)
Version 1.11 (Jan 31 2011)
Version 1.10 (Sep 28 2010)
Version 1.9 (Jun 9 2010)
Version 1.8 (Jun 5 2010)
Version 1.7 (Mar 29 2010)
Version 1.6 (Dec 30 2009)
Version 1.5 (Aug 17 2009)
Version 1.4 (May 21 2009)
Version 1.3 (May 11 2009)
Version 1.2 (Mar 25 2009)
Version 1.1 (Feb 20 2009)