Example: You’ve started your user story and have opened your PR against the first environment, Integration (INT), but it's failing validation due to some missing components. You need to add these missing dependencies (E.g. a custom field) before being able to successfully validate and promote.

Note: The rest of the document follows the above scenario for adding missing components in or changing existing items. If it turned out that you actually needed to remove items (E.g. reducing the scope of that feature and removing components such as a new field), you'd follow the same process except for the initial Compare & Commit where you'd be selecting a deleted item instead to remove it from the feature branch. For any environments where that component has already been deployed, Gearset would then conduct a deletion as part of the deployment (as long as 'Deleted Items' are ticked in your CI Job settings)

If your missing custom field doesn't already exist, develop it within your developer sandbox as mentioned above and when it's ready in the sandbox, using Pipelines commit the field to the same feature branch that you already opened the PR from.

Once the additional components are committed to the feature branch, you don’t need to open a new PR into the first environment (which in this scenario is INT). Gearset will already detect that a PR is already open and won't allow you to, as per this screenshot.

This means that, after committing, Pipelines will automatically update the PR previously open against INT (on branch gs-pipeline/[feature name]_-_INT) with the new commits, and rerun the merge conflict checks. You can see the new or changed items showing under "Changes in this PR".

If the Validate pull requests targeting the source branch setting is enabled for the continuous integration (CI) Job, the validation checks will also rerun. Which in this scenario this time should now succeed as you’ve added the missing dependency that originally failed the validation.

Your branch is now viable, you can safely proceed with promoting your PR forward into INT when ready. This kicks off the CI job to deploy those changes to INT org and automatically creates a new PR now waiting to be merged in UAT.

Now let’s look at a slightly different scenario.

Example: Only after merging and testing in INT we realise that changes need to be made to the user story and more permissions need to be added to the permission set, before merging in UAT.

Firstly, you’d need to have developed the fix in your sandbox and add the changes to the correct branch, and make sure that the new changes (the permissions, in this case) get committed to the existing feature branch.

Any new commit into a pre-existing feature branch, will automatically update any open PRs. In this example there is a PR open against our second environment, UAT. Your new commit will have resolved the issue of missing permissions, however, we don't want to promote that PR yet.

It's very important to note that these permissions aren't yet present in the INT environment, so they've not been integration tested. Before promoting to UAT, it's important that we get them into INT before proceeding further.

For this reason, we should leave the existing PR currently open against UAT untouched for now.

In your Pipeline, click in the Dev SB environment you’ve just used to commit to the same feature branch, and you’ll see that the branch has changed with ‘Changes in this branch’. This is telling you what has changed in the branch since last time you opened a PR into the next environment (INT in our case). You’ll only see the extra commits, because the existing ones where already merged.

From here we hit Create pull request; this will create a new PR into the next environment so that those changes are being correctly propagated through the pipeline.

We can then check again that the PR has passed the validation and merge the PR into the INT branch. Gearset will then repeat and deploy those changes into the INT org.

Once this has been successfully promoted it will be in the INT branch as well as the INT org. From here you're ready to begin your integration testing (where needed) on the additional components/commits. Once you're satisfied it's now ready for UAT, move onto the next step.

Because you already had a PR open from the same feature branch against the next environment (UAT), Gearset knows that, so won't automatically create a new PR as we'd normally do.

As described in 2.2, once the additional components were committed to the feature branch, Pipelines will automatically update the PR previously open against UAT (on branch gs-pipeline/[feature name]_-_UAT) with the new commits, and rerun the merge conflict checks. You can see the new or changed items showing under "Changes in this PR". If the Validate pull requests targeting the source branch setting is enabled for the continuous integration (CI) Job, the validation checks will also rerun.

Note: If there are branch protection rules set up in the VCS to un-approve the PR if extra commits are added, the PR will need to be re-reviewed here before its mergeable.

Now that our changes are merged and tested positively in INT, the PR can be merged with UAT branch without any additional input needed. You have now added features and fixes to the user story while the features are in flight.

This kicks off the CI job to deploy those changes to the UAT org and automatically creates a new PR now waiting to be merged into the next environment (Main in our case).

Now let’s look at another slightly different scenario.

In this scenario we have a user story waiting to go into Main but it has failed the UAT testing (manual or automated), so needs to be updated accordingly before continuing. This is urgent, and you want to accelerate the process for the UAT team to re-test it as soon as possible. To this end, you want to skip the INT environment for now, whilst being diligent that things work as expected in UAT.

These steps will highlight how to complete this, bearing in mind that as it's not recommended, some steps need to happen outside of your Gearset Pipeline. This is what allows you to bypass certain environments.

Firstly, you’d need to have developed the fix in your sandbox and add the changes to the correct branch, and make sure that the fix or new changes get committed to the existing feature branch.

Pipelines guides you to follow your user stories from left > right sequentially, therefore now you won’t create a new Pull Request to the first environment branch (INT in this scenario) because you’ve decided that you want to skip environments for now.

After committing to an existing feature branch, Gearset will automatically update any open PRs with the extra commits in that branch. In this example there is a PR open against Main (on branch gs-pipeline/[feature name]_-_MAIN). Your new commit may have resolved the issue, however, we don't want to promote that PR yet.

If that updated PR was to be merged now into Main, you’d update your Main and kick off a deployment to Production. It's very important to note that these fix isn't yet tested in any environment, and without re-doing the necessary testing the fix is not ready to be merged into Main.

Also, on merge, Pipelines would realize that INT and UAT are missing a commit and automatically open back propagation ‘Sync’ PRs to align everything together (depending on your Back Propagation settings). However, since testing is needed in UAT before promoting anything to Main, let’s get the fix in UAT first.

For this reason, we should leave the existing PR currently open against Main untouched for now.

For this, you’ll need to go to your version control system and manually open a PR from your original and now updated feature branch into your UAT branch (or whatever environment branch you’re trying to fix, that is not the first in line in your Pipeline).

Just create the PR and go back to your Pipeline.

When open, this new PR will now show up in your Pipeline awaiting in UAT and should only show the extra commits added to the feature branch, since that’s the delta vs UAT, and be auto converted into a promotion branch for UAT (gs-pipeline/[feature name]-UAT).

That PR is reviewed as usual and can be promoted in the Pipeline, which will then trigger the CI job to deploy the extra commits into UAT sandbox, and allow testing to begin in there. The UAT testers can now retest your feature in the UAT sandbox and feedback any further failures or a pass result before you continue.

Gearset won't automatically create a new PR to the next environment (Main in this case) as we'd normally do, because you already had a PR open from the same feature branch against that next environment (Main).

Instead, as described in 3.2, once the additional components were committed to the feature branch, Pipelines automatically updated the PR previously open against Main (on branch gs-pipeline/[feature name]_-_Main) with the new commits, and rerun the merge conflict checks. You can see the new or changed items showing under "Changes in this PR". If the Validate pull requests targeting the source branch setting is enabled for the continuous integration (CI) Job, the validation checks will also rerun.

Note: If there are branch protection rules set up in the VCS to un-approve the PR if extra commits are added, the PR will need to be re-reviewed here before its mergeable.

If the feature passed testing in UAT, you now can feel confident about the updated PR against Main. Now that our changes are merged and tested positively in UAT, the PR can be merged with Main branch without any additional input needed. You have now added features and fixes to the user story while the features are in flight bypassing an environment due to some urgency.

Once merged into Main, this kicks off the CI job to deploy those changes to Production and it is also back propagated (fully, with all relevant commits) to any remainder environments that does not have the extra commits for the fix (INT in the scenario described).