This document outlines some reasons and troubleshooting steps that users can take to work out why commits being made into the feature branch are not being reflected in the promotion branch.
Glossary of important terms
Glossary of important terms
Feature branch - This is the original branch that is created, where all the features are originally added into.
Promotion branch - These are the branches that are automatically created by Gearset. These are preceded by gs-pipeline/
Expected behavior
When adding a commit to a feature branch, Gearset will automatically add these commits into any promotion branches linked to that feature branch.
In this example we have the branch Feature-1. With a PR opened to UAT.
Adding a commit to the original feature branch will automatically update the promotion branch so that they are aligned.
Note: Adding a change to the promotion branch will not update the feature branch.
What factors can prevent successful branch syncing?
Releases:
When updating a feature branch, where the promotion branch is in a release, Gearset will not automatically sync that promotion branch. If that branch needs updating then abandon the release and update the feature branch, this will update the promotion branch which you can then add back into the release.
Merge conflicts:
We have seen issues where users are adding commits to a feature branch and those commits are not being synced to the promotion branches. For this to happen the users will have followed the following steps:
Creates a feature branch - commit changes, creates a PR to next Environment.
PR has a merge conflict on a file that needs to be solved.
Accept the Environment changes, mark as resolved and commit merge.
Go back to the feature branch and commit more changes.
Then we try and merge the feature branch into promotion branch.
5.1 If we notice any merge conflicts, we try and run a semantic merge automatically.
5.2. If it succeeds, then we push a commit to promotion branch, something like:Gearset: Synced feature branch. Merged feature branch X into promotion branch Y.if the change that you commit also forms a merge conflict with the file that you have selected, then this will not be updated in the promotion branch.
The feature branch has been updated, but the promotion branch does not contain this commit.
To address this issue, we have introduced a feature that ensures the promotion branch remains in sync with the original feature branch. If the promotion branch falls out of sync, we automatically reset the promotion branch and derive directly from the feature branch. This approach guarantees that the promotion branch always mirrors the most recent updates from the feature branch, thereby preventing discrepancies that could result in an unintended deployment of incomplete or outdated changes.
This is an example of the PR comment added to the Git when this happens.
This branch has been overwritten with the latest changes from the X branch due to merge conflicts arising from direct commits to this branch
We utilize forcepush permissions in Git to update the promotion branch to match the original feature branch like the example above. However, there may be instances where this process fails due to factors such as insufficient user permissions, branch protection rules, or impending version control system issues.
If the automatic synchronization fails, you will see a new webhook error in your pipeline:
Updating all promotion branches to include the latest changes from the feature branch, as it has changed on remote
In that case, following steps can be taken as a workaround.
Workarounds
If you are unable to promote changes in the pipeline due to this, then the easiest way to workaround this is by closing and re-opening the PR.
To do this:
Ensure that the Auto-delete feature branches is unchecked, this will ensure that the feature branch is not deleted.
In pipelines find the PR that you are wanting to use this workaround on.
Before closing this PR, make sure to take note of the feature branch name.
Once you have the feature branch name, you close the PR using the bin icon.
Open your git provider and find the feature branch (in my case Feature-Dev2-Onboarding)
Open a PR from that feature branch to the long lived branch where the feature was last stuck at. In this example we are using GitHub, please consult your git providers documentation on how to do this if you are not using GitHub.
The PR should now be in the pipeline again ready to be promoted (Note: the name seen in Gearset will be the name of the PR that you created)
The promotion branch is now up to date with the most recent commits from the feature branch.