Maintaining a synchronized Gearset Pipeline is essential for a stable and efficient Salesforce release process. When environment branches drift out of sync with your Main/Master branch, you risk unexpected merge conflicts, deployment failures, and overwritten work. This guide outlines how to keep your Pipeline aligned, ensuring every environment reflects the latest state of your Main/Master branch so your team can build and release features reliably and rapidly.
Difference between Sync Pull Request (PR) vs Back Propagation PR
As an introduction, below we're providing a more in-depth and technical explanation of the difference between Sync PR feature and the Back Propagation PR, which are both used in Gearset Pipelines.
These two features are there to help your team keep the Pipeline environments aligned and in sync. Before you start using them it's important to gain an understanding of how each feature helps in different ways.
Read more about it (click the arrow to expand)
Read more about it (click the arrow to expand)
Your Gearset Pipeline is designed to automatically open back propagation PRs after individual features get propagated to your base branch (usually Main/Master) and consequently to Prod - this behavior applies when your Pipeline is configured to create back propagation pull requests "Only when changes are promoted into the final environment", which is Gearset's recommended setup, and as long as you're using Gearset Pipelines branching model.
These individual back propagation pull requests (PRs) contain only the relevant commits that built up that feature (e.g FeatureA contains 3 commits of work, so the back propagation PR would contain those 3 commits only). This allows you to be very granular with which features come back to which Pipeline environments at a specified time.
However, since Gearset Pipelines uses the merge commit strategy, a unique commit is generated when FeatureA merges onto your base branch (Main/Master), which isn't included in the back propagation PRs themselves (as the unique commit is only generated on merge).
This back propagation behavior leaves those unique commits present in Main and doesn't back propagate them to lower Pipeline environments, which can cause some confusion when they appear on new feature branches, which is explained in further down in this article.
In contrast, a Sync PR uses your base branch (Main/Master) as the source and the environment branch as the target, so that all commits are present to pull back (when Sync PR is merged), including those unique merge commits, which essentially fully aligns the history of commits that made it in Main onto the environment branch.
Unlike back propagation PRs, Sync PR loses the individuality of each feature, and would bring back all commits from Main/Master to respective environment branch(es) - that is regardless of whether these features are legitimate components that could result in a validation and deployment to the target org (Sandbox) of your CI job, or if these are just the unique merge commit(s) which won't necessarily require a deployment of any metadata components to the org (e.g. because Main/Master is already aligned with Pipeline environments on the metadata level).
Functionality of Sync PRs
In a nutshell, Sync PRs in Gearset Pipelines will:
Merge any metadata items that are present in Main/Master branch into the respective environment branches against which Sync PR(s) is created for.
Align the history of Git commits (commit numbers) made in Main with the history of Git commits made in other environment branches (e.g. INT, UAT, QA etc.)
Every new commit made in Main is not present in your Pipeline's environment branches until a Sync PR is fully merged in Gearset. Therefore, the best practice is to create a Sync PR after every Prod deployment in Gearset Pipelines to ensure all the environment branches are continuously kept in sync.
How to automate the creation of Sync PRs in the Pipeline
Enable automated Sync PR creation in Pipeline settings
On your Pipelines page, click the cog icon 
-> Edit pipeline details... -> then enable: Automatically create Sync PRs after a production release.
Quick video to show where the setting is:
Gearset will provide more information on the automatic creation of Sync PRs shortly!
How to manually create Sync PRs in the Pipeline
Note: These steps are to be followed if you've not enabled your Gearset Pipeline to automatically create Sync PRs for you.
Follow best practices - ensure that the next environment is in sync before you open a new PR in your Pipeline (one of the ways to do that is to check that a Sync PR was created and merged into the environment to which you're going to promote your new PR).
Ideally, we recommend to click on the final Pipeline environment (normally Prod) and select Create sync PRs from there - this automatically opens sync PRs against each of your Pipeline environments (see video below).
Once the Sync PR is merged, you're ready to create the PR with your changes. This way your newly created PR will contains only the changes you're promoting.
Note: Creating a Sync PR to fix a PR that is already opened and in progress in the Pipeline, in order to remove unexpected changes from it, won't fix your issue! Instead, you'd need to create and merge the Sync PR, and then re-create your original PR - keep in mind this may not apply to all VCS providers or the behavior may differ depending on the VCS used in the Pipeline (e.g GitHub, Azure DevOps, Bitbucket etc)
And if a Sync PRs had already been created and merged, Gearset will inform you about it (see image below).
This will essentially prevent you from creating another Sync PR(s) when we detect that Git commit histories are fully aligned between Main and the environment branch.
Expected behavior when both Sync PR and back propagation PR(s) opened against the same environment
Note: This applies to unique scenarios where both Sync PR and back propagation PR(s) contain the same changes.
If you have back propagation PR(s) opened in the Pipeline (containing your individual feature branch commits), and then if you open a Sync PR to the same environment:
When you merge a Sync PR, as long as the Sync PR contains all the commits that back propagation PR has, the back propagation PR will auto close. It should also show as merged in the "Recent promotion history" tab.
However, if the back propagation PR has more unique commits than the Sync PR, then it won't auto close.
GitHub, Bitbucket and GitLab would automatically close any individual back propagation PRs if the Sync PR merges all the same changes before the back propagation PR does - it's because these VCS providers will detect if all the relevant commits end up on the target branch via other means, and close any PRs that are now redundant.
Azure DevOps however will leave the PR open (so it'll continue showing in the Pipeline), and will show a message that: "all changes in this pull request have been already merged to the target branch" - it is safe to either merge or abandon such PR.
FAQs
These are some of the commonly asked questions that are related to keeping your Pipeline environments in sync, as well as to the "Create Sync PR(s)" feature that is designed to help teams achieve the healthy state of Pipeline branches being as aligned as possible with whatever changes reach Main/Master and eventually Production org.
Will the Sync PR overwrite work in progress in that environment?
Will the Sync PR overwrite work in progress in that environment?
Let's say that in your Pipeline, two developers are working out of two separate feature branches, but each branch contains the exact same Custom field component.
The first developer has promoted their changes to the Custom field all the way to Production. The second developer however, has only reached the penultimate environment (Staging). If you were to trigger and merge the Sync PR, can we expect the second developer's Custom field to be overwritten?
Not automatically, no. We would expect this to trigger a merge conflict within your Pipeline. In this particular example, you'd be presented with a warning and an option to allow you to choose which Custom field changes you'd like to maintain (either those from the first developer or the second). You never have to worry about the accidental overwriting of components.
Do you see unexpected differences in your PRs?
Do you see unexpected differences in your PRs?
A common issue some of our customers face when using Gearset Pipelines is unexpected differences in their pull requests (also referred to as "additional items" showing in the PRs).
There are several reasons why these differences appear. For a detailed technical explanation of this behavior, see this article:
Are your Pull Requests not showing what we expected?
Solution and best practice: create Sync PRs after Prod releases
As a best practice when using Gearset Pipelines, we recommend syncing up all Pipeline environments to your default base (Main/Master) after each release to Prod - this is to prevent the most common issue, such as users working with Gearset Pipelines seeing additional and unexpected items in their PRs.
Are you (thinking of) adding new metadata types to your Pipeline?
Are you (thinking of) adding new metadata types to your Pipeline?
If you're adding new metadata types to the Main branch, it's important to update the metadata filter(s) in all of the CI jobs associated with your Pipeline!
Otherwise, if the metadata filter isn't updated, and you merge a PR with a new change (e.g. Lightning page), the CI job would likely skip the deployment of any metadata items (e.g. Lightning page) that are not added to the filter used in that CI job.
Follow Gearset's recommendation and best practices on how to add previously missing metadata types into Gearset Pipelines.