Copado Quick Start - ​Version ​Control & User Stories

Updated 4 days ago by David Venegas

This guide is a series of steps to quickly set up Copado with version control and user stories. It is not a full explanation, so please refer to the the links provided for more information.

Base setup

  1. Install Copado from the AppExchange
    • Enable/whitelist the Copado IP Addresses in your Salesforce Network Settings if there are IP restrictions to allow Copado to access your Salesforce Org.
  2. Add users to the Copado Package by going to Setup → Installed Packages
  3. Assign Copado licenses to each user through the Copado License Manager.
  4. Create an Org Credential record for each user that will work with Copado. An Org Credential represents the permission for Copado to access an org as a certain user.
    These Org Credentials must be authenticated with the users of the Org where Copado is installed.
  5. Create an API Key for your user to enable the Webhooks functionality for e.g. scheduling Copado jobs or allow for custom automation of actions.
  6. If required, set up the Sandbox Environments you will connect to Copado (Sandboxes / Developer / Production Orgs for e.g. dev1, dev2, int, uat) and then create Org Credentials for each of the Orgs. When setting OAuth, sign in with the corresponding user of each Org.

Git Repository and the main Release Flow.

  1. Create a new repository in your Git version control provider (e.g. Github, Bitbucket, GitLab, others).
  2. Commit the example .gitignore file in the master branch to avoid tracking unnecessary files and thus keeping your branches with only necessary files.
  3. Link Copado to your Git Repository

    • If your Git Repository is behind a firewall you will need to whitelist the Copado IP Addresses.
    • It is recommended that developers and admins working with Copado have access to the Git Repository to review their changes and see who modified specific lines of code or configuration files
  4. Create a Git Snapshot for the production Org with the master branch.
    A Git Snapshot links an Org to a GIT branch of your Git Repository, in order to perform actions, such as backups, commit to the branch, or commit metadata changes via a User Story.
    The User Story’s Org Credential will determine which Git Snapshot will be used for the commit. 
  5. Follow the Salesforce Git Trailhead for more information on Version Control.
  6. Click “Create Snapshot Now” in the Git Snapshot record that links the production Org to the master branch of your Git Repository. All the metadata components of the Org, which are not mentioned in the .gitignore file, will be committed to the branch.
  7. Once the Snapshot is finished, verify in your Git Repository that the metadata components have been committed in the master branch. Then create new branches out of the master branch that correspond to each of the other Orgs (e.g. dev1, int, uat).
  8. In Copado, create the Git Snapshot records for each other Org with their corresponding branch and Org Credential. Branch names are case sensitive, so make sure to check that the branch name in git is the same as on the Snapshot in Copado.
      • Consider creating a Release Management user in each Org that has access to all the metadata. Link each Git Snapshot record to the Org Credential of the Release Management user
      • Users that will be committing in user stories need access to a Git Snapshot record linked to an Org Credential linked to the same Environment of the user story. If they do not have access to this Git Snapshot, you must share the Org Credential record with them so they have access to the Git Snapshot
  9. Create a Deployment Flow. Select the Git Repository record and the main branch to track all metadata changes in Git. The main branch is usually master, from which the User Story feature branches will be created.
  10. Create Deployment Flow Steps to connect the different Orgs of the deployment flow. For each step select the source and destination environment and type the branch related to the source environment.
  11. In the Deployment flow click ''Manage Branches'' and then click ''Recalculate''. All Environments will be marked as In Sync, since the branches in Git have been created from master and there are no committed changes yet.
      • When first implementing Branch Management your branches are "In Sync" between each other but not in sync with their corresponding Org. You either have to refresh your Sandboxes to be in sync with the Git branches or you will have to gradually resolve the differences, more details here

Change Management & first Deployment

  1. Create a Project and select the Main Release Flow as the project’s Deployment Flow. The project allows you to group user stories, sprints and releases. User stories that belong to the project will be deployed following the Org path of the deployment flow.
  2. Create a User Story linked to an Org Credential of one of the lower environments of the deployment flow. The user story in Copado allows you to track, commit, test and deploy metadata for specific business requirements.
  3. In the user story click ''Commit Changes'' and select some metadata components that have been recently modified and that have not been deployed yet. (If you do not find newly created metadata, click the Refresh Cache link). Then click “Commit Changes” and when finished you are redirected to the user story.
  4. The “User Story Selections” section of the user story layout displays the list of the committed metadata components. For a commit to be successful, the committed metadata must have changes.
  5. Check the "Promote and Deploy" checkbox in the user story. Copado will create a promotion record and deploy the user story metadata to the target environment. Scroll to the User Story promotions related list. Click on the promotion name to open the Promotion page.
  6. The destination environment of the promotion is defined based on the deployment flow of the project. In the Deployments related list, you will find the deployment of the metadata.
    1. See here for more details on promotions and how promotion branches work.
    2. Once the deployment is successful the environment of the User Story is changed to the Promotion destination environment and the Promote and Deploy checkbox is unchecked.
  7. Repeat “Promote and Deploy” process to deploy the user story to Production.

How did we do?