Sign in to Essentials+ with your Salesforce login using a common org across the team, typically your production org (this allows the team to all be represented for simple account management from the Team tab of Account Settings).
Add your orgs to Copado Essentials+
Click Add Organization. Add each org that is part of your development pipeline. Give it a name. Select Salesforce Org in the Type field. Under Environment, select if the org is a production-level org (signing in from login.salesforce.com) or a sandbox org (signing in from test.salesforce.com). Click Authorize and sign in to the org. Click Save. Perform these steps for up to 50 orgs (per user).
Ensure Enable Direct Commit to Branch and Enable Work Items are checked:
Select [your user name] at the top-right corner of the app > Account Settings. Click on the Team tab in the left-hand column. Find and check the Enable Direct Commit to Branch and Enable Work Items checkboxes on the Team page.
Initialize Your Git Repository:
Navigate to your Git provider and create a new repository within your account. Ensure that your permissions within Git allow for third party tools to perform actions.
Inside Copado Essentials+, navigate to the Organizations tab and click Add Organization. Select the appropriate Git provider (e.g., Github, Gitlab, Bitbucket, Azure DevOps) from the Type list. Give your repository a name (e.g., "Github Repo"). Click Authorize. This will pop open a screen to log into your Git provider. Once logged in, click the blue Select Repository button next to the Git repo URL and select the appropriate repository that you just created.
Click Save on the record.
Click the Deployments tab along the top of your screen.
Create a new deployment by clicking “New Deployment” in the top right corner. Give your deployment a name (i.e. Git Init). Set your Source Org as the top level production org of your development pipeline (this will be your master branch). Set your target org as your Git repository that you added in previous steps. Click Save.
From the Add Components tab on the deployment page, click the component Type dropdown and select Wildcard. On the right-hand side of the component grid, click the Select checkbox that tops the column second from the right. You should see all of the wildcard components selected in this list, now.
Next, go to the Deploy Options tab, scroll down to the bottom of the page and click the “Change” button and click on the gray Advanced Options dropdown, as well, to display all of the available deployment options. Find the Git Branch section. Check the box next to “Commit directly to the target branch master”. This commit will now be performed directly to the master branch of your repository. Click Save at the bottom of the page.
Scroll back to the top of the page and select Commit to Git Branch blue button. This could take several moments depending on the size of your Salesforce org as Copado Essentials+ is capturing a snapshot of your org as it currently stands.
Navigate back to your repository. Clone your master or main branch of your repository for each of your Salesforce orgs that are part of your work stream. For example, in a pipeline where developers are working in their dev boxes and then merge into an Integration Sandbox or UAT Sandbox, your repository would have a Master branch and an Integration or UAT branch. These extra branches allow for you to resolve any merge conflicts long before the changes reach your production environment or master branch.
This is how it will look in Github (the idea is the same in other Git repositories):
From here, select the Master branch button, type in your branch name (e.g. UAT), and click Create branch from 'master'.
NOTE: If using an enterprise repository (i.e. on-premise), you will need to provide Copado Essentials with a Git Repo URL where it can access your repo, and if using HTTPS, a Login Username and Password. If using SSH, you will need to provide your login username as well as configuring SSH keys within your Git provider settings. Copado Essentials will generate the private and public keys for your use when you click the “Generate Key Pair” link next to SSH.
Sharing orgs and repositories
Sharing orgs and repositories reduces repetitive work. This Help article called Team Collaboration provides instructions for setting this up.
If you plan to use Deployment Pipelines with Work Items follow the steps below, otherwise proceed to the step for setting up CI Jobs, below.
Configure Pipeline
Navigate to Account Settings by clicking your username in the top right corner and clicking Account Settings from the dropdown. Once in Account Settings, click the Pipelines tab along the left hand column.
Click “Add Pipeline” in the top right corner. Give your pipeline a name.
If you are wanting to integrate Git into your pipeline, select your Git repository in the Git Org dropdown.
In the first Environment area, name the environment where you would like your changes to start. Traditionally, this will be in a Dev environment. In the organization dropdown, select the appropriate Salesforce Org where your changes will start.
For the subsequent Environment boxes, follow the previous step to configure each subsequent step in your work stream.
For each subsequent work stream step, if Git is included in your pipeline, you will need to select the appropriate Git branch so that when a work item is deployed along the pipeline, the appropriate Git branch is updated simultaneously.
Once your entire pipeline is represented, click the Save button.
Note: Some development teams utilize an Essentials+ pipeline as a means of "back deploying" their work to keep their dev environments in sync with each other. In this deployment scenario, you would set your production as the first pipeline environment and each subsequent environment will be the associated dev environments that need to be kept in sync with production after a release.
Optional: If you plan to utilize CI jobs to automatically deploy changes committed to a Git branch to the associated org. Please follow these steps:
Create and Configure CI Job
Click the CI Jobs tab along the top of the page.
Click “New Job” in the top right corner or “Create your first CI job” in the middle of the page.
Give your CI Job a title (best practice is to name your CI job with the expected functionality i.e. “UAT Branch to UAT Org”)
IMPORTANT: Your CI job source org should be the Git Repository that you would like Essentials to deploy changes from. Select your Git Repository and the correct branch as your source org.
Select your Target org. This should be the corresponding Salesforce org that the source org branch is the record of truth for.
Select your action. Recommendation: if setting up for a production level environment, choose the validate action. Choosing this action will allow Essentials to build the deployment for you and check it for any missing dependencies while still giving you the ability to manually control any releases to your live production environment.
Select your schedule for performing the CI action. If triggering from a Merge into the branch, please leave this value as “None”.
Check the box next to “Triggered by Git commit to branch”. When you check the box, you should see a “Setup Webhook” link appear next to the Checkbox text.
Click the “Setup Webhook” link. This will pop up a modal with a Payload URL in a gray box. Copy the webhook URL and follow the instructions found in the “Like This” link found in the modal.
Once the configuration is complete in your Git repository, click the Save button.
VERY IMPORTANT: Once your CI job has been saved, navigate into the CI job and click the Deploy Options tab.
Find the Git Source area and select the option “Deploy files committed since the last successful build”. This will validate or deploy the pieces of metadata that are successfully merged into the Git branch.
Trial Use Cases:
Deploy a change from Org to Org using Deployment tab
Navigate to Deployments tab and select New Deployment.
Give your deployment a name.
Select your Source Org (where your changes currently sit).
Select your Target Org (where your changes need to go).
Click Save.
Click the Add Components tab.
Select the Component Type or convenient Component View with your changes.
Using the diff key along the right hand side of the screen, select the appropriate components you want to deploy.
If deploying Apex code and wishing to run Static Code Analysis (SCA) or Apex tests:
For Apex Tests, click the Deploy Options tab to manage your deployment options. You can select only certain tests to run by changing the Test Level to be Run Specified Tests. If you’d like to run all Local Tests in the org, select Run Local Tests. If you’d like to run all tests including managed package tests, select Run All Tests in Org.
For Static Code Analysis, find the more dropdown in the top of the page to the right of the Validate and Deploy buttons. Once open, click on Run Static Code Analysis to kick of a run of Static Code Analysis. The results will be displayed on the deployment screen in the yellow box above the buttons. Static Code Analysis can also be run from the Deploy Options tab by checking the box next to Code Analysis.
Once you are satisfied with your deployment, click Validate and/or Deploy in order to validate and deploy your selected components to your target org.
Deploy changes using work items (Git included if included during setup of pipeline)
Ensure your pipeline is configured correctly through the previous steps.
Give your Work Item a name.
Select your Pipeline.
Double-check the starting environment.
Click Save.
Click the Add Components tab.
Select the Component Type or convenient Component View with your changes.
Using the diff key along the right hand side of the screen, select the appropriate components you want to deploy.
If deploying Apex code and wishing to run Static Code Analysis (SCA) or Apex tests:
For Apex Tests, click the Deploy Options tab to manage your deployment options. You can select only certain tests to run by changing the Test Level to be Run Specified Tests. If you’d like to run all Local Tests in the org, select Run Local Tests. If you’d like to run all tests including managed package tests, select Run All Tests in Org.
For Static Code Analysis, find the more dropdown in the top of the page to the right of the Validate and Deploy buttons. Once open, click on Run Static Code Analysis to kick off a run of Static Code Analysis. The results will be displayed on the deployment screen in the yellow box above the buttons. Static Code Analysis can also be run from the Deploy Options tab by checking the box next to Code Analysis.
Once you are satisfied with your deployment, click Validate and/or Deploy in order to validate and deploy your selected components to the next environment in your pipeline.
Once ready to deploy again, return to your work item and click Validate and/or Deploy in order to validate and deploy your selected components to the next environment in your pipeline.
Deploy changes to Git using Deployments tab
Navigate to Deployments tab and select New Deployment.
Give your deployment a name.
Select your Source Org (where your changes currently sit).
Select your Target Org.
NOTE: If deploying to a Git repo, this should be the org you have authorized from the Organizations tab.
Once Git repo is selected, select the branch you wish to create your feature branch from by clicking “Select Branch” and using the dropdown to select from the branches configured in your repo.
NOTE: Ensure all of your environments upstream have their own branch within your repository to take advantage of the ability to address merge conflicts earlier on within your development process.
NOTE: These changes can also be directly merged into the target branch without making use of feature branches by selecting “Commit Directly to the Target Branch XXX” in the Deploy Options area of your deployment screen. This approach however will not offer the same level of review and merge conflict detection as the feature branching strategy chosen by default.
Click Save.
Click the Add Components tab.
Select the Component Type or convenient Component View with your changes.
Using the diff key along the right hand side of the screen, select the appropriate components you want to deploy.
If deploying Apex code and wishing to run Static Code Analysis (SCA) or Apex tests:
For Apex Tests, click the Deploy Options tab to manage your deployment options. You can select only certain tests to run by changing the Test Level to be Run Specified Tests. If you’d like to run all Local Tests in the org, select Run Local Tests. If you’d like to run all tests including managed package tests, select Run All Tests in Org.
For Static Code Analysis, find the more dropdown in the top of the page to the right of the Validate and Deploy buttons. Once open, click on Run Static Code Analysis to kick of a run of Static Code Analysis. The results will be displayed on the deployment screen in the yellow box above the buttons. Static Code Analysis can also be run from the Deploy Options tab by checking the box next to Code Analysis.
Once you are satisfied with your deployment, click Commit to Git Branch.
When the commit has completed, a new button will appear next to Commit to Git Branch that says “Review Changes”. This button will take you into your respective Git repository directly to the most recent commit. From here, perform your reviews of the committed code.
When ready, follow your Git providers steps to open a Pull Request and then Merge it directly into the target branch.
NOTE: If your CI job was set up before you performed the merge, you can now navigate back into Essentials to review the build of components that were deployed. Click the CI Jobs tab, find the associated CI job for that environment and click it. Once in the CI job, you will see the record of Successful and Failed builds along the left hand side of the screen. Each build can be clicked on to see the components included as well as perform a rollback if you wish by clicking the green “Rollback” button at the top of the screen.
NOTE: If the CI job was not set up before merging, you will need to perform a second deployment from your updated Git branch to your target Salesforce org in order to migrate changes from Git into Salesforce.
[End]