View Source

{excerpt}This plugin allows you to distinguish good builds from bad builds by introducing the notion of 'promotion'.{excerpt} 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 Hudson.) 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.)

h1.Promotion Action
When a build is promoted, you can have Hudson perform some actions (such as running a shell script, triggering other jobs, etc. --- or in Hudson 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.

{note:title=Do not rely on files in the workspace}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.

TODO: talk about a typical set up, the configuration, manual promotion, PROMOTED_URL.

h2. Changelog
h5. Version 1.11 (Jan 31 2011)
* Promote a build even if downstream build is unstable. ([8626@issue])
* Promote Builds Plugin can use custom workspace. ([8547@issue])
* Invalid characters in Promotion name causes error. ([7972@issue])
* Fix promotion permlinks. ([8367@issue])
* Allow promotion actions to be reordered. ([8548@issue])

h5. Version 1.10 (Sep 28 2010)
* Promotion processes are now recognized as permalinks.

h5. Version 1.9 (Jun 9 2010)
* If fingerprints are not available, use the upstream/downstream triggering information to determine the relationship as a fallback.

h5. Version 1.8 (Jun 5 2010)
* Add the possibility to choose a different color for the star icon, to be able to differenciate the various promotion processes

h5. Version 1.7 (Mar 29 2010)
* Use JDK configured for project when running promotions ([3526@issue])
* Select node for running promotions from label configured for project ([4089@issue]) (does not yet run on exact node where promoted build ran, unless project is tied to a single node)
* Show most-recent first in promotion history tables ([6073@issue])

h5. Version 1.6 (Dec 30 2009)
* Fix for running on slave node ([4635@issue])
* Copy promotions when a job is copied ([3489@issue])
* Fix broken "Back to Promotion Status" link ([3562@issue])

h5. Version 1.5 (Aug 17 2009)
* Updated to work with Hudson 1.320

h5. Version 1.4 (May 21 2009)
* Re-doing a release as 1.3 had never shown up in the update center.

h5. Version 1.3 (May 11 2009)
* Expose environment variable 'PROMOTED_URL' that points to the URL of the build that's being promoted ([report|])
* Internal modernization.

h5. Version 1.2 (Mar 25 2009)
* Updated to work with the current Hudson

h5. Version 1.1 (Feb 20 2009)
* Fixed a problem where Hudson may issue the same warning multiple times for the same configuration problem ([report|])
* SVN Tagging is now a permitted promotion step
* Promotion now fails if any actions are not performed ([2597@issue])
* Improved logging of promotion build process so users can see what succeeded and what failed
* Promotion action to build another project no longer does nothing ([1765@issue])
* Added "Promotion History" pane to the PromotedBuildAction page ([2794@issue])
* Fixed 404 for last failed link while promotion build occuring ([2578@issue])