Salesforce environments constantly change as you build features, deploy them, and release them to your production org. Sometimes a hotfix is what you need to release quickly and skipping parts of the release pipeline is needed. Over time, more and more metadata differences between your environments begin to appear.

Being able to back-propagate changes eases the task of aligning changes across all environments and allows developers to work from the most relevant code. Ultimately it encourages more frequent releases and reduces the likelihood of experiencing environment drift and overwriting work.

Here we guide you on how to forward propagate your changes with our pipelines solution. Let’s now look at how you can get your orgs synced and automatically make merged changes available for promotion to lower environments in the release pipeline.

The logic is simple: Gearset allows you to forward and back-propagate, automatically creating PRs on your behalf. But the way you can do this depends on what you’re trying to achieve. Before you go ahead, consider:

1. Where do I want changes to be propagated to?

Some teams do occasional hotfixes and want to keep all lower environments in sync and aren't concerned with developer sandboxes; others want to keep developer sandboxes equally in sync.

1.1 Sync lower environments (except developer sandboxes):

If your team does hotfixes and needs to get them back-propagated in other environments but doesn’t regularly need to refresh metadata in sandboxes and is not looking into keeping this automatically deployed because it is up to each individual, then a setup similar to this image is what is needed. The tool automatically back-propagates changes if they were to be merged straight into higher environments. Example: A new merged PR into main would automatically create a PR backwards into Hotfix and into UAT, and so on.

We highly recommend keeping the toggle off for ‘Back-propagation disabled’ in each developer sandbox. For more details on this recommendation please read the article When to enable/disable back-propagation in developer sandboxes? For now, if you want to implement this you'll click in your sandbox environment and switch it off.

1.2 Sync lower environments (including developer sandboxes):

If your team wants to keep sandboxes in sync, you’ll need to have extra static environments (CI jobs) that facilitate the automation of this process. It should look similar to this (adapted to your environments):

This requires having a sync environment (CI job) between your developer sandbox(es) and your first static environment. For each dev sandbox you would have one CI job automating the deployment of changes from a sync branch into the developer org. Here's how you can achieve this:

  • Add environment -> add static environment -> Create a new environment/job

  • Now create a CI job with the source being the sync branch and target the developer sandbox. Configure your CI job as you want but some things you need make sure:

    • Use a specific sync branch for each developer sandbox (example: dev1_sync). You can easily branch off from any other branch (mostly common from main) by selecting it in the drop down list and then click 'Create new branch from SelectedBranch'.

    • Select as target the relevant sandbox (following this example, dev sandbox 1).

    • For these specific CI jobs you can untick the option “Validate pull requests targeting the source branch” as the changes are already validated either in the developer sandbox that it is coming from (when forward propagating) or in integration/production orgs (when back-propagating) and it will save you time.

    • 'Synchronization type', 'Different types to deploy' and metadata filter selections match the settings used in your other static environments.

    • Once saved you 'Add webhook' in 'Create a webhook automatically.

  • Repeat for each developer sandbox.

  • Use this guide to have them added to your Pipeline and linked correctly (see above image for reference). Make sure each one is linked from their developer sandbox and all link up to the first static environment.

  • Just as in the example before, we recommend keeping the toggle off for ‘Back-propagation disabled’ in each developer sandbox (blue boxes). More details on why here.

This setup means that if changes need to be back-propagated to developer sandboxes, whether from hotfix environments or changes promoted from the other dev sandboxes, there are CI jobs in place to receive them through a PR into the sync branch and once merged they get deployed automatically to the org. This enables teams with several sandboxes to keep them up to date with a few clicks.

Important: Because each extra static environment is a CI job, each of them uses an extra webhook. Some git providers (eg. GitHub) have a max. of 20 webhooks. Larger teams with a high number of developer sandboxes may hit this limitation, and this approach wouldn’t be suitable. If that’s the case, please reach out to discuss your use case and we can help you get set up.

Note: This same setup is the one used in the following scenarios, assuming the need to sync up to developer sandboxes.

2. When do I need back-propagation of changes to happen?

Some teams want to back-propagate changes only after a feature is tested and merged into master, whilst other teams have longer sprints and want changes back in their developer sandboxes as soon as they make it past developer sandboxes because there is dependent cross work.

2.1 Only when changes are promoted into the final environment:

If master is your source of truth and only when it is updated do you need to sync your other orgs, click on the settings cog next to your pipeline name, open 'Edit Pipelines' and select this option.

This means that even if you promote changes from one dev sandbox into the next environment (integration in our scenario), you are not yet bringing those changes back to the other developer sandboxes, as you want them to be tested and merged into production first. Once the PR is merged into main, back-propagation will take place and automatic PRs are open to any environments that don’t have those changes (in this case, Hotfix and developer 2 sync). This is what happens (blue arrows represent the back-propagation):

The benefit of working this way is that waiting for changes to go to production makes less ‘noise’ of things back-propagating immediately, but does take longer overall to get things back in sync.

Each developer can choose whether to promote them when needed or if unnecessary they can just close the PR. Just tap the PR and in the cog on the right they can close it.

2.2 When changes are promoted into any adjacent environment:

If the way you work requires your developer sandboxes to be refreshed before changes are completely integrated in main, click on the settings cog next to your pipeline name, open 'Edit Pipelines' and select this option.

This means that if you promote changes from one developer sandbox into the next environment (integration in this scenario), you have the option to now start integrating those changes straight back to other developer sandboxes. Once the PR is merged into integration, it forward propagates to UAT but also a back-propagation will take place and a new PR will be automatically created for each sync environment that does not contain those changes yet.

The benefit of working this way is that changes sync up a lot quicker in lower environments but can cause a lot of noise.

And again, each developer can choose whether to promote them when needed or if unnecessary to just close the PR.


If you've found this article helpful, confusing, or just have questions, don't hesitate to get in touch and one of our team will get right back to you.

Did this answer your question?