{"id":15045296,"url":"https://github.com/jenkinsci/promoted-builds-plugin","last_synced_at":"2026-03-03T01:36:24.522Z","repository":{"id":858953,"uuid":"1163731","full_name":"jenkinsci/promoted-builds-plugin","owner":"jenkinsci","description":"Jenkins Promoted Builds Plugin","archived":false,"fork":false,"pushed_at":"2025-08-18T10:25:51.000Z","size":1455,"stargazers_count":96,"open_issues_count":12,"forks_count":170,"subscribers_count":109,"default_branch":"master","last_synced_at":"2025-08-18T12:23:31.931Z","etag":null,"topics":["adopt-this-plugin","jenkins-plugin","promote-builds","promotion-action"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/promoted-builds","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-12-13T05:51:37.000Z","updated_at":"2025-08-18T10:25:55.000Z","dependencies_parsed_at":"2023-07-05T19:33:57.967Z","dependency_job_id":"35947cdd-69c8-4000-85e7-881d84681c5e","html_url":"https://github.com/jenkinsci/promoted-builds-plugin","commit_stats":{"total_commits":841,"total_committers":102,"mean_commits":8.245098039215685,"dds":0.6135552913198573,"last_synced_commit":"2528ee66e6a6b945054ae523f373487608da073b"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/jenkinsci/promoted-builds-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpromoted-builds-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpromoted-builds-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpromoted-builds-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpromoted-builds-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/promoted-builds-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fpromoted-builds-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272155752,"owners_count":24883096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adopt-this-plugin","jenkins-plugin","promote-builds","promotion-action"],"created_at":"2024-09-24T20:51:42.043Z","updated_at":"2026-03-03T01:36:19.192Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nPromoted Builds Plugin\n======================\n\n[![Join the chat at https://gitter.im/jenkinsci/promoted-builds-plugin](https://badges.gitter.im/jenkinsci/promoted-builds-plugin.svg)](https://gitter.im/jenkinsci/promoted-builds-plugin?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Jenkins Plugin](https://img.shields.io/jenkins/plugin/v/promoted-builds.svg)](https://plugins.jenkins.io/promoted-builds)\n[![GitHub release](https://img.shields.io/github/release/jenkinsci/promoted-builds-plugin.svg?label=changelog)](https://github.com/jenkinsci/promoted-builds-plugin/releases/latest)\n[![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/promoted-builds.svg?color=blue)](https://plugins.jenkins.io/promoted-builds)\n\nThis plugin allows you to distinguish good builds from bad builds by\nintroducing the notion of 'promotion'.Put simply, a promoted build is a\nsuccessful build that passed additional criteria (such as more comprehensive\ntests that are set up as downstream jobs.) The typical situation in which you\nuse promotion is where you have multiple 'test' jobs hooked up as downstream\njobs of a 'build' job. You'll then configure the build job so that the build\ngets promoted when all the test jobs passed successfully. This allows you to\nkeep the build job run fast (so that developers get faster feedback when a  \nbuild fails), and you can still distinguish builds that are good from builds\nthat compiled but had runtime problems.\n\nAnother variation of this usage is to manually promote builds (based on\ninstinct or something else that runs outside Jenkins.) Promoted builds will\nget a star in the build history view, and it can be then picked up by other\nteams, deployed to the staging area, etc., as those builds have passed\nadditional quality criteria. In more complicated scenarios, one can set up\nmultiple levels of promotions. This fits nicely in an environment where there\nare multiple stages of testings (for example, QA testing, acceptance testing,\nstaging, and production.)\n\n\u003ca name=\"PromotedBuildsPlugin-PromotionAction\"\u003e\u003c/a\u003e\n# Promotion Action\n\nWhen a build is promoted, you can have Jenkins perform some actions (such as\nrunning a shell script, triggering other jobs, etc. — or in Jenkins lingo, you\ncan run build steps.) This is useful for example to copy the promoted build to\nsomewhere else, deploy it to your QA server. You can also define it as a\nseparate job and then have the promotion action trigger that job.\n\n\u003e **Do not rely on files in the workspace**\nThe promotion action uses the workspace of the job as the current directory\n(and as such the execution of the promotion action is mutually exclusive from\nany on-going builds of the job.) But by the time promotion runs, this\nworkspace can contain files from builds that are totally unrelated from the\nbuild being promoted.\n\nTo access the artifacts, use the [Copy Artifact Plugin][1] and choose\nthe permalink.\n\n\n\u003ca name=\"PromotedBuildsPlugin-Usage\"\u003e\u003c/a\u003e\n# Usage\n\nTo use this plugin, look for the \"Promote builds when...\" checkbox, on the\nJob-configuration page. Define one or a series of promotion processes for\nthe job.\n\nHow might you use promoted builds in your environment? Here are a few\nuse cases.\n\nArtifact storage -- you may not want to push an artifact to your main artifact\nrepository on each build. With build promotions, you can push only when an\nartifact meets certain criteria. For example, you might want to push it only\nafter an integration test is run.\n\nManual Promotions - You can choose a group of people who can run a promotion\nmanually. This gives a way of having a \"sign off\" within the build system. For\nexample, a developer might validate a build and approve it for QA testing only\nwhen a work product is completed entirely. Then another promotion can be added\nfor the QA hand off to production.\n\nAggregation of artifacts - If you have a software release that consists of\nseveral not directly related artifacts that are in separate jobs, you might\nwant to aggregate all the artifacts of a proven quality to a distribution\nlocation. To do this, you can create a new job, adding a \"Copy artifacts from\nanother job\" (available through Copy Artifact plugin\") for each item you want\nto aggregate. To get a certain promotion, select \"Use permalink\" in the copy\nartifact step, then your promoted build should show up in the\nlist of items to copy.\n\n\u003ca name=\"PromotedBuildsPlugin-Notes\"\u003e\u003c/a\u003e\n# Notes\n\n\u003ca name=\"PromotedBuildsPlugin-OnDownstreamPromotionConditions\"\u003e\u003c/a\u003e\n### On Downstream Promotion Conditions\n\nOne of the possible criteria for promoting a build is \"When the following\ndownstream projects build successfully\", which basically says if all the\nspecified jobs successfully built (say build BD of job JD), the build in the\nupstream will be promoted (say build BU of job JU.)\n\nThis mechanism crucially relies on a \"link\" between BD and BU, for BU isn't\nalways the last successful build. We say \"BD qualifies BU\" if there's this\nlink, and the qualification is established by one of the following\nmeans:\n\n1.  If BD records fingerprints and one of the fingerprints match some files\nthat are produced by BU (which is determined from the fingerprint records of\nBU), then BD qualifies BU. Intuitively speaking, this indicates that BD uses\nartifacts from BU, and thus BD helped verify BU's quality.\n2.  If BU triggers BD through a build trigger, then BD qualifies BU. This is\nsomewhat weak and potentially incorrect, as there's no machine-readable\nguarantee that BD actually used anything from BU, but nonetheless this\ncondition is considered as qualification for those who don't\nconfigure fingerprints.\n\nNote that in the case #1 above, JU and JD doesn't necessarily have to have any\ntriggering relationship. All it takes is for BD to use some fingerprinted\nartifacts from BU, and records those fingerprints in BD. It doesn't matter how\nthose artifacts are retrieved either — it could be via\n[Copy Artifact Plugin][1], it could be through a maven repository, etc. This\nalso means that you can have a single test job (perhaps parameterized), that\ncan promote a large number of different upstream jobs.\n\n\u003ca name=\"PromotedBuildsPlugin-AvailableEnvironmentVariables\"\u003e\u003c/a\u003e\n### Available Environment Variables\n\nThe following environment variables are added for use in scripts, etc.\nThese were retrieved from github [here][2].\n\n*   `PROMOTED_URL` - URL of the job being promoted\n    *   ex: [http://jenkins/job/job_name_being_promoted/77/](http://jenkins/job/job_name_being_promoted/77/)\n*   `PROMOTED_JOB_NAME` - Promoted job name\n    *   ex: job_name_being_promoted\n*   `PROMOTED_NUMBER` - Build number of the promoted job\n    *   ex: 77\n*   `PROMOTED_ID` - ID of the build being promoted\n    *   ex: 2012-04-12_17-13-03\n*   `PROMOTED_USER_NAME` - the user who triggered the promotion\n*   `PROMOTED_JOB_FULL_NAME` - the full name of the promoted job\n\n## Job DSL support\n\n```groovy  \nfreeStyleJob(String jobname) {\n  properties{\n    promotions {\n      promotion {\n        name(String promotionName)\n        icon(String iconName)\n        conditions {\n          selfPromotion(boolean evenIfUnstable = true)\n          parameterizedSelfPromotion(boolean evenIfUnstable = true, String parameterName, String parameterValue)\n          releaseBuild()\n          downstream(boolean evenIfUnstable = true, String jobs)\n          upstream(String promotionNames)\n          manual(String user){\n            parameters{\n              textParam(String parameterName, String defaultValue, String description)\n          }\n        }\n        wrappers {\n          /* build wrappers, e.g. credentialsBinding */\n        }\n        actions {\n          shell(String command)\n        }\n      }\n    }\n  }\n}\n```\n\nSee [WrapperContext](https://jenkinsci.github.io/job-dsl-plugin/#path/job-wrappers) and [StepContext](https://jenkinsci.github.io/job-dsl-plugin/#path/job-steps) in the API Viewer for full documentation about the possible wrappers and actions.\n\n### Example\n\n```groovy\nfreeStyleJob('test-job') {\n  properties{\n    promotions {\n      promotion {\n        name('Development')\n        conditions {\n          manual('testuser')\n        }\n        wrappers {\n          timestamps()\n        }\n        actions {\n          shell('echo hello;')\n        }\n      }\n    }\n  }\n}\n```\n\n[1]: https://wiki.jenkins-ci.org/display/JENKINS/Copy+Artifact+Plugin\n[2]: https://github.com/jenkinsci/promoted-builds-plugin/blob/master/src/main/java/hudson/plugins/promoted_builds/Promotion.java\n\n## Undergoing project based on this Plugin\n\n* `Artifact Promotion Plugin For Jenkins Pipeline` - Under GSoC 2019.\n   Join with the Project through the following Chat Link:\n    * [promoted-builds-plugin](https://gitter.im/jenkinsci/promoted-builds-plugin)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fpromoted-builds-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fpromoted-builds-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fpromoted-builds-plugin/lists"}