Branch Management Application in Copado V9 & Over.

Updated 5 months ago by Iván Minaya

Branch Management Application in Copado V9 & Over. 

Branch Management takes a predefined deployment flow and allows for the changes that are tracked in Git for the various branches, to be merged, validated in Git, and then validated in Salesforce before performing a deployment that deploys such changes to the next (or previous) org within the deployment flow and merges the branch information; thereby ensuring that Git and Salesforce remain in sync.

  • User Stories Ahead: 
    • Copado CBM allows you to create a deployment from the selected environment onto the next environment filtering by User Stories:
      • Click the Promote button in the source environment.
      • Select the Project or Release. 
      • Select the required User Stories to Promote. 
      • Click “Create Promotion & Deploy”. 
  • User Stories Behind: 
    • Copado CBM allows you to create a deployment from the higher environment onto the lower one filtering by User Stories:
      • Click the Back Promote button in the destination environment.
      • Select the Project or Release.
      • Select the required User Stories to Back Promote. 
      • Click “Create Back Promotion & Deploy”.
You can add, remove and reorder the User Story columns by editing the "CBM Fields" Field Set in the User Story object.
  • Commits Ahead or Commits Behind: 
    • Copado allows you to sync to the higher and lower environments based on the Git Commits of the Branch. 
    • If you are promoting user stories to higher environments, its advised to only be back promoting to lower environments instead of Sync.
    • Back Sync should only be used by those who Sync to higher environments as well. Basically, CBM only users.
  • Deployment Errors: 
    • If Copado detects any error in the Validation Deployment Deployment Errors will be shown, and Sync won’t be allowed.
  • File Differences: 
    • From the File Differences CBM tab, you can view the Update, Create and Delete differences between the files to Sync. (more information)

Canvas Features:

  • Infinite Canvas:
    • Manage as many environment as desired with our infinite extendable canvas.
  • Enable Canvas Guidelines:
    • For a perfect alignment and a geometrical order sensation, you can enable the canvas guidelines by clicking the eye icon. 

With Branch Management set up using webhooks from your Git Repository, Branch Management will continuously check for changes and perform a validation deployment of the merged changes.

Copado V8 Interface  & Under

Note: The following Setup instructions and how it works also applies to v9 & up versions as well.


How does it work?

The deployment flow (with Git repository and branch information) is set up within Copado. A Copado webhook is also added to your Git repository. Every time a commit is received by the Git repository, the commit information is sent to Copado where the following will occur:

  1. The Git repository is retrieved and the branch divergence will be calculated (commits ahead and behind)
  2. A local merge (ahead) or pull (behind) of the diverged commits will be attempted between a branch (e.g. Dev2) and its parent branch (in this case Staging). 
  3. If the merge succeeds, a validation only deployment is created of the MERGED content (e.g. validation deployment into the Dev1 org). 
  4. If the merge fails, the error information is displayed to the user.
  5. The user will be able to see if the validation deployment succeeded or failed (and its errors).
  6. The differences, between branches, of the affected files will be available to be compared.
  7. If the validation deployment was successful, the user can choose to perform a sync (e.g. Staging content into Dev1). If the "Sync" button is clicked, the deployment is executed (Staging content into the Dev1 org) and ONLY IF SUCCESSFUL, then the Staging commit is merged into the destination branch (e.g. Dev1) and the changes are pushed to your Git repository

Best Practices tip

Always sync back to lower environments before pushing to production, or once deployment has been done to production, no new User Story feature branch can be created until its environment has been synced.
This is to prevent the feature branch inheriting the latest changes to Production into the feature and orgs branch without having actually synced them.

How to set it up?


  1. 1 Git Repository
  2. For each environment within your Deployment Flow, 1 branch must be created within your Git repository. Note that branch names are case sensitive
  3. All branches must start in sync, all in the same commit Id, which will be the common starting point. When creating new branches. all branches must be created from the same "master" branch.

Setup steps

  1. Make sure you have CBM enabled from the Account Summary tab
  2. Create the org credentials that will be part of the Deployment Flow
  3. Rename environments (It is strongly recommended to rename the Environments equal to the branch names)
  4. Add the Branch Management Permissions to each environment. Make sure the related list is included in the Environment layout
  5. Create an new empty git repository on your git server
  6. Create .gitignore file on the master branch (this should be the first file of the repo)
  7. #package.xml file is recreated on the fly by Copado, no need to track
              #unnecessary changes of this file
              #Managed packages can trigger the installation or uninstallation of 
              #applications, it is recommended to manage this outside git
              #if you are not customizing a managed package, you can keep your 
              #repository clean by ignoring all files for that package. 
              #For example, to ignore all files of the "Copado" managed package
              #just add to your .gitignore file the following text: *copado__*
              #if you will be customizing managed packages, make sure that the 
              #same version of the package is installed on all your environments 
              #so that deployments will only update existing managed components. 
              #Creation of managed components is not permitted by the API.
              #It is recommended that you ignore managed components that cannot be 
              #modified since there is no need to track them in Git, 
              #like for example:
              # classes/copado__*
              # triggers/copado__*
              # pages/copado__*
              #profiles and permission sets are complex Files. If your Org's 
              #metadata and Git are in sync, you can track incremental changes on 
              #Profiles and Permission sets using Copado "commit files" functionality.
              #Otherwise ignore profiles and permission sets until you are ready for it. 
              #You can deploy profiles and permission sets using 
              #Copado Deployer steps: Full profiles and Full Permission sets.
              # Below is how to ignore them
              # profiles/*
              # permissionsets/*
              #Translations are complex since get updated indirectly across
              #multiple files, they can make a deployment fail if a field is 
              #translated in source and it doesn't exist on destination. 
              #If you are committing incrementally new fields and new Translations
              #you can track them in Git, just be careful. 
              #If you choose  to ignore them in Git, you can always create a deployment
              #with the Copado Deployer "Translation" Step. 
              # translations/*
              # objectTranslations/*
              #Sites which has Domain mapping has environment specific information. 
              #Make sure you setup Copado Environment Variables to make sites config
              #files environment agnostic.
              #Until the above is achieved, you can ignore them as follows
              # sites/*
              # siteDotComSites/*
  8. Create a git repository in Copado that connect to the one created in a previous step
  9. Create deployment flow (including repository and main branch) Make sure those 2 fields are included on the Layout
  10. Using the Flow editor, add all the deployment steps by setting the destination org and then the branch
  11. Create a snapshots for each Org -> branch (without running them yet)
    1. For master branch, set permissions to "Allow Snapshots and Commits"
    2. For all the other branches, set permissions to "Allow Commits Only"
  12. Initialize the master branch by running the git snapshot for the master branch
  13. On the git server, create all the branches based on the master branch
  14. Edit the Snapshot for the master branch and set permissions to "Allow Commits Only".
  15. From the deployment flow, go to "manage branches" and press the Recalculate button, all branches should be displayed in Sync after the recalculation.
  16. You are all set, now you can start creating commits and into the different branches and Copado will do its magic.

Be mindful of what you commit into Git. Is better to have many small commits with a proper commit message than committing a bunch of files. Committing all files in bulk is not a good practice and will only lead to conflicts and deployment issues.

In case you have committed some files by mistake, here is a quick tip on how to undo the changes in Git.

git reset HEAD~n
          git push -f origin branch

Replace "n" with the number of commits to undo. Replace "origin" with the right remote name, and replace "branch" with the right branch name.

If git command line is not an alternative, you could achieve the same using a GUI such us SourceTree 

Connect your git repository, please follow SourceTree instructions for that.

The following screenshot shows the master and dev branch. Let's assume that the latest commit on the master branch was committed by mistake and you need to revert it.

By doing right click on the "unwanted commit", select "reverse commit"

This will create a new commit which is the new status.
Now you just need to push the new commit. Use the Push icon on the toolbar and confirm the action.

Finally your repository will look similar to this.

Best Practices Validations

As from Copado v7, we have enabled the following validations:

  • All Flow Steps must have a branch
  • All Flow Steps must have Source and Destination
  • There are no duplicated branches on the steps
  • There are no duplicated Source environments
  • Enforce Branch/Environment naming convention. If set to true, the Branch and the Source environment must be equals (case sensitive). Eg. Environment name "UAT"  vs. Branch name "UAT".

This validations only apply for CBM flows, if a repository and main branch have been set.
For CCM flows, the validations do not apply.
Please, notice that the UI for the flow is changed. Now it's read only, so all management in your flow has to be done in the Deployment Flow Steps related list to help enforce this Best Practices.

How to use it

If you have a CBM deployment flow, this validations will be available once you upgrade to Copado v7.
If you want to disable this Best Practices enforcement, you can turn off the validations by setting the "Disable Validations" checkbox to true.
If you want to enforce the naming convention between Environments and Branches, you have to set the "Enforce branch/env naming convention" checkbox to true.
Validations will apply when you try to activate a CBM flow, when you try to edit an active CBM flow, or when you create or edit a deployment flow step in an active CBM flow.

How did we do?