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’ you can sync directly to your developer sandbox environment. Easily see how out of sync you 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
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, 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. 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.
If there is a validation error on your deployment, try deploying an earlier update in the order as sometimes this may be important (e.g. earlier update is required in your Dev Sandbox for a successful deployment of any newer update). You may also choose items to deploy on a validation error if you need to manually resolve.
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.
Team owners are able to Clear updates on a developer sandbox from the selection pictured below.
Note: In case 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.
While for a team-shared Pipeline, all team owners on the Gearset team will have access to "Clear updates" on Dev Sandboxes.
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.
