Skip to main content

Keep your Pipeline environment branches in sync

Syncing environments in Gearset Pipelines (also referred to as 'static environments') via the use of 'Create sync PR' feature

Mateusz Kochanowicz avatar
Written by Mateusz Kochanowicz
Updated today

Difference between Sync Pull Request (PR) vs Back Propagation PR

Your Gearset Pipeline is designed to automatically open back propagation PRs after individual features get propagated to your base branch (usually Main/Master) 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).

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 between the branches (e.g. Sync PR created from Main -> UAT environment will 100% align the history of commits between these two Pipeline environments).
​
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).

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.

Summary of 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 - before you open a new PR in your Pipeline, make sure that you create a Sync PR on 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.

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.

Are you adding new metadata types to Main?

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.

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.

Did this answer your question?