After each production release, Gearset creates a sync PR to bring your pipeline's earlier environments back in line with your production branch. When that sync PR has no file changes, Gearset merges it for you automatically, so nobody on your team has to merge it by hand. If a sync PR does contain file changes, Gearset leaves it open for your team to review. This article explains when Gearset merges a sync PR automatically, what happens if it can't, and how to turn the behavior off.
Note: Automatic sync PR merging doesn't apply to pipelines that use Gitflow. Sync PRs serve a different purpose in a Gitflow pipeline.
What is a sync PR with no file changes?
A sync PR with no file changes holds only the merge commits Gearset needs to bring an environment branch's commit history back in line with your production branch. Merging it doesn't change any metadata in your Salesforce org, so it doesn't trigger a deployment either.
For more on how sync PRs differ from back propagation PRs, see Keep your Pipeline environment branches in sync.
When does Gearset merge a sync PR automatically?
When automatic sync PRs are turned on in your pipeline settings, Gearset automatically merges any sync PR that has no file changes. The process runs like this:
You merge a PR or a release into your production environment.
Gearset creates the sync PR, or updates the sync PR that's already open.
Gearset checks whether the sync PR has any file changes. This is a file diff check that your Git provider performs as part of its pull request process.
If the sync PR has no file changes, Gearset merges it and posts a comment on the pull request in your Git provider to say it merged automatically.
Do validations still run on an auto-merged sync PR?
Gearset's sync creates the pull request, but it's your Git provider that determines whether there are any file changes. This is a file diff check your Git provider performs as part of its normal pull request process, comparing every file in the pipeline's repository. It doesn't check whether Salesforce would validate those changes as metadata, so the pull request can show changes for any file difference, not just ones that would affect a deployable change.
How do auto-merged sync PRs appear in promotion history?
Sync PRs that Gearset merges automatically appear in your pipeline's promotion history as merged by Gearset, with a Sync PR type tag. In your Git provider, the same merge shows up as made by your team-shared Git user.
[Screenshot needed: the pipeline promotion history showing an auto-merged sync PR with its "Sync PR" tag.]
Why does Gearset leave some sync PRs open?
Gearset leaves a sync PR open when it contains file changes. File changes in a sync PR can be a sign that something unexpected reached your production branch, so review the changes before you merge the sync PR yourself. Merge sync PRs with file changes by hand: Continuous delivery rules apply to back propagation PRs only, so they can't merge a sync PR for you.
Do I need to change my branch protection rules?
If your environment branches have branch protection rules, such as required reviews, Gearset can only merge a sync PR with no file changes when your team-shared Git credentials are allowed to bypass those rules. Give your team-shared Git user permission to bypass branch protection on your environment branches. Without that permission, the sync PR stays open and you merge it yourself.
For more on which credentials Gearset uses for each pipeline action, see Which Git credentials are used for which actions in Pipelines?
What happens if Gearset can't merge a sync PR?
If Gearset can't merge a sync PR with no file changes, for example because of branch protection, the sync PR stays open in your pipeline. The sync PR sidebar shows why the merge failed, with a How to resolve button.
[Screenshot needed: the sync PR sidebar showing the "How to resolve" button after a failed auto-merge.]
How do I let my team-shared Git user bypass branch protection rules?
Gearset can only merge a sync PR automatically if your team-shared Git user is allowed to bypass your environment branches' protection rules, such as required reviews. Without that permission, Gearset leaves the sync PR open for you to merge by hand, even when it has no file changes. Set this up directly in your Git provider:
GitHub: add your team-shared user to the bypass list when you set up required pull requests, under
Allow specified actors to bypass required pull requests. See Managing a branch protection rule on GitHub Docs.GitLab: set your team-shared user, or a group it belongs to, to
Allowed to push and mergeon the protected branch. See Protected branches on GitLab Docs.Azure DevOps: grant your team-shared user the
Bypass policies when completing pull requestspermission on the branch. See Branch permissions on Microsoft Learn.Bitbucket: grant your team-shared user merge access, and write access if it doesn't already have it, on the protected branch. Bitbucket doesn't have a single bypass setting, so these access levels are what let the team-shared user complete the merge. See Use branch permissions on Atlassian Support.
How do I turn off automatic sync PRs?
Whether automatic sync PRs are on by default depends on your pipeline:
New pipelines have automatic sync PRs on by default.
Existing pipelines that already have the toggle switched on keep automatic sync PRs on.
Existing pipelines that already have the toggle switched off keep automatic sync PRs off.
To turn off automatic sync PRs:
On the Pipelines page, click the cog icon.
Click
Edit pipeline details....Turn off Automatically create Sync PRs after a production release.
[Screenshot needed: the pipeline cog menu showing "Edit pipeline details..." and the automatic sync PR toggle.]
Useful resources
If you have questions about automatic sync PRs, please send a message to our support team, who will be happy to help.