Updated 3 weeks ago by Copado Solutions

As user stories are worked on, Metadata and Git Commits may be added to the user story. Once a user story is ready for deployment, the user story can be flagged as, “Ready for Promotion”. This means that the User Story may be deployed from one environment to the next as defined by the project’s  deployment flow. A promotion is therefore a deployment of multiple user stories from one to another, following a designated deployment flow.

It's possible to create Promotion for User Stories belonging to a Project or User Stories belonging to a Release regardless of the project. Promote a Release is available since Copado v5.2.

  • To create a Promotion click on the “Promotions” tab and press the “New” button.
  • Select the Project or the Release, and a Source Environment. Copado will automatically fill the source Org Credential, Destination Environment and destination Org Credential based on the Deployment Flow related to the Project/Project's Release and the available credential owned by the running user. As from Copado v6. If an Org Credential is marked as "Default Credential" the promotion will use that credential regardless of the Owner. This allows sharing 1 "deployment" Org credential between multiple release managers.
  • The checkboxes, Create Full Permission Sets Step and Full Profiles Step will respectively detect if Permission Sets or Profiles were added to the metadata in User Stories.
  • Manual Steps that were specified against a User Story will also be added to the deployment.
  • User Story Commits:
    • Git Metadata step will be added if commits were selected against the user stories when using CCM without CBM.
    • Git Promotion step will be added if commits were selected against the user stories when using CCM with CBM.
  • Delete Metadata step will be added if files were deleted within the git commits.

Note: when using the "Promote and Deploy" checkbox, e.g. as part of an Approval Process, Copado will trigger the creation and execution of a new Promotion for the approved User Story.


User story commits must be in the same repository. 

CCM stand alone: When doing a promotion, Copado will create 1 single Git MetaData step, that will contain only committed files within the user story commits, and it will use the latest commit as the source of the deployment.
CCM + CBM: When doing a promotion, Copado will create one single Git Promotion step. A new promotion branch will be created out of the target org branch and call it promotion/{}, once created, Copado will merge every feature branch for each promoted User Story.  Note that in this scenario, when committing files from the User Story, copado will create automatically a Feature branch feature/{} behind the scene, these feature branches will be merged into the promotion branch.

When pressing the "Create Deployment" button a menu will appear requesting the user to confirm the deployment options. If the user sets the deployment option "Validation Only" to 'checked', the deployment steps will be set as "Check Only". The User Story selections will remain unaffected.

Once the deployment has completed successfully, the User Stories against the Promotion to which the Deployment is linked will be moved to the next Environment in the Deployment Flow. The checkbox on the User Story object called, “Promote Change” will be unchecked and also the "Promote and Deploy" checkbox. Bear in mind that check-only  (validation deployments) will not cause any update on the user stories.

CCM + CBM: promotion branch will be automatically merged into the target branch, which is the branch related to the target Org on the CBM deployment flow. If the Deployment name contains :tag=x.y.z Copado will create and push a Tag x.y.z. Tags cannot be duplicated, so typically the tag is added when deploying to Production and merging into master.

When creating a "Validation Only" deployment, deployment tasks against the User Stories as well as Full Profile and Full Permission Set steps will not be created.

Shallow fetch depth in Git can be configured by the user through adding @gitDepth=XXX to the name of the deployment record created from the Promotion, where XXX is the depth of the history of commits that are used. e.g:


IMPORTANT: @gitDepth is case sensitive.

Test Level deploy options

  • No Test Run (not apex test are run unless is a production deployment)
  • Run Specified Tests (only included apex test classes will run, aka Fast Deploy)
  • Run Local Tests (all apex test classes excluding managed packages)
  • Run All Tests In Org (all apex test classes including managed packages)

More information regarding  Test Levels


  • Having Git conflicts while promoting  User Stories. This happens when the feature branch  cannot be merged into the Promotion's branch. You will need merge the branches and resolve conflicts outside of Copado. If you are using Github, by creating a pull request, using the Promotion branch as the base and merge the feature branch into it,  you will be able to do it 100%  online via the web user interface. Once the merge is done, create the promotion deployment again using the exact same Deployment name, this way Copado will reuse the same promotion branch where conflicts are resolved.

Promote User Stories from Multiple Projects

  1. Make sure all projects are linked to the same deployment flow
  2. Create a Release record linked to one of the projects
  3. Link all user stories to the Release
  4. Create a promotion record and select the Release
  5. The user stories linked to the Release will be listed in the Promotion page
  6. Continue the usual promotion process by selecting the user stories to promote and then creating the deployment

Customization with Field Sets

As from Copado v7, you have new Field Sets available so you can customize the information shown in the User Stories related list on the Promotions, and in the Promotions Edit view (notice the Detail view of Promotions are handled by the standard layout).
There's a new field in the User Stories related list in the Promotions with an icon in which you can click to open and view the User Stories.

Promotion Selenium Tests

As of Copado v8.0, the Promotion page displays the Regression Tests of the source and destination Environment, as well as the User Story Tests linked to the selected user stories of the promotion. The test results will be displayed in the Selenium Test Results Summary section, and also in the Promotion Selenium Tests related list.

In the Promotion Selenium Tests related list:

  • By clicking the "Run source regression", all the Regression Tests of the source Environment will be run.
  • By clicking the "Run destination regression", all the Regression Tests of the destination Environment will be run.
  • By clicking the "Run source user story", all the User Story Tests of the source Environment will be run.
  • By clicking the "Run destination user story", all the User Story Tests of the destination Environment will be run.

Summary of overlapped metadata on the Promotion

As of Copado v9.0, the Promotion page displays a new related list where the User Story Metadata Index records appear. This allows you to review if there are potential conflicts between your metadata items and also know which metadata was Auto-resolved by Copado when the feature branches of the user stories being promoted were merged into the promotion branch.

The Search box allows users to search by in Metadata, User Story, Status and Last Modified Date fields.

The promotion will mark the User Story Metadata item as Auto-resolved in the Status field if there was a conflict, otherwise, the merge was a Git Merge.

The column with the merge result is only available once the promotion deployment has been created, the 2 possible values for the overlapped items are "Git merged" with a Git icon and "Auto-resolved" with a Copado icon. The higher number will be displayed in Green and all the other ones in Gray.

For more information, read  User Story - Metadata Index entry.

Back Promotion

As from Copado v9 you can promote user stories from the higher environments back to the lower environments by creating a Back Promotion.

When creating a new Promotion from the Promotion tab a “Back Promotion” checkbox will be shown. When checked, the Source Environment field switches to Destination Environment. Copado will infer the source Environment based on the Deployment Flow of the selected Project or Release and will create a Promotion onto the selected destination.

Mass Back Promotion

By clicking on the Mass Back Promotion button,  You can choose Source Org and Project / Release. Copado will display candidates Environments and User Stories and allow you to Back Promote them massively.

In order to Mass Back Promote User Stories into your lower Environments, Follow this Steps:

  1. On Manage Branches Page, choose The Source Environment. This is the environment that holds the User Stories that are going to be back promoted.
  2. Choose the Project or Release.
  3. Select the User Stories to Back Promote and the destination Environment.
  4. Click "Create Back Promotion" or "Create Back Promotion & Deploy".

Whenever you choose a Source Environment and Project / Release, Copado Smart Candidates Algorithm will show the Environments with candidates User Stories to Back Promote. Locked Environments Means rather the User Story Originated on that Environment or has already been back promoted. 

Multiple-Source Mass Back Promotion 
If you need to create a mass back promotion from different source environments,  follow the regular mass back promotion steps, and "Create Back Promotion". From the "Created Back Promotions". "Click on Prepare Another Promotion" and Repeat the process. 

When you Deploy Back Promotions, a Deployment Status will be displayed, With the deployment status information. 

User Stories Ahead and Behind

As from Copado v9, the User Story page is provided with User Stories Ahead and Behind information within the Flow Bar. 

  • User Stories Ahead:
    • Git Committed User Stories seating in the current Environment, and that have not been Promoted to the next environment. 
  • User Stories Behind: 
    • User Stories Promoted to the next Environment through a different stream of work, that have not been Back Promoted to the Environment of the current User Story being Displayed. 

In order to display User Stories Ahead and Behind, click the toggle on the left side of the Flow Bar. 

As of Copado v11, when a back promotion impacts metadata listed in your User Story, your conflicting User Story metadata will be updated to "Back Promoted", and a warning will appear on top of the screen.

When a back promotion impacts metadata listed in your User Story, your conflicting User Story metadata will be updated to "Back Promoted", and a warning will appear on top of the screen. Note: User Stories are considered ahead from the next environment as soon they have a Complete Git Commit, External CI Job or Deployment Task

How did we do?