Once a pull request is open and displayed in front of an environment, we can select the environment to see the pull request and feature ready for promotion. Once a pull request is promoted, we open a pull request of this feature against the next environment in the pipeline.

But what happens behind the scenes with Pipelines, from when a PR is opened against an environment branch to when we automatically open a PR to the next one?

These are the steps in chronological order:

Step 1 - User opens a PR from feature branch to environment branch. This PR will not trigger the child validation if the CI job linked to that environment has the option "Validate pull requests" selected.

Step 2 - The PR from the feature branch is closed. Gearset opens a new PR from promotion branch to environment branch.

Step 3 - This time the feature "Validate Pull Request" is triggered. Gearset runs a validation from promotion branch to the org target of the CI job. When the job is set up as Delta CI, child validations triggered by PRs are now faster because the comparison re-uses the snapshot taken after the last successful deployment run, rather than downloading again the current state of the org.

Step 4 - Merge conflict check against environment branch.

Step 5a - NO CONFLICTS DETECTED -

No extra action required. The Promote changes button will be available to click. If a peer review is required, the review status will be shown in Pipelines UI for pull requests in GitHub, GitLab, BitBucket and Azure DevOps. Until the review is done on your Git provider, the Promote changes will be clickable but merging would just fail because conditions haven’t been met. Most source control providers give you control over the "mergeability of pull requests".

Step 5b - CONFLICTS DETECTED -

After the user chooses which lines they want to keep, we do a merge commit from the environment branch to the promotion branch. The PR already open will now include the new commit and the Promote changes will become available because conflicts were resolved. We "Validate pull requests" again, running the validation from the promotion branch against the target org, before the Promote changes becomes available. As mentioned above, Delta CI jobs will re-use the snapshot taken after the last successful deployment run for this child validation. This will also happen if the user makes any other commit to the promotion branch.

If the new commit resets the review requirements, the user will have to go back to the Git provider (GitHub, GitLab etc) and have someone complete it again, or the merge will fail.

Step 6 (If applicable) - Users can have additional checks for their PRs in their Git Provider. Gearset will show that those checks have passed or failed.

Users can then proceed with the propagation using their judgement.

Step 7 - Gearset merges the selected PR into a local branch.

Step 8 - Merge conflict check of the local branch against environment branch.

Step 9 - Gearset runs a Validation from the local branch against the Org target of the CI job. This should be validating exactly what ends up deploying from the environment branch when the CI job is triggered after the merge. Gearset will skip this validation if all of the following conditions are true:

Step 10 - API-merge of the PR into the environment branch:

When the user clicks on the Promote changes, that merge will be recorded on the Git Provider as being done by the user who clicked. We use the API-merge to respect the branch protection rules.

Step 11 - CI triggered by the change in the branch.

Step 12 - The package is deployed to the Org. On Salesforce the deployment will appear as done by the pipeline owner. After a merge to the environment branch, a webhook is triggered which kicks off propagation on the Pipeline. Propagation is independent of the CI job doing the deployment.

Step 7 - Gearset merges all the selected PRs into a local branch. If there are conflicts between the selected PRs, this step is going to fail with below message:
"We were unable to promote your selected changes due to merge conflicts."

At this point the user can try promoting the changes one at the time, or they can resolve the conflicts manually and try again. Gearset will also offer to proceed with the successfully merged changes:
​
"The promotion failed due to merge conflicts. No changes were made to your branches. You can try promoting the changes in isolation or you can resolve the conflicts manually and try again."
​
"Alternatively, Gearset can try promoting only the successfully merged changes."

Step 8 - Merge conflict check of the local branch against environment branch.

Step 9 - Gearset runs a Validation from the local branch against the Org target of the CI job. This should be validating all the PRs together. Gearset will skip this validation if all the of the following conditions are true:

Step 10 - API-merge of each PR separately into the environment branch. All the merges will appear on the Git provider as done by the same person. We use the API-merge to respect the branch protection rules. After each merge into the environment branch, the related webhook is triggered which kicks off propagation on the Pipeline.

Step 11 - We do our best not to trigger the CI job one time for each PR merged. To be more specific, the CI job is paused while we do the merges and then turned back on at the end to do one deployment only.

Step 12 - The package deployed to the Org. On Salesforce the deployment will appear as done by the Pipeline owner.