Advance notice: This article describes an upcoming change to how Gearset pipelines behave. This change is not yet live - we expect it to be available in the app within the next week.
With fix forward, new commits on a feature branch no longer reach the promotion branch after its first environment. Instead, you create a fix PR to carry them forward and update existing feature PRs. This ensures that all standard changes in your pipeline (excluding hotfixes) are tested at each environment in your pipeline.
As part of this change, we're introducing a new promotion branch naming format (gs-pipeline-fix/{featureBranch}_-_{env}) for fix PRs - please ensure that your repository accepts this branch format as part of its branch protection rules and any automations.
What is this change, and what does it mean for your pipeline?
No more unplanned changes in later environments. New commits no longer flow into every promotion branch automatically regardless of where in the pipeline those features are. Later environments only get the commits you send in a fix PR.
Features can't move ahead without their fix. When a promotion PR is missing commits, Gearset marks it as stale and blocks it. You won't be able to promote a feature to the next environment while its fix is still behind.
Fixes are easier to track. Each fix is its own PR, linked to the feature it fixes. The stale feature PR shows a
Go To Fix PRbutton, and your dev sandbox shows where each of the feature's PRs is and whether it's active, stale, or merged.Less setup for each fix. The fix PR title is pre-filled, and the feature PR's tests and deployment steps are appended to the fix PR automatically.
New Term: Fix PR
This change introduces new concepts to Gearset pipelines, namely the concept of a PR being stale, and fix PRs.
A PR is considered stale if its promotion branch does not contain all the latest changes from its feature branch. To update a stale PR, users will need to create a fix PR and promote this through their pipeline.
A fix PR contains the latest changes from the feature branch at the moment that fix PR is created. This process is designed to enforce keeping lower environments in sync with the latest changes from the feature branch before promotions.
Once the fix PR reaches the same environment that the feature PR is at, the fix PR will update the feature PR, and the feature PR will no longer be stale nor be blocked from promoting to subsequent environments.
Summary of changes: Before and after
The biggest change is how new commits reach a promotion branch. Today, when a commit is made to a feature branch, Gearset syncs this commit to the promotion branch in every environment.
With fix forward, Gearset will only sync commits made on the feature branch to the promotion branch when the PR is open against the first environment of your pipeline.
If a commit is made to your feature branch while your PR is open further down your pipeline, a fix PR will be needed to sync the promotion branch with the latest changes from the feature branch.
Here is a guide on how the behaviour looks before and after fix forward:
| Before fix forward | With fix forward |
New commits for PRs on their initial environment | Synced to the promotion branch | No change |
New commits for open PRs already promoted to a later environment | Synced to the promotion branch | Not synced. The promotion PR is marked as stale (missing latest commits). |
Stale promotion PR before fix PR is created | Doesn't apply | Promotion is possible, but fix changes will not deploy to environment |
Stale promotion PR after fix PR is created | Doesn't apply | Promotion is blocked in Gearset |
When the block lifts | Doesn't apply | When a fix PR merges into the promotion branch |
Tests and deployment steps | On the feature PR | Copied from the feature PR to the fix PR |
What you need to do differently
After a feature leaves its first environment, every new commit to the feature branch needs a fix PR to update the promotion branch with new commits. When a commit has been pushed to the feature branch and the promotion branch is stale, we flag this PR to alert the user that a fix PR is needed:
Here is a quick step by step guide on how to create and merge a fix PR in Gearset with the new flow:
Create a fix PR for any feature whose promotion PR shows as stale. Use
Create Fix PRfrom the stale feature from your developer sandbox in Gearset:
Promote the fix PR through the pipeline. Gearset merges the fix changes into the feature's promotion branch at the environment where the original feature PR is open.
Don't merge stale PRs in your version control system. Gearset only blocks promotion inside Gearset, so a merge done directly in your VCS skips the fix and the promotion gate.
You can find an in-depth guide on how to edit or fix your user stories in progress with fix forward here
Risk: changes can be missed
If you push a fix but don't create a fix PR, that fix doesn't reach later environments. The feature can look finished while the fix is still only on the feature branch.
However, users will be alerted that the changes they have promoted are not included in their PR in Gearset. Additionally, a PR that is stale will not have its feature branch deleted automatically, allowing a new feature PR to be opened with the latest changes.
This risk is highest in these cases:
Teams used to the previous behaviour may expect every push on a feature branch to reach every environment, as it did before.
Merges done directly in your VCS aren't blocked, so a stale promotion PR can be merged without the fix.
Abandoned fix PRs leave the promotion PR stale (missing latest commits). The fix doesn't move forward until you create a new fix PR.
Users with multiple pipelines connected to the same repo may see PRs not syncing on their initial environment if another connected pipeline contains that PR on a non-initial environment.
If you have any questions, concerns or feedback on the upcoming change, please get in touch with our support team via our instant chat.