Pipelines currently supports one branching model:
The diagram above is just one example of the use of this branching model. You can include as many, or as few, Salesforce orgs as you'd like, connected to each other in any way you'd like. In the example above there are three Salesforce orgs:
One or more Developer Sandboxes – ideally one per team member. This is where people work on their changes, before pushing them into the repository.
A Staging environment.
A Production environment.
Changes start out in a Developer Sandbox, before flowing into Staging, and finally to Production.
In this branching model, most orgs have their own associated long-lived environment branch. By merging changes into an environment branch, you can resolve any merge conflicts and avoid overwriting changes directly in the target org.
Each environment (org/environment branch pair) has its own CI job that monitors for changes to the environment branch, and pushes those changes out to its target org. This keeps the org and the environment branch in sync.
Note there is an exception, in that developer sandboxes have no long-lived environment branch. Instead, they have associated short-lived feature branches, and no corresponding CI jobs.
When an individual team member has a change they want to push through the release pipeline, they first create a feature branch from the
master) branch. They can create the branch and commit their changes all from the manual compare and deploy workflow in Gearset. Of course, if some team members would prefer to use VSCode and the Git CLI – or any other tools – then that's fine, too!
When individuals want to deploy their changes to a specific environment in the pipeline, a new branch is created from the feature branch. This new branch is called a promotion branch, and is specific to the
(feature, environment) pair. This promotion branch is then merged into the environment branch.
Therefore, even though the feature branch isn't merged, the feature itself is promoted across the pipeline using these promotion branches that get created between each environment.
For example, the feature branch
ABC is being promoted in this screenshot via the promotion branch
Here are some of the FAQs around promotion branches.
Why use promotion branches?
Using promotion branches allows merge conflicts to be resolved without pulling unrelated changes into the original feature branch. You can do this by merging the environment branch into the promotion branch and resolving any conflicts there. If you did this directly into the feature branch, unrelated changes in your environment might get accidentally pulled into downstream environments.
How do the changes get into the org?
As soon as the promotion branch is merged into the environment branch, the environment's CI job will detect the merged changes and deploy them out to the org associated with the environment.
Do I have to create the promotion branch myself?
The short answer is no, but you can if you’d like to do so:
If you’re using the new Developer Sandbox environment, type it in your pipeline. Creating a pull request within the UI from that environment will automatically create a promotion branch for you.
If you create a pull request against an environment in an active Pipeline from a bare feature branch within your provider (i.e. GitHub), we will create a promotion branch from this feature branch and open a pull request from it to the target environment. The original pull request will be closed, with a link added in its comments to the newly opened promotion branch pull request (we'll also link back in the opposite direction).
If you create a pull request from Gearset, targeting any of the source branches of your Environments in Pipelines, then this will automatically be created as a promotion branch. You can create the pull request within Gearset in your Deployment Summary page.
Alternatively, you can manually create a promotion branch outside of Gearset using the correct naming convention:
create a new branch from the feature and call the branch:
# environment's branch is called 'staging'
# feature is called 'add-field-to-account'
git checkout add-field-to-account
git checkout -b gs-pipeline/add-field-to-account_-_staging
git push -u origin gs-pipeline/add-field-to-account_-_staging
# Create a new pull request against staging and set the source
# to gs-pipeline/add-field-to-account_-_staging
# If you run into conflicts, you can safely resolve these in
# your new gs-pipeline/add-field-to-account_-_staging branch
# If you already opened a pull request directly using the
# feature branch add-field-to-account, close it
Doing extra work on a feature
If you have a feature already in your pipeline that needs more work, then you can do that work in your original feature branch. Note that Pipelines will detect this and automatically back-propagate the extra work to earlier environments (if necessary), to avoid drift between your environments.
If you have extra work specific to the environment you’re merging into, then you can do that in the promotion branch and it will not be promoted further. Generally, this is only necessary in order to resolve merge conflicts with a particular environment.
If you make additional commits to the feature branch and a promotion branch pull request is already open against an environment, Pipelines will automatically sync them into the open promotion branch pull request. On merging the changes into the environment, if these new commits are missing from the previous environment, we'll open a back-propagation pull request containing the missing commits to ensure all branches are kept up to date.
When the feature is ready for release to production, it's deployed by merging one final promotion branch back into
main. In this model,
main is essentially the environment branch for production.
You're free to merge to
main either during or at the end of the sprint. We'd also recommend that, after each release, you merge
main back into each environment branch in turn. If your environments are set up as in the above diagram, for instance, then we'd suggest you merge
main back into your long-lived environment branches (
staging, in this case) using your git provider or CLI at the end of sprint or after a release. This is helpful for a few reasons:
It guarantees that all changes that ended up in
mainhave been pulled back into the upstream environments, reducing the chance of surprise merge conflicts in the next sprint.
It brings any merge commits made against
maininto upstream environment branches, keeping your branching and commit history cleaner and easier to understand.
If you have a merge conflict when merging to
main, and you make any additional changes when resolving that conflict, it ensures that these changes will be captured in the upstream environments, too.
Now that you’re familiar with the branching model used in Gearset Pipelines, the next document will show you how to set up your first pipeline.