Within Pipelines UI, when your PR (pull request) fails the validation against the target org, Gearset may give you an option to Manually resolve the issue.
What does 'Manually resolve' option allow me to do?
So this option is there to allow you to manually deploy changes from the branch to the target org of your CI job.
And by doing so, we essentially allow you to manually resolve a validation error.
Sometimes validation errors are blockers that don't allow your PR promotion before the error is resolved, and - for example - a fix is added directly to the PR.
Note: When you use this button, Gearset doesn't automatically update your PR or doesn't promote your feature branch (or user story) to the source branch of the CI job (so called long-lived branch).
This is how the option shows up in the Pipelines UI:
When you click on View details (as highlighted in blue), you'd see in Gearset validation error(s) that you need to resolve in order to successfully promote the PR.
What happens after I select 'Manually resolve'?
When you click on Manually resolve, Gearset will run a comparison between your source branch (for example in this case: gs-pipeline/feature/SupportUser) and the target org.
Once the comparison loads up, you'll be able to manually re-select the components you want to deploy to the target org - specifically with an intention to help you resolve a validation error.
It's important to note that if a specific metadata, or its component, needs more advanced edits within the XML code in order for the validation error to be resolved - the Manually resolve option may not be sufficient.
It's because this option only allows you to deploy additional components to the target org with hope that it'd be helpful enough to resolve the error.
Gearset's comparison results doesn't allow users to amend the XML code of retrieved metadata types.
Also, this option will not help you resolve an issue with failing Apex class tests, as it isn't intended for these type of issues.
Permissions needed to run this option.
From the screenshot below gs-pipeline/feature/SupportUser_-_INT is the source branch and Target is the INT Org.
If you are not the owner of this Org connection, you need to have the delegated access from the Owner of this connection as explained here. If this is a Team shared Org, you need to get delegated access from any of the Team owners in your team. Otherwise you will not be able to deploy manually through this option.
When is it recommended to use 'Manually resolve' option?
We want to highlight that Manually resolve button was primarily created to help teams with very large PRs, such as a release from their long-term project.
Why? Because larger PRs are more prone to potentially failing validation due to dependency issues.
How do we help teams resolve such dependency issues?
Simply, by giving users an option to manually choose the order in which they want to deploy the changes from the PR.
This way, we essentially allow you to split your complex deployment into multiple incremental parts (if necessary) to avoid dependency issues and be able to fix validation failures.
This can help with resolving specific Salesforce validation errors (but let's be clear, not all errors).
Example of an issue that can be fixed with 'Manually resolve' option
Below is a a typical scenario that you should be able to resolve with this feature:
When a ComponentA that is included in the PR needs to be present in the target org before ComponentB gets deployed to the same org, but your PR includes both ComponentA and ComponentB.
What happens then?
Firstly, Salesforce API is not intelligent enough to prioritise the deployment of ComponentA before ComponentB is deployed in order to not fail a validation - if we consider the above example scenario where both components are added to the same deployment package.
Manually resolve option allows you to break down your deployment into two stages:
- Deploy ComponentA to your target org.
- Once done, merge the PR (if needed) and let the CI job follow up with org deployment. The deployment package would include the ComponentB, that should not failed on the validation stage.