Copado Rollback

Updated 1 week ago by Copado Solutions


This is a Beta feature. We look forward to receiving your feedback based on your experience using this feature. To do this, you can head to our community group or use one of the quick links in the Rollback Deployment Step or the Wizard summary itself.

By following Copado's best practices in your release process, you will be able to identify issues with your metadata changes as they are being deployed from one environment to the next one. While enforcing quality gates, you will be able to catch the issues before the changes arrive to production. Hence, the probability of errors in production should be reduced significantly.

However, we understand that there might be cases that require that you perform a rollback of the changes that got deployed.

This is where Copado provides you with a simple rollback mechanism that gives you the ability to quickly compare and select only those changes that you want to rollback. This rollback feature supports Salesforce metadata items (including nested components) as well as Vlocity components.


To start using the rollback functionality, you will need to meet the following prerequisites:

  • Enable the rollback feature (you will find information about how to do this in the “Enable the Rollback Support” section of this article).
  • Assign the “Admin” or “User” licenses.
  • Assign the “Copado User” permission set.

Scopes and Supported Capabilities

In Scope

Out of Scope

  • Git Promotion and Delete Metadata steps 
  • Revert selective metadata changes
  • Rollback updates, additions and deletions in a single step
  • Rollback nested metadata items such as Custom Fields or Record Types
  • Rollback Vlocity components
  • Commit metadata in the destination branch to reconcile changes with Git 
  • Configure Apex Test levels for the rollback deployment
  • Perform validation deployments
  • Add additional steps before/after deployment
  • Deployments with Multi-Destination orgs
  • Metadata dependency notifications and warnings
  • DX Source Format
  • Comparisons of Vlocity items (Preview option instead)
  • Vlocity deletions (unsupported by Vlocity Build Tool)
  • Other deployment step types like Git Metadata and Metadata 

Enable the Rollback Support

Rollbacks are not enabled by default. To enable this feature, follow the steps below:

  1. Go to the Environment tab.
  2. Select the destination Environment record to which the changes are promoted or deployed.
  3. Go to the Rollback section and check Enable Rollback.
    For example, if you enable this for the Staging environment, the Rollback option will be available whenever there is a promotion or deployment done in this environment.
If you cannot find the Enable Rollback checkbox in the lightning page, please make sure that the environment Platform field is set to “Salesforce”. Additionally, if you are using Salesforce Classic, make sure the Enable Rollback field is added to your layout.

We recommend you to enable this option only in business-critical environments to minimize the amount of storage consumed and the time deployments may take when taking the backup.

It is important to note that, when you enable the Rollback option, the feature will be available only for the new promotions and deployments created after Rollback has been enabled, and not for the previous ones.

Rollback Process

As soon as a deployment takes place in an environment, two types of files are created for each of the two steps—Git Promotion and Delete Metadata:

  • Rollback_index.json: This file contains the list of metadata involved in this deployment step which will be used during the rollback process.
  • This is a backup of the metadata before the deployment took place. This backup will be used as the source of truth for the rollback.

You can initiate the Rollback process after a successful promotion to an environment where Rollback is enabled. Here are the steps to follow:

  1. Go to the Promotion record and click Rollback (beta) to launch the Rollback wizard.
  1. On this screen you will see all the steps that can be rolled back. They have the Step Available checkbox checked.
In case more steps are added to the deployment process, they will be listed on this screen. The Step Available checkbox will be unchecked if they cannot be rolled back (see “Scopes and Supported Capabilities” section).
  1. Click Next.
  2. In the Select and Compare Metadata screen, you will get an option to keep only the metadata that you want to be rolled back. By default all are selected. This table indicates the actions to be performed by the rollback (left) based on the original actions implemented in the environment (right).


Original Action 



Update (Undo the change)

Update (Change made)



  1. Click Compare to compare the metadata versions before and after the rollback is performed.
Vlocity components will have a preview option instead to see the original component version coming from the backup, but not the version currently available in the destination.
  1. Click View Differences to view the differences between the backup version and the environment version after the rollback is done.

This step enables you to make an informed decision whether you want to rollback the changes.

  1. Once you are comfortable with your selections, click Confirm Metadata.
  2. In the Deployment Overview screen, you have an option to select the necessary test level for your Rollback deployment.
    1. No Test Run: The default Salesforce test level will be applied (no test for non-production orgs, All Local Tests for production orgs).
    2. Run Specified Tests: Use the Add Tests Classes button to select the test classes to execute. Once confirmed, those will be added to the list and  the Test Only option will be checked to indicate that they will be used only for test coverage purposes.
    3. Run Local Tests: All tests in your org are run, except the ones that originate from installed managed packages. 
    4. Run All Tests in Org: All tests in your org are run, including tests of managed packages.
  3. Now that you have completed all the tasks, you can click one of the available buttons according to your requirement:




Go to the previous screen.

Save and Close

Exit the rollback wizard. When you launch the wizard again, you will be taken to the screen where you can complete the process.

Validate Deployment

Executes a validation deployment for the rollback.

Add Pre and Post Steps

Go to the Deployment screen, where you will see the Rollback step in the Step section and you can click on Add Step to add Pre and Post deployment steps.

Save your changes and click on Deploy to launch the deployment screen. Here click on Deploy All to execute your rollback deployment.The Deployment status screen is displayed where the deployment type is mentioned as Rollback. This screen indicates that the rollback has been completed successfully.

You can click on Return to Wizard to go back to the wizard screen.

Start Deployment

Initiate the rollback deployment.

  1. The next step in the Rollback process is validation. Click on Validate Deployment.
  2. To start the rollback, click Start Deployment.
  3. After the deployment is complete, Copado will perform the following actions:
    1. A commit with message RollBack Step commit: <deploymentJob.stepId> will be made against the destination branch to reconcile changes with the version control.
    Example: RollBack Step commit: a165p0000071SbFAAW
    1. The Is Rolled Back? field in the Promotion record will be updated to indicate this Promotion has steps that have been rolled back.
    2. The rollback Deployment will be related to the Promotion record.
    3. The rollback Deployment will be related to the original Deployment record.
  4. A Rollback step is created in the rollback Deployment. In order to review the changes that have been rolled back, you can access the step and click on Return To Wizard.

Moreover, in the rollback summary page and in the Rollback step we have provided a feedback option for you to share your thoughts with us. This will help us further improve this feature.


Once the rollback process is completed, you can expect the following results:

  • The selected changes are reverted.
  • The selected new items are deleted.
  • The selected deleted items are re-created.
  • There is a commit in the destination branch to reconcile changes.
  • The rollback Deployment will be related to the Promotion record.
  • The rollback Deployment will be related to the original Deployment record.

Original action performed in the Environment

Reverse action performed during a Rollback




Update (undo the change)



Additional Considerations & Best Practices

  • Rolling back metadata components may affect any data records related to them. For example, if you rollback a new field that has been created in the last deployment and delete it, all the related data that has been populated between the deployment and the rollback will be lost. In certain situations, depending on your project, the metadata affected and the impact of the issue that you are experiencing as part of your last deployment, a roll-over​ strategy may be more convenient than a rollback​ strategy. There are 2 approaches to do a roll-over:
    • Create a new “Bug” user story, commit your fixes and deploy them to Production. 
    • If you can quickly identify the user story that caused the issue, you can change its credential and bring it back to a lower environment where you can do your fixes, re-commit them and then deploy to Production. 
      • Both approaches will enable you to enforce any Quality Gates present in your pipeline or any approvals that need to be run.
      • We highly recommend you to add an additional HotFix environment that is an exact copy of your Production environment (you can use back-promotions to keep it up to date), which you can use for these kinds of emergency situations. 
  • Depending on the number and size of the deployments in the pipeline, rollbacks can consume a significant amount of storage. The script below is set to delete the rollback backup files that were created more than 60 days before and that belong to those deployment steps with status 'Completed Successfully', 'Cancelled' or 'Completed with Errors'. If you want to change these conditions, you can:
    • Change the statuses (eligibleStatuses) in the first line of the script, removing the existing ones or adding others.
    • Change the query “WHERE” condition to be more specific about which deployments’ files you want to clean up.
    List<String> eligibleStatuses = new List<String>{ 'Completed Successfully', 'Cancelled', 'Completed with Errors' };

    List<copado__Step__c> steps = [

        (SELECT Id, ContentDocumentId FROM ContentDocumentLinks WHERE ContentDocument.Title = 'Rollback')


      copado__Deployment__r.LastModifiedDate < LAST_N_DAYS:60 AND 
      copado__Deployment__r.copado__Status__c IN :eligibleStatuses

    Set<Id> cdIds = new Set<Id>();

    for (copado__Step__c step : steps) {
     if (!step.ContentDocumentLinks.isEmpty()) {
      for (ContentDocumentLink cdl : step.ContentDocumentLinks) {

    if (!cdIds.isEmpty()) {
     delete [SELECT Id FROM ContentDocument WHERE Id IN :cdIds];
  • When rollbacks are enabled, deployments might take more time to be completed since a backup needs to be taken.
  • You can also export the rollback package ZIP file by selecting the Attach Deployment File checkbox in your rollback deployment. Refer to the Troubleshooting a Deployment article for more information.

How did we do?