What was the legacy workflow recommendation for keeping developer sandboxes in sync?
Originally, if your team wanted to keep developer and hotfix sandboxes in sync, you needed to have extra static environments (CI jobs) that could facilitate the automation of the syncing process.
It would look similar to one of below diagrams (adapted to your environments).
Approach 1
This model shows the sync CI jobs in-between the developer sandboxes and the next environment (Pipeline Integration) to which changes are promoted to. This is the baseline model described further down
Approach 2
Second alternative (image below) was to configure the sync CI jobs in the same way.
However, instead of them sitting in-between your developer sandboxes (as on the image above), and the next environment (e.g. Pipeline Integration) - the CI jobs would sit vertically alongside your developer sandboxes.
This meant you would have 1 less merging (or promotion) step in your Pipeline workflow, which essentially would contribute to much quicker forward promotion of new features to other Pipeline environments.
Why use developer sandbox updates instead?
You will no longer need to maintain a long-lived branch per developer sandbox.
You will be able to synchronize your sandbox directly with promotions happening to your base branch (usually main, or an earlier branch in long term project workflows), which are tracked as ‘Updates’ on your developer sandbox.
You will no longer have to review and resolve errors or conflicts on all individual back promotion pull requests, as you can take updates directly from your base branch in one block.
The order in which promotions went out to your base branch is maintained when updating. By default, all updates will be selected to deploy to your dev sandbox in one go; you can deploy up to a point in the order if needed to.
Work in progress in your developer sandbox, even items that have not yet been committed, will be protected when synchronizing. Point-in-time, Gearset will detect and capture your work in progress from your developer sandbox that will be affected by the update, allowing you to use Gearset’s merge conflict resolution UI to merge with changes coming back without overwriting critical work in flight.
How to make the move
Retiring your sync environments and CI jobs
When transitioning to using dev sandbox updates from the sync CI job workflow, the first thing you’ll need to do is to retire your sync CI jobs related to developer sandboxes, pictured earlier in this article.
Note: You may want to test the new developer sandbox updates functionality in isolation before making the full transition. If this is the case, use the information below to disable one sync CI job and test developer sandbox updates on that environment first.
Step 1: Ensure your developer sandbox is in sync with Production or your base branch.
If possible, a sandbox refresh will be the best way to cleanly bring your developer sandbox completely up to date.
If that’s not possible, you can open a Sync PR on your sync job and merge that to bring your org in line with your base branch, or you can promote any open back propagation PRs that are outstanding on each developer sandbox sync job.
If you plan to refresh your developer sandbox to bring it up to date before enabling the new functionality, you can close all of the open PRs in your version control system directly.
Step 2: Disable your developer sandbox sync environments/jobs.
Click on each developer sandbox sync environment in your pipeline to navigate the side panel. Disable each CI job by toggling the job enabled/disabled toggle in the top right hand corner.
Step 3: Delete developer sandbox sync environments from your pipeline view.
Head to the top right corner of your pipelines screen and click Edit environments. From here, click on the trash can icon on the sync CI job in question to Delete environment.
This will not delete your underlying CI job! Instead, you'd only see it removed from the Pipelines UI as an environment.
Step 4: When ready, delete the underlying sync CI jobs and associated branches.
Head to the CI dashboard view to locate your sync CI job.
Locate your developer sandbox sync CI jobs. Search for their names in the filter to make this easier.
You may want to just disable the jobs and keep them for a period of time to reference information contained in the job histories, if you need to.
However, when you are ready and the job history is no longer needed, you can retire the job fully by clicking Delete... . At this point, it’s recommended to also delete the associated branch in your version control system.
Enabling updates on your developer sandbox
Now that you have retired your sync environments and CI jobs related to developer sandboxes, we recommend that you ensure your developer sandbox is as up to date with production or your base branch as possible.
Step 1: Reconnect your developer sandbox environments directly to the next stage of the pipeline by clicking Edit environments and reattaching them.
Step 2: Click on the developer sandbox in question, navigate to the Updates tab and click Enable updates.
You can also use the toggle to disable/enable, pictured below.
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.
For more information on how the solution works, head to the Developer Sandbox Updates article here.