Advance notice: This article describes an upcoming change to how Gearset pipelines behave. This change is not yet live. We expect to release this change to the app on the 9th of November.
This article is for teams that open pull requests (PRs) in their version control system (VCS) and not in the Gearset Pipelines UI.
If you use the Pipelines UI, read Fix Forward: How to edit or fix your features in progress. For a quick, top down view on this change, read Fix forward: what's changing in Pipelines.
The screenshots in this article show GitHub. The same steps apply to other version control systems.
Before you start
Make sure that these conditions are true before you open a fix PR:
Your pipeline uses the expanded branching model - This change does not apply to Gitflow pipelines.
The feature has left its first environment - While the feature PR is open on its first environment, Gearset syncs new commits for you. To update this PR, push a commit to the feature branch.
The feature is not in an active release / bundle - Fix PRs cannot merge into releases / bundles yet. Thus, you cannot use this flow to fix features that are in a release / bundle. Remove the feature from the release / bundle to update the feature PR in isolation, or merge the fix PR separately into production. We aim to offer first-class support for releases and bundles in the coming weeks.
Create and promote a fix PR
Step 1: Commit your fix to the feature branch
Make the fix. Then commit it and push it to the same feature branch that you used for the original feature. Do not create a new feature branch.
Your feature branch shows your changes relative to your pipeline default branch. If you create a new feature branch, two versions of your changes will exist. This can cause merge conflicts if the two versions diverge significantly over time.
Do not force push your feature branch. If you force push and then create a fix, the fix PR contains only the changes in the new version of your branch. It does not revert the commits that the force push removed when it deploys. Therefore we recommend adding new commits to the existing branch, and avoiding changing branch history wherever possible.
In this example, I have committed Update GS_RandomApexTests.cls to my feature branch while a PR for this feature is open against my UAT branch. This change has already been deployed to staging without this new change:
Step 2: Find the stale promotion PR
Gearset will no longer add your new commit to the open promotion PR. In GitHub, the promotion PR (source branch gs-pipeline/<feature-branch>_-_<environment>) will not show this new commit.
In our worked example above, our PR is open against UAT and does not show the latest commit from the feature branch. The promotion PR is now stale, although your version control will not show this.
However, you can confirm if a PR is stale by looking at the commits on the feature branch vs the commits on the promotion branch. If the promotion branch is missing the latest commits from the feature branch, it is stale and needs a fix.
In our example, see the missing Update GS_RandomApexTests.cls commits from the PR open against UAT:
Step 3: Open a PR to the first environment
In GitHub, open a new pull request with these branches:
base: the branch of the first environment in your pipeline.
compare: your feature branch.
Gearset will intelligently detect if a newly created PR has an already existing stale feature PR.
If a feature PR already exists for a feature further down the pipeline and there are new changes on the feature branch, Gearset will create a fix PR.
Otherwise, Gearset creates a regular feature promotion PR.
Important note: Open the PR against the first environment in your pipeline only. Do not open a PR from your feature branch directly to the environment where the stale promotion PR waits. Gearset will see that PR as a duplicate PR for the same feature on the same environment as an existing PR and won’t create a fix.
Step 4: Check the fix PR
Gearset will close your PR and create a new fix PR with source branch gs-pipeline-fix/<feature-branch>_-_<environment>. This is a fix promotion branch and behaves similarly to a feature promotion branch - since Gearset manages this branch, do not edit or delete it directly.
Gearset will recognise that this PR is a fix for the original feature PR. The following will show in pipelines:
The stale promotion PR shows
This pull request is blocked by a fix. Cannot promote until fix PR <number> is merged.The fix PR links back to the promotion PR that it blocks.
A fix PR can contain multiple commits - so it is possible to add multiple fix commits to the feature branch and promote them through the pipeline using only one fix PR. If you commit to a feature branch while a fix for that feature is open against its first environment, Gearset will sync these commits to the open fix PR.
Since fix PRs specifically target a single feature, you should only add fixes to fix PRs that address a specific feature. Otherwise those other fixes will be attached to the wrong feature.
In our example - the fix PR contains just the missing change from the feature. The other changes in this feature have already been merged to Staging, and won’t appear in the promotion branches commits:
Step 5: Merge the fix PR
Merge and promote the fix PR through your pipeline in the same way as other PRs. Each environment has its own fix branch, the same as promotion branches.
Step 6: Check that the fix merged into the promotion PR
When the fix PR reaches the environment where the feature's promotion PR waits, Gearset merges the fix into the stale promotion branch for you. Gearset does not open a new fix PR there. In GitHub, the existing promotion PR now shows the commits from your fix. In Gearset, the promotion PR is no longer blocked, and can now be promoted again.
In our example, see the sync commit from Gearset as it adds the fix commits to the promotion branch:
Step 7: Merge the feature
Now the fix has been synced to the promotion branch - you can promote the PR as normal. Wait for validation to run again and pass. Your fix now moves forward with the feature.
Abandon a fix PR
You can close a fix PR in GitHub. However, the PR remains stale, meaning:
Gearset will not sync the promotion branch with the feature branch
The extra commits on the feature branch are not deployed when the feature merges.
Things to know
Do not merge stale or blocked promotion PRs in your VCS. Gearset blocks promotion only inside Gearset. If you merge the PR directly in GitHub, the fix is not included and the latest changes will not deploy.
Do not change Gearset-managed branches outside Gearset. Do not edit, force push or delete
gs-pipeline/andgs-pipeline-fix/branches. Gearset uses the feature branch as the source of truth for your feature. Thus, Gearset may not keep commits that you add to these branches directly.AI agents and scripts: If an AI agent or a script pushes commits to your feature branches, update its instructions. A push to the feature branch no longer updates the open promotion PRs. After the push, the agent must also open a PR from the feature branch to the first environment.
DevOps Performance Tracking: Fix PRs are treated the same as feature PRs in the DevOps performance and DORA metrics views. We do not mark the features or fix PRs as bugs as part of this process.