--- name: devsecops-devsecops-promotion-pipeline title: Promotion pipeline description: The promotion pipeline promotes inventory entries from one environment to another and creates a promotion pull/merge request. last-updated: 2026-08-14 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/devsecops?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Promotion pipeline {: #cd-devsecops-promotion-pipeline} The promotion pipeline promotes inventory entries from one environment to another and creates a promotion pull/merge request. {: shortdesc} ## Separation of Duties during Promotions {: #cd-devsecops-separation-of-duties} - Promotions achieved primarily through **Pull Request workflow** - → Create promotion PR (e.g. from source to target env branch) - → Review/edit PR (including PR validation status check) - → Merge PR into target env branch - → Run CD deployment pipeline (on commit, timer or manual trigger) - → Rinse and repeat for next environment branch - → Can have arbitrary number of environment branches - Roles - **Developer** : Commit code, resulting in CI pipeline updating main (non-prod) inventory - **Promotion Ops / Release Manager** : Trigger promotion pipeline (main→staging and/or staging→prod), creating PR with status check for gating (enforced by toolchain ACL, and inventory branch protections) - **Production Ops / Approver** : Review and merge promotion PR into prod branch. Run prod pipelines. (enforced by inventory branch protection) - Leverage **distinct CD toolchains for staging and production** workloads (distinct Ops) - This means a developer can prepare a change, but cannot unilaterally place it in production if branch protection requires a separate approver. - The **promotion PR becomes the formal change approval record**, and the merge history provides auditable evidence of who approved the production promotion and when. ## Promotion pipeline steps {: #cd-devsecops-promotion-pipelinesteps} 1. Get inputs for the promotion and the promotion pull/merge request. 2. Promote the inventory entries from the source environment to the target environment. 3. Create the promotion pull/merge request. Edit the pull/merge request to indicate which changes to perform. Watch for optional and mandatory fields. 4. Optional. Set the evidence statuses, and add the aggregated evidence summary to the promotion pull/merge request. 5. Merge the pull/merge request. 6. Send a Slack notification if the feature is turned on. ## Stages and tasks {: #cd-devsecops-promotion-pipeline-stages} The following table lists the tasks run in a Promotion pipeline. In addition, the table also provides an overview of each of these stages: - **Task or Stage**: This refers to the name of the stage as defined within the `.pipeline-config.yaml` configuration file. - **Short description**: This provides a concise explanation of the actions performed during the execution of the stage. - **Customisation permissible**: This indicates whether users have the flexibility to modify or replace the default behavior of the stage by inserting a custom script in the `.pipeline-config.yaml` file. - **Default Reference Implementation**: This indicates whether the DevSecOps pipelines come with a pre-defined or default implementation for the stage. Notably, for certain stages like `unit-tests` or `setup`, the DevSecOps pipeline doesn't offer any out-of-the-box implementation. Instead, users are required to provide custom scripts or code tailored to their application's requirements. - **Evidence Collection**: This indicates whether the stage performs the collection of standard evidence. When DevSecOps Pipeline provide a reference implementation for a stage, evidence collection is performed out-of-the-box. However, if user choose to modify or replace these predefined stages, they must ensure that their custom implementations include appropriate evidence collection. The same responsibility falls on users for stages where the DevSecOps pipeline doesn't provide an out-of-the-box implementation, necessitating them to perform evidence collection. The column indicates the entity (**User/Pipeline**) responsible for carrying out the evidence collection. - **Skip permissible (applicable to version >= v10)**: This indicates whether users can opt out of running this stage by setting the skip property to true in the `.pipeline-config.yaml`. However, caution is advised when using this feature, especially for stages designed to collect evidence. Skipping such stages might lead to missing essential evidences for the build. |Task or stage |Short description |Customisation permissible in `.pipeline-config.yaml` | Default Reference Implementation |Evidence Collection |Skip permissible | |:----------|:------------------------------|:------------------|:------------------|:------------------|:------------------| |`inventory-promotion` |Create pull request for the promotion. |No | Yes | NA | No | |`inventory-finish` |Collect and upload log files, artifact, and evidence to the evidence locker. |Yes | No | NA | No | {: caption="Promotion pipeline stages and tasks" caption-side="top"} For more information about how to customize stages by using the `.pipeline-config.yaml` file, see [Custom scripts](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-pipelines-custom-customize&format=markdown) and [Pipeline parameters](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-pipeline-parm&format=markdown) lists. ## Running the promotion pipeline {: #cd-devsecops-promotion-pipelinerun} Use the manual promotion trigger to run the promotion pipeline. If the source (master) branch is ahead of the target (prod) branch, the pipeline creates a promotion pull/merge request that you can review and edit. If the source branch is behind the target, the promotion pipeline fails with the `All changes have already been promoted` message. To modify the default values of the promotion pull/merge request, or to promote from an alternative source to target, users can modify the [inputs](#cd-devsecops-promotion-pipelineinputs) from the Pipeline Environment Variables UI. Before you run the continuous deployment pipeline, make sure that the promotion pull/merge request is merged. You can find the pull/merge request URL in the pipeline logs. {: tip} For more information about the inventory and promotion process, see [Inventory promotion](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-inventory&format=markdown). ## Partially promoting inventory items {: #cd-devsecops-promotion-partial-promotion} The partial promotion method allows the promotion pipeline to promote a select subset of available inventory. An inventory entry in this context would be a single file (of the inventory type) present in the inventory repo, this would map to a unique filename on the local filesystem {: important} Using the parameters `inventory-include` and `inventory-exclude` enables the partial promotion method. When using `inventory-include`, the patterns / filenames provided in that environment property resolve to their respective entries and promoted by the pipeline. Similarly, entries provided in `inventory-exclude` get excluded from promotion. The format utilises glob pattern (also supports full paths), similarly to what is followed in the CC-pipeline. For more information about glob patterns, see the [glob](https://man7.org/linux/man-pages/man7/glob.7.html){: external} manual. ### Filtering applied in partial promotion Partial promotion applies two levels of filtering - using the `.inventoryignore` file and applying filtering based on the glob patterns given to `inventory-include` and `inventory-exclude` #### Using the .inventoryignore file To exclude a set of files or folders by default for every partial promotion run as well as CD-pipeline run, you can add the list of files / folders to the `.inventoryignore` file to exclude those entries. The list of available entries (that the pipeline can promote) is available after filtering the entries out from the `.inventoryignore` file. The pipeline searches for the `.inventoryignore` file at the repository's root. If you prefer a different name for the inventory exclusion file, you can specify it by setting the `inventory-ignore-file` key as an environment property within your pipeline. Make sure that this file is at the root of the inventory repository. #### Using the inventory-include parameter The list of entries to promote after filtering the entries provided by the `inventory-include` and / or `inventory-exclude` If both `inventory-include` and `inventory-exclude` are present, `inventory-include` takes precedence, and then `inventory-exclude` excludes items from the subset that is defined by the inclusion list. If one of these variables are supplied, the pipeline will try to resolve the complete paths of the glob patterns or just direct filenames and go ahead with partial promotion. Only the common list of entries between the 2 levels of filtering gets promoted by the pipeline. ### Example usage of inventory-include and inventory-exclude params This section shows examples of using glob patterns and also incorporating them in the `inventory-include` and `inventory-exclude` parameters. Here is an example directory structure for an inventory repository, containing microservices, (nested) configuration files and helm charts. ``` cd-pipeline-deps my-application-plugin-component-config my-application-plugin-component-diagnostic-monitor configuration # directory entry configuration/my-staging-region # directory entry configuration/my-staging-region/environment-1-cluster # directory entry configuration/my-staging-region/environment-1-cluster/serviceA-component_config configuration/my-staging-region/environment-1-cluster/serviceB-system_config configuration/my-staging-region/environment-1-cluster/serviceC-params_config configuration/serviceX-dashboard-setup_helm configuration/serviceY-releases_helm my-application-task-runner my-application-dashboard my-application-dashboard_deployment my-application-module my-application-module_deployment .inventoryignore global_deployment README.md ``` #### To select all sub-module entries of a component `inventory-include` set to : `*plugin-component*` Selected inventory entries : ``` my-application-plugin-component-config my-application-plugin-component-diagnostic-monitor ``` #### To select all the helm charts in a given configuration folder `inventory-include` set to : `configuration/*helm` Selected inventory entries : ``` configuration/serviceX-dashboard-setup_helm configuration/serviceY-releases_helm ``` #### To select all the config files of a particular environment `inventory-include` set to : `configuration/my-staging-region/environment-1-cluster/*_config` Selected inventory entries : ``` configuration/my-staging-region/environment-1-cluster/serviceA-component_config configuration/my-staging-region/environment-1-cluster/serviceB-system_config configuration/my-staging-region/environment-1-cluster/serviceC-params_config ``` #### To select only one component `inventory-include` set to : `my-application-dashboard*` Selected inventory entries : ``` my-application-dashboard my-application-dashboard_deployment ``` #### Using combination of glob patterns in inventory-include `inventory-include` set to : `*plugin-component*,configuration/*helm` Selected inventory entries : ``` my-application-plugin-component-config my-application-plugin-component-diagnostic-monitor configuration/serviceX-dashboard-setup_helm configuration/serviceY-releases_helm ``` #### Using combination of glob patterns in inventory-exclude `inventory-exclude` set to : `configuration/**, my-application-dashboard*` Selected inventory entries : ``` cd-pipeline-deps my-application-plugin-component-config my-application-plugin-component-diagnostic-monitor my-application-task-runner my-application-module my-application-module_deployment .inventoryignore global_deployment ``` ## Promotion pull/merge requests {: #cd-devsecops-promotion-pipelinepr} The information from the body of the promotion pull/merge request is used to create the change request. Files that are changed by the promotion pull/merge request represent the entries, such as images, that are deployed by the continuous deployment pipeline. If the changes were made because of an emergency, the promotion pull/merge request is marked with an emergency label. The change request that is created by the continuous deployment pipeline is also marked as `emergency`. The evidence that is collected in the continuous integration pipeline is summarized and attached to the change request in the continuous deployment pipeline. ## Promotion validation pipeline {: #cd-devsecops-promotion-validation-pipeline} Once a promotion PR is opened, you can optionally perform the evidence aggregation and summary generation in the Promotion validation pipeline, and set the evidence statuses on the promotion pull/merge request (PR). The PR may be created by the Promotion pipeline or manually in the inventory repo. The pipeline enables early validation of the promotion PR before the PR is merged to the target branch (environment). Based on the status of the PR, users can either proceed with the promotion (when all the evidence statuses are green), or choose to fix the problem in the continuous integration pipeline (when the evidence status is red). Additionally the validation pipeline also adds the aggregated summary of evidences for one or more applications in the inventory to the promotion pull/merge request as a comment, in a user-friendly tabular format (as shown in Figure 3). The table provides useful links, such as links to pipeline runs, app repositories, and issues created for each of the applications. By default, each row in the *Detailed evidence status* table corresponds to an application context provided by a source repository used to create artifact(s) referenced in the inventory entries. This application default grouping can be customized based on a group-by value obtained by applying the JSON filter (defined in the property `application-group-by-filter`) on each inventory entry files. {: note} While the validation is in progress, merging of the promotion pull/merge request is blocked. Once the validation pipeline completes, the evidence status is set on the pull/merge request. Clicking on each entry in the status takes the user to the specific stage in the corresponding CI pipeline run. ## Stages and tasks {: #cd-devsecops-promotion-validation-pipeline-stages} The following table lists the tasks run in a Promotion Validation Pipeline. In addition the table also provides an overview of each of these stages: - **Task or Stage**: This refers to the name of the stage as defined within the `.pipeline-config.yaml` configuration file. - **Short description**: This provides a concise explanation of the actions performed during the execution of the stage. - **Customisation permissible**: This indicates whether users have the flexibility to modify or replace the default behavior of the stage by inserting a custom script in the `.pipeline-config.yaml` file. - **Default Reference Implementation**: This indicates whether the DevSecOps pipelines come with a pre-defined or default implementation for the stage. Notably, for certain stages like `unit-tests` or `setup`, the DevSecOps pipeline doesn't offer any out-of-the-box implementation. Instead, users are required to provide custom scripts or code tailored to their application's requirements. - **Evidence Collection**: This indicates whether the stage performs the collection of standard evidence. When DevSecOps Pipeline provide a reference implementation for a stage, evidence collection is performed out-of-the-box. However, if user choose to modify or replace these predefined stages, they must ensure that their custom implementations include appropriate evidence collection. The same responsibility falls on users for stages where the DevSecOps pipeline doesn't provide an out-of-the-box implementation, necessitating them to perform evidence collection. The column indicates the entity (**User/Pipeline**) responsible for carrying out the evidence collection. - **Skip permissible (applicable to version >= v10)**: This indicates whether users can opt out of running this stage by setting the skip property to true in the `.pipeline-config.yaml`. However, caution is advised when using this feature, especially for stages designed to collect evidence. Skipping such stages might lead to missing essential evidences for the build. |Task or stage |Short description |Customisation permissible in `.pipeline-config.yaml` | Default Reference Implementation |Evidence Collection |Skip permissible | |:----------|:------------------------------|:------------------|:------------------|:------------------|:------------------| |`inventory-validation` |Validates the pull request raised for the promotion. |No | Yes | NA | No | |`validation-finish` |Collect and upload log files, artifact, and evidence to the evidence locker. |Yes | No | NA | No | {: caption="Promotion validation pipeline stages and tasks" caption-side="top"} For more information about how to customize stages by using the `.pipeline-config.yaml` file, see [Custom scripts](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-pipelines-custom-customize&format=markdown) and [Pipeline parameters](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-pipeline-parm&format=markdown) lists. ## How to opt-in into promotion validation? {: #cd-devsecops-promotion-validation-pipeline-opt-in} [Deprecated]{: tag-deprecated} The `opt-in-promotion-validation` option that was used to automatically kick-off the promotion validation pipeline on a pull request is `deprecated` in favor of the `Git Promotion Validation trigger`. If you have this property in the environment settings, you will see the deprecation notice in the pipeline logs and Slack notification. ## How to enable promotion validation? {: #cd-devsecops-promotion-validation-pipeline-enable} For all new CD toolchains, Git Promotion Validation trigger is automatically created and set to enabled. {: note} To enable the Git Promotion Validation trigger on an existing pipeline, you can use the following steps. 1. Go to the **Trigger** page of the CD pipeline that you want to add it to. 2. Select **Add > Git Repository** to add a new trigger. 3. Input the following information required for the the trigger: - Provide a trigger name. For example: Git Promotion Validation Trigger. - Specify `promotion-validation-listener or promotion-validation-listener-gitlab` as the `EventListener`. - Select the corresponding inventory repository for the pipeline for the **Repository** field. - Select the name of the target environment for the **Branch**. - Check the box for the field **When a pull request is opened or updated**. 4. Click **Add**. 5. Set the trigger to **On**. ## Inputs {: #cd-devsecops-promotion-pipelineinputs} |Variable |Description |Default value |Required or optional | |:----------|:------------------------------|:------------------|:----------| |source-environment |The source inventory branch of the promotion. |`master` |Required | |target-environment |The target inventory branch of the promotion. |`prod` |Required | |priority |The priority of the change. |`critical`, `high`, `moderate`, `low`, or `planning` |Optional | |assignee |The functional ID or the email of the person to assign the change request to in the Change Request IBM Cloud Organization. |`''` |Optional | |description |The description of the change that is appended to the change request description. |`''` |Optional | |purpose |The reason why the change is required. |`''` |Optional | |impact |More notes about what this change implementation impacts. |`''` |Optional | |inventory-ignore-file |Custom filename for .inventoryignore file, this file contains list of files / folders to ignore on every partial-promotion run. |`.inventoryignore` |Optional | |inventory-include |Inventory entries to selectively promote (partial promotion). |`''` |Optional | |inventory-exclude |Inventory entries to exclude in partial promotion. |`''` |Optional | |backout-plan |The plan that describes how the change is rolled back in a failure. |`''` |Optional | |slack-notifications |The switch to turn the Slack Integration on or off |0 |Optional | |customer-impact |Impact of the change on the customers. |`critical`, `high`, `moderate`, `low`, or `no_impact` |Optional | {: caption="Promotion pipeline inputs" caption-side="top"} ## Outputs and effects {: #cd-devsecops-promotion-pipelineoutputs} * Slack notification * Promotion pull/merge request You must edit and modify the pull/merge request if the optional parameters were not provided. |Variable |Description |Required or optional | |:----------|:------------------|:--------------| |Priority| One of the following values: `Critical`, `High`, `Moderate`, `Low`, `Planning` | Required | |Change Request assignee | The email ID of the assignee. | Required | |Additional Description | The description about the changes in the application. | Optional | |Purpose | The purpose of the changes that are made to the application. | Optional | |Explanation of Impact | The impact of the change to the application behavior or environment. | Optional | |Customer Impact| One of the following values: `Critical`, `High`, `Moderate`, `Low`, `No_Impact` | Required | |Deployment Impact| One of the following values: `Small`, `Large` | Required | |Backout Plan | The steps to back out if the deployment fails. | Optional | {: caption="Table 2.Optional parameters" caption-side="top"} ![Promotion pull and merge request](images/promotion-pr.png){: caption="Promotion pull and merge request" caption-side="bottom"} When the (optional) promotion PR validation runs, the evidence status is set on the pull/merge request. ![Optional evidence status set on promotion pull and merge request](images/promotion-pull-request-status.png){: caption="Evidence status on promotion pull and merge request" caption-side="bottom"} The aggregated evidence summary of the evidences (that can be coming from multiple apps in the inventory) is displayed in tabular format as a comment in the PR. ![Optional aggregated evidence summary captured in a comment on promotion pull and merge request](images/promotion-pull-request-summary.png){: caption="Aggregated evidence summary in promotion pull and merge request" caption-side="bottom"} ## Next step {: #devsecops-promotion-pipeline-next} After the Promotion Pipeline finishes successfully, you can [proceed to the CD Pipeline](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-cd-pipeline-overview&format=markdown).