A common issue some of our customers face when using Gearset Pipelines is they see unexpected differences (or additional items) in their pull requests. 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?

As a best practice, we recommend syncing up all environments to your default base (Main/Master) after each Prod release - this is to prevent such issues.

We have introduced a feature called "Create sync PR(s)" that will allow you to easily sync your environment branches with your default base (Main/Master).
​
Every Pipeline user should be familiar with what Sync PR does and how it helps to keep your Pipeline environment branches in sync.

Read below to find out how to verify what is actually being validated in your deployment package, and therefore deployed to the org, even if the PR is showing additional metadata items.
​

When users see this behavior (unexpected items in their PRs), their primary concern is that the CI job might be deploying metadata that they do not intend to deploy.

Usually, this is not the case. If you’ve run a validation on your PR, you can confirm this in your Pipeline.

To do it, select your PR and under Merge and validation checks select View details:

This will give you an overview of what components your CI job has attempted to validate. In this case, you can see that 75 component have been validated. This means that when the CI job attempts a deployment, it will only deploy what is included in this validation.

But why is there a discrepancy between what your CI job is validating, and what is displayed in Files with changes on your PR?

When a feature is promoted through the entire Pipeline and reaches Main/Master, it will cause a drift in terms of commits between the Main and the other long-lived environment branches (for example INT or UAT or whatever the green Pipeline environments are called).

The changes you are seeing in the PR are the commit differences showing between your feature branch, which is a copy of your Main branch, and the environment branch (for example INT or UAT). This can be seen in both scenarios shown as below.

In the below example, the commit difference is between the feature branch XCV and the Environment branch ADO INT.

Here is an example of a PR which shows 100s of changes which are the commit differences between the promotion branch created out of the original feature branch (eg XCV) against the environment branch (ADO INT).

This is due to the fact that the PRs are always opened from the original feature branch, so the merge (commit) to the UAT branch will have a different number from the merge to Main, even if it will include the same items. So it is the commit difference(s) that are showing in this part of the PR (on the "Files with changes" tab).

In cases like this, for the actual number of components deploying, you can check the VALIDATION CHECKS section > View details on the PR.

Alternatively, on the CI jobs page, find the CI job in question (e.g. ADO INT), click on it to unfold all the pending PRs against this environment and select Validation runs -> View comparison or View summary* to preview the items that will be added to the deployment package and be deployed to the org with this PR.
​
*View summary option will show you the same list of items but on the validation page as opposed to a comparison preview.
​

This will be the actual number of components deployed against the Org.

It's important to note that validated components are not always synonymous with the files changed in a deployment. A single component can be made up of multiple files, which may affect how changes appear in your deployment summary.

Suppose you modify an Apex class in your source org. The following files may be changed:

Even though two files are modified, they belong to a single Apex class component. When validating or deploying, Gearset treats this as one component, not two separate changes.

This distinction is crucial when reviewing deployment summaries or understanding why the number of validated components differs from the count of Files with changes.

Or go to CI job history of that PR and check the delta comparison to see what the package contains which it will deploy to Org when you promote the PR.

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 a user creates a new feature branch from Main, it may appear that the next environment (e.g. UAT branch) is behind one or more commits. It 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) we made to add the new field to our 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 (e.g. 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. By merging this PR, the 2 branches will be again in sync (meaning that: all the commits that have been done in Main will be replicated in the environment branch).
​
Below screenshot shows a Sync PR ("sync pull request") feature in the Pipeline. You can trigger it by selecting Create pull request (blue button).

This creates the Sync PR within your Pipeline. Sync PR will show up against your selected environment branch, so that you can Promote it:

The Sync 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.

The Main branch is the source of truth, but sometimes it might happen that something gets added to Prod before Main (for example a Hotfix, a parallel deployment process outside Pipelines).

Sometimes a 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 a new "feature A", when the time comes to open a PR against the next environment (e.g. UAT), this PR will also include every commit that was added to Main directly.

The solution to this issue is:

When a hotfix is pushed directly to main this may cause the earlier environments to become out of sync. The recommendation is to push this hotfix back through the pipeline's environments before creating a new feature branch. Any feature branch created from main will include the hotfix changes. If these changes are not in your next environment such as Integration, they will appear in the pull request.

If you have changes A & B you would like to move through the pipeline, but hotfix C was made to main before the feature branch is created. Then this feature branch would include A, B & C. To make sure the pull request only has A & B, then the commit C will need to be back-propagated before the feature branch is created. Once the back-propagation is finished, use the Sync environment option to align the git histories of your environment branches in addition to back-propagating changes.

Another common reason for this to come up is if changes were committed to a branch (such as main or an environment branch) outside the typical pipeline release cycle, so they did not make it to all environments. Similar to the hotfix behavior, this will cause the environments to be out of sync. When out of sync, pull requests will include extra components as they existed on the feature branch (created from your source of truth) but not the environment branch.

Using the Sync Environment option in Gearset, will allow you to pull these changes from your source of truth (commonly main) to the environment branch. This will allow the net changes between the feature branch and environment branch to be only the changes made to this specific feature.

Check our documentation on what the semantic merge is.

Hopefully this article will make it easier to know how to track down constituent parts of the profile object for your deployment. If you have any questions, let us know.