Best Practice Recommendations for Copado Credentials and Environment Snapshots

Updated 1 month ago by Copado Solutions

Credential Overview

First and foremost, please make sure you review the Credential Overview article.

Keep in mind that each Copado Admin, Copado User or Copado Guest should have one Credential for the Production Org where Copado is installed. This ensures that their Salesforce User, in the Org where Copado is installed, is a valid and authenticated user for Copado.

Out-of-the-box, credentials are private in the Salesforce Sharing Model, and the Copado best practice recommendation is to never change this setting.

Create a Credential

It is necessary to create a credential for the Org where Copado is installed. To do so, please follow the instructions provided in the How to Create a Credential article.

Default/Shared Credentials

Copado offers the possibility to create default/shared Credentials for your sandboxes. Please review the following articles to understand the possibilities that these credentials offer:

  1. Should All Users Have Their Own Org Credential?
  2. Default Credential
  3. Sharing Credentials

Credential Share Read vs Read/Write

It is important to understand the impact of credential share read vs read/write. When sharing credentials, you can determine the level of access that users will have to a record. In the case of credentials, apart from being able to read or modify the fields on the Credential record, users will be able to perform the following operations depending on the level of access:

  • No sharing: No access.
  • Default Credential checked AND Share set to Read: Users can deploy to a particular environment.
  • Default Credential checked AND Share set to Read/Write: Users can commit from or deploy to a particular environment.
  • Default Credential unchecked AND Share set to Read: Users can read the credential, but cannot use it for deployments or commits.
  • Default Credential unchecked AND Share set to Read/Write: Users can commit from a particular org, but cannot deploy to it. Please avoid this setup if possible.

Copado Integration User

It is important to note that the Copado integration user does not need to be an Active user in the Production Org where Copado is installed. Typically, Copado recommends that the Git Repository integration and any additional integrations, such as ALM (JIRA/ADO), are authenticated using a real-named User. In order to ensure full Copado Setup functionality, this named user is also going to be a User with the Copado Admin license.

On the other hand, the Copado Integration User will be an unnamed user whose credentials, for sandboxes only, can be marked as a Default Credential for each sandbox environment and shared to public groups of Copado Admin-licensed and Copado User-licensed users for the sole purpose of streamlining commits, User Story credential updates and promotions/deployments throughout the lower environments of the pipeline.

Typical setup recommendation for the Copado Integration User in the Production Org where Copado is Installed is:

  1. Salesforce User with a generic name such as “Copado Integration”.
  2. Salesforce native System Administrator Profile.
  3. If your Org has user roles implemented, select the highest role in the hierarchy.
  4. The User should be Inactive in Production.

Since the Copado Integration User is not a real-named user, there is no need for it to be Active in the Production Org where Copado is installed, nor any reason for this user to consume Production licenses for Salesforce or Copado.

The reason why Copado recommends the Copado Integration User be created as an Inactive user in the Production Org where Copado is installed is that, when sandboxes are created/refreshed from Production, the Copado Integration User only has to be updated to be Active in the sandbox, and then its credential can be authenticated for the new/refreshed sandbox.

Pipeline Permissions

Sample pipeline, for visual context:

For most of our Copado customer and partner teams’ DevOps Standard Operating Procedures (SOPs), the majority of Developers and Declarative Admins are allowed to promote/deploy their own metadata changes to the DevMerge and QA Sandboxes, but, typically only a limited number of Developers/Declarative Admins and/or Release Managers are allowed to promote/deploy their own metadata changes to the UAT sandbox or commit their own metadata changes from a Hotfix sandbox.

Select and Implement your Sandbox Credential-and-Snapshot Strategy

Regardless of which model you chose, there should always be a 1:1 pairing of credential to Git Snapshot record for each environment in the pipeline. Select and implement either Model I or Model II.

Model I - Default “Copado Integration” Credentials with Tiered Sharing

If you want to follow the Model I (Default "Copado Integration" credentials with tiered sharing), please follow the instructions provided below:

Sandbox Credentials and Snapshots:

Keep in mind that all DevOps team members with the Copado Admin or the Copado User license have permission to commit from and promote/deploy to sandboxes. If you want to use credentials and snapshots for a sandbox, please complete the following steps:

  1. Create two public groups in Salesforce Setup: "Developers" and "Release Managers":
    1. From our example above, we would add those Developers / Declarative Admins who, per your SOPs, are only allowed to promote/deploy as high as the “QA” sandbox to “Developers”.
    2. From example above, we would add those Developers / Declarative Admins who, per your SOPs, are allowed to promote/deploy to all sandboxes up to and including the “UAT” sandbox and are also allowed to commit changes from the “Hotfix” sandbox to “Release Managers”.
  2. Create and authenticate a “Copado Integration” credential for each sandbox in the pipeline:
    1. Make sure the Copado Integration User is active in each sandbox and is on the native System Administrator profile to ensure unfettered access to all metadata in the sandbox.
    2. Make sure to create and authenticate the “Copado Integration” credentials while logged in as a Copado Admin-licensed user; that person needs only to know the Copado Integration user’s Salesforce username and password for each sandbox to which you are authenticating.
    3. Once the credential has been successfully authenticated, edit the credential and append the string “-Copado Integration” to the end of the credential name. For example: Dev1-Copado Integration.
  3. Once each “Copado Integration” credential has been authenticated successfully, flag it as the Default Credential for that environment in your pipeline.
In order for Copado to work as expected, there should only be one credential flagged as a Default Credential per Copado environment record.
  1. Once each “Copado Integration” credential has been flagged as the Default Credential for its environment, make sure to click the Share button on the credential and add a manual share that is read/write to the appropriate Public Groups.
    1. In our example above, we would share the following “Copado Integration” credentials as read/write to both “Developers” and “Release Managers.”
      1. Dev1
      2. Dev2
      3. Dev3
      4. Dev4
      5. DevMerge
      6. QA
    2. In our example above, we would share the following “Copado Integration” credentials as read/write to only the “Release Managers.”
      1. UAT
      2. Hotfix
  2. Remember that, regardless of the model we choose, we should always have a 1:1 pairing of credentials to Git Snapshot record for each environment in the pipeline. Furthermore, for each Copado Integration credential, create the corresponding Git Snapshot record for the environment and the environment branch against the pipeline repository, and make sure all the Git Snapshot Permissions are set to Allow Commits Only, and the Frequency is set to None or it is blank.

Production Credentials and Snapshot:

Keep in mind that only DevOps team members with the Copado Admin license have permission to commit from and promote/deploy to Production.

  1. Since the Copado Integration user is inactive in Production, Copado’s best practice recommendation for Production deployment is to use a real-named user’s Production credential for optimal traceability and that user must have the Copado Admin license in order to deploy to a Production org:
    1. If your Copado installation includes more than one Copado Admin license, we typically see where the Customer/Partner DevOps team selects one Copado Admin user’s Production credential to flag as the Default Production Credential and then that one Production credential is manually shared as read/write to the other named Copado Admin users, rather than to “Developers” and/or “Release Managers.”
    2. As part of your standard Copado implementation, you should already have a Git Snapshot for the Production Org and main branch of your pipeline repository that is linked to this one Copado Admin-licensed user’s Production credential.
      1. After the initial Copado setup is complete, the Git Snapshot Permission of the Production Git Snapshot record should be updated from Allow Snapshots and Commits to Allow Commits Only because, during the remainder of our use of Copado, we are only contributing incremental commits to the pipeline. Furthermore, the Frequency must be updated to None or left blank.
  2. In this model, the owner of each Copado Integration credential, as well as the owner of the selected Production credential, must also make sure to Generate a Personal API Key.
Model II - Personal/Private Credentials for ALL Environments in the Pipeline

For some Customers/Partners, their InfoSec Policies do not permit Model I, so that is the typical use case for Model II. Just keep in mind that Model II does add additional administrative overhead to the Copado Admins.

Sandbox Credentials and Snapshots:

Please remember that, out-of-the-box, credentials are private in the Salesforce Sharing Model, and the Copado best practice recommendation is to never change this setting.

In this second model, every Copado Admin-licensed and Copado User-licensed user will create their own personal credential, not only for Production (a Copado requirement), but also for: 

  • each Environment in the Pipeline that they will be committing metadata changes from,
  • each Environment in the Pipeline that they will be promoting/deploying and/or back promoting metadata changes to.

In this second model, all credentials remain private (not shared).

Since the Git Snapshot object has a Master-Detail Relationship to the Credential Object, and in the Salesforce Sharing Model is set to Controlled by Parent, each Git Snapshot record is inherently private.

That means that, in this second model, every Copado Admin-licensed and Copado User-licensed user will create their own personal Git Snapshot record for each of their personal sandbox credentials with the Git Snapshot Permission set to Allow Commits Only and the Frequency set to None or left blank.

Production Credentials and Snapshots:

Keep in mind that only DevOps Team Members with the Copado Admin License have permission to commit from and promote/deploy to Production.

Regarding Production specifically, every Copado Admin-licensed user will create their own personal Git Snapshot record for their Production credential and that Production Git Snapshot record should have the Git Snapshot Permission set to Allow Commits Only and the Frequency set to None or left blank.

During the initial Copado setup, one Copado Admin-licensed user’s Production Git Snapshot Permission will be initially set to Allow Snapshots and Commits, to seed the pipeline repository’s main branch, but then the Git Snapshot Permission should be updated to Allow Commits Only and the Frequency should be updated to None or left blank.

In this model, every Copado Admin-licensed and Copado User-licensed user must also make sure to Generate a Personal API Key.


How did we do?