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:
Opening a Pull Request to enter the Pipeline
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
Merge conflict check against environment branch. One of two outcomes either
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".
CONFLICTS DETECTED
Conflicts that require manual intervention: Pipelines UI will present the conflicts side by side allowing users to pick line by line which parts they want to keep.
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 4
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.
If we can do semantic merge, Gearset automatically does a merge commit from the environment branch to the promotion branch. To be more specific, we will proactively apply the semantic merge when the PR opens if we determine it can help avoid issues. Whilst the PR is open the conflict will not show in the Pipelines UI, because we know already that we can solve it automatically. However, it will be still possible to see the conflict when logging in to the Git provider
Step 5
If applicable - Users can have additional checks for their PRs in their Git Provider, such as code scanning runs or external checks. Gearset will show that those checks have passed or failed in the 'Reviewers and other checks' > Status checks sub-section.
Users can then proceed with the propagation using their judgement and in accordance with their branch protection rules, such as minimum number of approvals or validation results from Gearset.
Note - Gearset Validation results (as referenced here) will not show up in the Status Checks section, as the 'Validation' is a separate dedicated area in the 'Merge and validation checks' section
Users can then either select a single PR or multiple PRs to continue
Selecting a SINGLE PR
Step 6
Gearset merges the selected PR into a local branch.
Step 7
Merge conflict check of the local branch against environment branch.
Step 8
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:
The CI job's last validation was successful
The comparison results are the same as they were for the last validation
The CI job's test settings haven't changed since the last validation
Step 9
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 10
CI triggered by the change in the branch.
Step 11
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.
Selecting MULTIPLE PRs against the same environment branch
Step 6
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 7
Merge conflict check of the local branch against environment branch.
Step 8
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:
The CI job's last validation was successful
The comparison results are the same as they were for the last validation
The comparison doesn't contain Vlocity objects
The CI job's test settings haven't changed since the last validation
Step 9
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 10
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 11
The package deployed to the Org. On Salesforce the deployment will appear as done by the Pipeline owner.