Why is back propagation needed in Pipeline workflows?
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 (or back promote) changes eases the task of aligning changes across all environments. And, most importantly, it allows developers to work from the most relevant code.
Ultimately, it leads to encouraging more frequent releases and reduces the likelihood of experiencing environment drift and overwriting work.
In promoting your first features article 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 pipeline.
The logic is simple: Gearset allows you to forward and back propagate, automatically creating (but not promoting) PRs on your behalf.
The way you can do this depends on what you’re trying to achieve. Before you go ahead, consider the steps we describe below.
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 updating developer sandboxes.
Others want to keep developer sandboxes equally in sync, which means they require back propagation to sandboxes to be enabled within their Gearset Pipeline.
1.1 Sync lower environments (except developer sandboxes)
If your team does hotfixes and needs to get them back propagated to other environments, but doesn't necessarily need to refresh metadata in dev sandboxes, then a setup similar to Pipeline shown on image below is required.
The tool automatically back propagates changes if they were to be merged straight into higher environments.
Example: A new PR merged promoted through the Pipeline and merged into Main would automatically create a back propagation PR into Hotfix environment.
And if a PR is merged directly into Main branch (i.e. outside the Pipeline), it would also back propagate this change into UAT and INT (so only the static environments highlighted in green).
Retiring back propagation workflow - guidelines
With the retiring back propagation workflow, our original recommendation was to keep the "Enable back propagation (legacy)" option disabled in each Developer Sandbox environment.
For more information on why this was originally recommended, please read the article:
When to enable/disable back-propagation in developer sandboxes?
At present, if you want to implement the recommendation for the legacy back propagation feature, make sure to keep this option disabled in your developer sandbox(es).
1.2 Sync lower environments (including developer sandboxes):
Originally, if your team wanted to keep 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).
Option 1 (soon to be retired workflow)
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 this article.
The main benefits of this setup were a logical flow you could follow from developer sandboxes through to your other environments, and an extra 'quality gate' for merge conflicts or additional checks to happen before we reach the first environment.
Requirements for Option 1 concept to work
Requirements for Option 1 concept to work
This concept 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 this can be achieved in the Pipelines UI:
Select
Add(environment) ->Add static environment->Create new environment/jobFrom there, you'd create a CI job with the source being the sync branch and the target being the developer sandbox. Configure your CI job according to your needs with some important considerations:
Use a specific sync branch for each developer sandbox (example:
dev1_sync). You can easily branch off from any other branch (most commonly from main) by selecting it in the drop down list and then clickCreate new branch from Main.As the target org, select the relevant sandbox (following this example, Developer Sandbox 1).
For these specific CI jobs you can consider unticking the option
Validate pull requests targeting the source branch:If you're happy that the changes are already validated either in the developer sandbox they're coming from (when forward propagating), or in integration/production orgs (when back propagating) - and because the CI jobs you're creating are purely transitionary, you can untick that option to save time.
If you'd prefer to have that validation stage take place for extra assurance, or because you're using that job as a Quality Gate for SCA by ticking 'Fail run if static code analysis issues are detected' (this option is present on the
Deployment gatesstage), we'd recommend that option to be ticked.
Configuration for CI job settings such as "
Synchronization type", or "Different types to deploy" (these are available on theDeployment behaviorpage) as well as for the metadata filter used in the job should match the settings used in your other static environments.After these are saved, you can follow with the configuration of outgoing webhooks.
Repeat this step for each unique developer sandbox.
Follow the setting up your first Gearset pipeline guideline 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 this option disabled" "
Enable back propagation (legacy)" in each developer sandbox (blue environments). 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.
Once PRs are merged into the sync branch, they get deployed automatically to the org. This concept allowed teams with several sandboxes in the Pipeline to keep orgs up to date with a few clicks.
Note: The same setup is the one used in the following scenarios, assuming the need to sync up to developer sandboxes.
Option 2 (also soon to be retired workflow)
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 means 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.
However, there was a small visualisation element to consider, meaning your Pipeline would no longer only flow horizontally anymore, and such setup could be more confusing with many developer sandboxes being present in the Pipeline setup.
Another change in the flow to consider were back propagation PRs - these would be opened to update the associated sync branches (highlighted in black on below image) after a feature has promoted through to the next static environment.
And back propagation would happen even though the feature was already in the sandbox (unless teams were leveraging the Create sync pull request option to completely realign the Git history).
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 these changes make it past developer sandboxes because, for example, there may be dependent cross work.
2.1 Only when changes are promoted into the final environment:
If Master/Main branch is your source of truth and you need to sync your other orgs only after the source of truth branch is updated, follow these steps:
On the Deployment pipelines page click on the cog icon next to your pipeline name, then select Edit pipeline details... and configure "Create back propagation pull requests" to Only when changes are promoted into the final environment.
This means that even if you promote changes from one dev sandbox into the next environment ("Pipeline Integration" in our scenario), you are not yet triggering back propagation of those changes to the other developer sandboxes.
This is because you want to first have the changes tested and merged into production before they're being back propagated.
What's the default behaviour?
Once the PR is merged into main, back propagation will take place and automatic PRs are simultaneously opened to any lower environments in the Pipeline that don’t have those changes (in this case specifically Hotfix and Developer sandbox 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’, rather that having changes back propagating immediately. But it does take longer overall to get all environments back in sync.
Each developer can choose whether to promote changes 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.
To close a PR, you can either click on the environment against which PR is open, or on the PR icon that shows how many PRs are opened against a specific environment:
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 into the Main/Master branch, then follow these steps:
On the Deployment pipelines page click on the cog icon next to your pipeline name, then select Edit pipeline details... and configure "Create back propagation pull requests" to When changes are promoted into any adjacent environment.
What's the default behaviour?
This means that if you promote changes from one developer sandbox into the next environment ('Pipeline Integration' in this scenario), you have the option to start back propagating those changes straight to other developer sandboxes.
Once the PR is merged into 'Pipeline Integration', it forward propagates to UAT. Also a back propagation will take place and a new PR will be automatically created for each adjacent 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 more noise within the Pipeline.
This also allows developers to choose if they want to back propagate the changes, or alternatively close the back promotion PR.