All Collections
Gearset Pipelines
Troubleshooting
Rollback with Gearset Pipelines
Rollback with Gearset Pipelines

Three methods to correctly revert a change with Pipelines.

Antonio Sale avatar
Written by Antonio Sale
Updated over a week ago

SCENARIO: The ‘Feature 1’ moved downstream on Pipelines from DEV to SIT to UAT. The Feature is merged into the UAT environment branch. This triggers the CI job and the 2 fields DiscountPercentage_c and DiscountRate_c are deployed to the UAT org. A PR is automatically opened against the next environment.

At this point the team realises that the ‘Feature 1’ is not working as it should, or that it is not needed anymore. They want to roll back starting from UAT. There are 3 ways to correctly revert with Gearset Pipelines. The choice depends on what the user wants to do after the reverting of the PR.
​

Important note: When doing a rollback, ensure that the auto-delete feature branches checkbox is unchecked. Otherwise the original feature branch will be deleted.
​

Option 1

The user wants to continue working on their feature branch (apply a few extra commits to resolve the issue and continue from there). This option requires work from the VC provider or command line.

  • Firstly, they need to close any promotion PRs which have been automatically opened downstream and upstream, related to the feature branch ‘Feature 1’. These are now redundant/unnecessary since we're going to be reverting the change

  • On the UAT environment where the user wants to revert the changes, open up the VC provider (GitHub, GitLab, Azure etc.) and find the promotion PR with ‘Feature 1’. Click the revert button, and merge this change in the UAT branch(*).

  • Gearset might propagate(**) to the upstreams/downstreams. Close all of the propagated PRs! (The reasoning is that we never want to propagate changes coming from a promotion PR)

  • Now go to the next upstream environment where the change was merged, and repeat the steps above.

Important notes:

  • Option 1 won't touch the original feature branch, which means once they have reverted the changes from all of their environments, they can re-use the feature branch, apply a few extra commits to resolve the issue and open a PR against the first environment branch in the Pipeline).

  • It's important they don't merge anything which we end up propagating as part of this revert, this might cause issues down the line

  • If the 'revert' button is disabled on the VC provider, the user can proceed manually. They'll need to create a new branch and revert every relevant commit which was on the promotion branch ‘Feature 1’. Then create a PR using this branch against the environment branch. They'll need to do this on all of the environments with the feature to revert.

  • (*) There are some providers like CodeCommit which don't support reverting. The revert button also only works for the 'simple' cases: if Feature 1 is merged, then Feature 2 expands on Feature 1, it’s not going to be possible to revert Feature 1 (the VCS or the CLI will return an error message, saying that the action cannot be done).

  • (**)Currently there are some inconsistencies between the various VC providers when reverting a PR:

    • For GitHub, the revert prefixes revert- before the source branch name

    • For Azure DevOps, the revert branch is configurable but defaults to suffixing -revert-from-{target_branch} after the original source branch name

    • For BitBucket, the revert branch name is configurable but defaults to revert-pr-{original_pr_number}

    • For GitLab, the revert branch name defaults to revert-{merge_commit_hash}

This means for ADO/BB/GL when the user reverts a PR (clicking the ‘revert PR' button on the VC side) it will create a ‘feature’ PR which then Pipelines will close and create a Promotion PR.
​

For GitHub when the user reverts a PR, Gearset ends up treating the new branch as a Promotion branch, therefore we won’t close/recreate the PR (like we do for ADO/BB/GL). What this means is that on Gearset Pipelines they would still need to convert before promoting, but on the VCS side they could still merge this in.

Option 2

Revert as Hotfix. This is probably the way to go for users that are not very familiar with Version Control, with the VC provider, or simply prefer to do everything from the Gearset interface.

  • Firstly, they need to close from the Pipelines UI any promotion PRs which have been automatically opened downstream and upstream, related to the feature branch ‘Feature 1’. These are now redundant/unnecessary since we're going to be reverting the change

  • Rollback the run of the CI job that brought ‘Feature 1’ to the org (UAT in our scenario), from the CI job history. This would remove DiscountPercentage_c and DiscountRate_c from the UAT org only.

  • Find the rollback in the metadata deployment history, and click on Clone Package. In our scenario, the source is going to be the UAT org, the target is a new Hotfix (feature) branch created from the UAT branch. Clone Package will automatically select the items that were previously rolled back: commit the same changes to the Hotfix branch.

  • Once the changes are committed, create a PR against the UAT branch. Gearset will close this PR and open a new PR from a promotion branch. The new PR will appear on the left side of the UAT node, on the Pipelines UI.

    • IMPORTANT: It is very likely that you have set up Pipelines with Delta CI jobs. This type of jobs will use a cached version of the UAT org when validating this PR, and this will cause the validation to fail because in the cached version the rollback has never happened. We are aware of this limitation and the current workaround is to manually hit the CI run button.

  • Promoting the PR we will remove DiscountPercentage_c and DiscountRate_c from the UAT branch. The CI job will be triggered, but it will not pick any changes because the fields have been already removed from the UAT org in the previous steps.

  • The merge will also trigger propagation downstream and upstream:

    • Downstream( ex: Main): it is important to close this PR without merging. The Hotfix branch was created from UAT so it will include all the features that have reached the UAT. Merging the PR would be the equivalent of merging the entire UAT (as it was when the hotfix branch was created) into Main.

    • Upstream (ex: SIT) promoting the changes will remove DiscountPercentage_c and DiscountRate_c from the branch, triggering the CI job that would remove them from the SIT org.

This is how a workflow with short-lived Hotfix branches would look like:

Important notes

  • Back propagation (moving the rollback upstream) will work only if the Deleted Items are included in the CI job settings.

  • Back propagation will be triggered at different stages, depending on your Pipeline settings:

If the option selected is “Only when changes are promoted into the final environment”, the PR against SIT in our example will need to be opened manually, as we are not promoting the Hotfix downstream into the final environment (Main).

Option 3

The user is happy to revert from their VC provider all of the commits on their original feature branch ‘Feature 1’, this will mean they'll start from a fresh / brand new feature branch. For a detailed walkthrough of this option, please refer to this article.

  • Firstly, they need to close any promotion PRs which have been automatically opened downstream and upstream, related to the feature branch ‘Feature 1’. These are now redundant/unnecessary since we're going to be reverting the change.

  • Then they need to go on their feature branch, revert all of the commits in sequence which make up the Feature 1 in the feature branch. So if the branch had commits a-b-c they now should have a branch with commits a-b-c-^c-^b-^a (where ^ is the revert). The 'changes' of this branch should be '0' / empty (the reverting of each of the commits should be done in reverse order)

  • They now need to manually open a PR using the feature branch against the last environment where the promotion branch was merged (in our example the UAT branch, the place where they want to revert changes). Gearset will automatically close this PR, create a promotion branch, and open a new promo PR. They should now merge this promo PR.

  • Gearset will now propagate the revert to the upstreams and downstream.

  • In the upstreams, the PR should correctly show the 'reverted changes' (since all the upstreams should have already had the change merged into it). Merge the PRs into the upstreams. If the upstream didn't have the changes, they can safely close this PR, since there is nothing to revert.

  • In the downstreams, the PR will show '6' commits, but no changes. You can safely close this PR, since the feature never made it to the downstream.

Important notes

  • Back propagation (moving the rollback upstream) will work only if the Deleted Items are included in the CI job settings. We also recommend setting up your Pipelines with Delta CI jobs.

  • This method will not be picked up by the reporting API as a failure.

  • Back propagation will be triggered at different stages, depending on your Pipeline settings:

If the option selected is “Only when changes are promoted into the final environment”, the PR against SIT in our example will be opened only when the rollback PR is merged into Main (read more here).

Did this answer your question?