Note: For customers migrating from the legacy workflow for synchronizing developer sandboxes using static environments, read this article on how to make the move: Migrating from legacy back propagation to Developer Sandbox Updates
Why use Updates to keep your developer sandboxes in sync?
Track promotions to your source of truth (base branch) as ‘updates’, which you can sync directly to your developer sandbox environment. Easily see how out of sync your environments are.
Sync all pending ‘updates’ to your developer sandbox in one go - if possible.
Maintain the order in which promotions were merged into your base branch to handle dependency related issues.
Never lose your work in progress. Automatically detect work in progress, including uncommitted items in your sandbox, that may be impacted by the update.
Point-in-time saving and protection for your affected work in progress to allow merging with incoming items from synchronizing.
Enabling Updates on your developer sandbox
Prerequisites to enabling Dev Sandbox Updates feature:
Before enabling Updates on your developer sandbox environments, we recommend that you ensure your developer sandbox is as up to date with production, or your base branch as possible.
If you are an existing customer using the legacy workflow for synchronizing developer sandboxes using static environments, read this article on how to make the move.
You also must have deployment level access to the sandbox in question or be a Team Owner to use this functionality.
By default, Dev Sandbox Updates will be enabled for all new developer sandbox environments added to a pipeline.
For those not automatically enabled, click on the developer sandbox environment, navigate to the Updates tab and click Enable updates.
You can also use the toggle to disable/enable updates for a specific Sandbox. Pictured below Enable updates option.
Now any promotions merged into your base branch will appear on your developer sandbox as Updates - you can deploy these back to your developer sandbox.
No additional set up of Git branches or CI jobs is required for this functionality.
Updating your developer sandbox
Once you've enabled updates on your developer sandbox environment in Pipelines, Gearset will track promotions, or merge commits, happening to your default base branch you've set in your pipeline settings (where features branches are created from). This is usually main or master branch, but your base branch may be an earlier branch when using Projects or other branching strategies.
By default, all pending updates are selected to be deployed directly to your developer sandbox together in one go.
Each promotion (merge commit) to your base branch is presented as one update you can deploy, e.g. an entire release is one update when using Developer Sandbox Updates.
All you have to do is click Update now to kick this off.
If you need to deploy a particular update before the others due to dependencies or validation errors, then try selected ‘up to a point’ in the order as below.
Once the update has started, Gearset will run some preparation in the background to identify work in progress in the sandbox that will be affected by the update. This is done point-in-time from the target sandbox to ensure you never overwrite your work in flight.
At this point Gearset will capture the work in progress relevant to the update from the sandbox, even items not yet committed, and will initiate a merge.
If there are no conflicts with your work in progress, the update will continue to deploy to the target sandbox.
If there are conflicts but Gearset is able to use semantic detection to handle the conflict, the update will continue to deploy.
If there is a true conflict we cannot resolve, you will be able to make the resolution yourself using Gearset’s merge conflict resolution UI, before committing the merge to continue the deployment.
With any conflicts resolved, the items will be deployed directly to your developer sandbox.
Resolving validation errors on Sandbox updates
If there is a validation error on your deployment, try deploying an earlier update in the order, as opposed to selecting multiple updates for deployment to your Dev org.
Sometimes the order of your updates may be important (e.g. earlier update is required in your Dev Sandbox for a successful deployment of any newer update).
You can also choose Select items to deploy option (screenshot below) - this allows you to manually select the items you want to deploy to your Dev org. This way you can skip metadata items that are causing the validation error, and instead deploy only the items that didn't error.
All deployments will be recorded in your Deployment history.
At times you may want to refresh your developer sandbox or clear your updates to start tracking a new point in your base branch.
Can I amend the Problem Analyzer template used for the Dev Sandbox Update?
Yes, this is possible. Problem Analyzer template used for your Dev Sandbox Update is the same template that is configured in the CI job that is directly linked with your Dev org - usually, this would be the first static environment (CI job) in your Gearset Pipeline.
But why would you want to do this, and how can it help with resolving validation errors?
Sometimes Gearset users are able to resolve certain validation errors by applying amendments to their Problem Analyzers templates used during the CI deployments.
For example, if you were able to resolve an error during forward propagating your changes simply by amending the Problem Analyzer template for your CI jobs, you may want to apply the same troubleshooting method during your Dev Sandbox Update.
Who can "Clear updates" on Dev Sandboxes?
Team owners are able to Clear updates on a developer sandbox from the selection pictured below.
Who can clear updates in user-owned Pipelines?
In terms of user-owned Pipeline, it is an expected behavior that only the Pipeline owner can "Clear updates" for any Dev Sandbox within the Pipeline - all other users (including team owners) will see this option being greyed out.
Who can clear updates in team-shared Pipelines?
For a team-shared Pipeline, by default all team owners on the Gearset team by have access to "Clear updates" on all Dev Sandboxes.
Can team members clear updates on their own Sandboxes?
This is possible to configure for both user-owned and team-shared Pipelines.
Access to clear updates can be granted to team members via Allow team members to clear updates option in your Pipeline settings. This allows team members to clear updates only for their own Sandbox(es).
What do the Icons in Developer Sandboxes mean?
Circular Arrows Icon: This indicates that there are updates ready to sync showing the number of updates pending on the left side.
Yellow Exclamation Mark (!): This appears when there are 5 pending updates. It serves as a reminder that updates should be applied soon to keep it sync with your base branch.
Red Exclamation Mark (!): This appears when the number of pending updates reaches 10 or more. It indicates that updates are now critical and should be applied as soon as possible to avoid potential issues.
