A common issue some of our customers face when using pipelines is they see unexpected differences in their pull requests. There are several reasons why these differences appear, for a detailed technical explanation of this behavior see this article. As a best practice we recommend syncing up all environments to your default base (main/master) after a release to prevent such issues.
Most common use case
When a feature is promoted through the entire Pipeline and reaches Main, it will cause a drift in terms of commits between Main and the other long-lived environment branches (for example SIT and UAT).
This is due to the fact that the PRs are always opened from the original feature branch, so the merge to the UAT branch will have a different number from the merge to Main, even if it will include the same items.
The git provider (GitHub, GitLab, Azure etc.) compares your branches based on the number of commits, not based on the actual items deployed. The consequence of this is that after a merge to Main, when the user creates a new feature branch from Main, it will appear as the next environment (ex: the UAT branch) is behind one or more commits. That means that if we work on a new feature, for example a new field, the PR to the next environment will not only include the commit(s) I made to add the new field to the feature branch, but also all the commits that were previously merged to Main before the feature branch was created.
This is not a huge issue in terms of the actual deployment to the target org, because the automated CI job will find out that those items have already been previously deployed to the target (ex: UAT org). However, it might be confusing for the user to see unexpected items included in the PR targeting the UAT branch.
In Gearset Pipelines we offer a shortcut to create a PR from the Main branch targeting the environment branches. Merging this PR the 2 branches will be again in sync (all the commits that have been done in Main will be replicated in the environment branch):
And promote the Sync PR that gets automatically created
This PR will include all commits that Main is ahead of UAT.
This has to be done for each environment branch, as the sync PR does not get automatically propagated upstream and downstream in Gearset Pipelines, like a normal PR.
Another use case
The Main branch is the source of truth, but sometimes it might happen that something gets added to Prod before Main (a Hotfix, a parallel deployment process outside Pipelines). Sometimes the user needs to add to Main metadata types that were not previously included in Version Control. The user then commits these items to Main, that will drift apart from the other long-lived environment branches (Main would be ahead of UAT for example).
If we create a new feature branch for the new feature A, when the time comes to open a PR against the next environment (ex: UAT), this PR will also include every commit that was added to Main directly.
The solution to this issue is again to click on the Sync Environment button for each node of the Pipeline. This will create a PR from the Main branch targeting the environment branches. Merging this PR the 2 branches will be again in sync (all the commits that have been done in Main will be replicated in the environment branch).
Please be aware that if new metadata types have been added to Main, the filters in the CI jobs need to be updated accordingly or the automation will not see those changes and will not deploy them to the target org.