Pipelines currently supports one branching model:
Note for when setting up a pipeline: For Gearset’s pipelines to work as expected, make sure to set the branch synced to prod (in this example main) as the Default base branch for new feature branches.
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.
Environments
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 branches. Instead, they have associated short-lived feature branches, and no corresponding CI jobs.
Features
When an individual team member has a change they want to push through the release pipeline, they first create a feature branch from the Main (or 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!
Promotion branches
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. These promotion branches such as gs-pipeline/ABC_-_Pipelines-Integration will always be created off the feature branch. This promotion branch is then merged into the long-lived 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 gs-pipeline/ABC_-_Pipelines-Integration.
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 in 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 then 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 Git 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 (accessible via Deployment history page where you'd select
View detailsunder the deployment from which you'd like to create the PR).Alternatively, you can manually create a promotion branch outside of Gearset using the correct naming convention:
Create or clone a new branch from the original feature branch and call the branch:
gs-pipeline/<feature-branch-name>_-_<env-branch-name>
# Example:
# 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.
Note: Your Pipeline 'Create back propagation pull requests:' setting will dictate when those extra commits are back propagated to the previous environments, so it will only be immediate if the setting is 'when changes are promoted into any adjacent environment'. If the extra commits can't be automatically added onto the Promotion branch for any reason, we'll open a special 'Sync:' PR to ensure the environment is up-to-date (see screenshot below, note the two-directional arrows). You'll need to promote the sync PR before the propagation can take place. This is to ensure the propagations are always representative of the current state of the feature branch.
Pull requests titles prefixed with Sync: will be dealt with in a specific way. You should avoid manually prefixing your pull request titles with the keyword, or you'll experience unexpected behaviour.
Managing your main branch
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 the 'Sync environment' button referenced here, your git provider or CLI, usually 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.