Flow merge

OrgFlow never copies metadata directly from one Salesforce org to another using retrieve and deploy. Instead, OrgFlow flows metadata changes between through the Git branches of configured Salesforce environments. We call this process flow merge or sometimes merge flow.

Flow merge is essentially a composition of flow in, flow out and Git merge operations:

• A flow in of the source environment
• A flow in of the target environment
• A Git merge from the source environment's branch into the target environment's branch
• A flow out of the target environment

By completing all these operations in combination, the result is that changes in both environment will have been committed to the Git repository, and changes in the source environment will have been safely merged with changes in the target environment, and deployed to the target environment's Salesforce org.

The individual flow in and flow out operations can optionally be skipped depending on your needs.

The following outlines the overall steps of the flow merge process:

1. Worker flows in the source and target environments concurrently
2. Worker merges the source environment's Git branch into the target environment's Git branch
3. Worker flows out the target environment

"Worker" in this context can be either a managed worker in OrgFlow's cloud, or the CLI running on your infrastructure.

While the simplified view is easier to understand, the flow merge process is technically not just two inbound flows followed by an outbound flow. This description is closer to what actually goes on behind the scenes:

1. Worker concurrently makes temporary local clones of repository, one with source environment's Git branch and one with target environment's Git branch
2. Worker retrieves metadata from source Salesforce org to a temporary local folder
3. Worker commits metadata changes to source Git branch
4. Worker retrieves metadata from target Salesforce org to a temporary local folder
5. Worker commits metadata changes to target Git branch
6. Worker merges from source Git branch into target Git branch
7. Worker determines changes in the target Git branch since last flow out and creates a delta archive
8. Worker deploys delta archive to target Salesforce org (or validates if check-only mode was selected)
9. If any components failed, worker repeats steps 7 and 8 while excluding failed components
10. Worker pushes new commits to both environments' remote Git branches (unless check-only mode was selected)

Steps 3 and 4 execute concurrently for improved overall performance.

"Worker" in this context can be either a managed worker in OrgFlow's cloud, or the CLI running on your infrastructure.

Starting a flow merge job

To start a flow merge job using the OrgFlow web app, navigate to the environments page, open the flow dropdown menu and select the flow merge menu item. This opens the flow merge dialog where you configure the inputs and options of the flow merge job:

OrgFlow CLI

To start a flow merge job using the OrgFlow CLI, use the env:flowmerge command.

Many of the available options in the flow merge dialog are self-explanatory. The following sections describe some options in more detail.

Skipping parts of the process

By default, a flow merge includes not only the Git merge from the source branch into the target branch, but also a flow in of both environments before the Git merge, and a flow out of the target environment after the Git merge. This ensures that any new metadata changes flow all the way from the source environment's Salesforce org to the target environment's Salesforce org, in as safe a manner as possible.

You can skip one or more of these steps using the checkboxes next to the diagram at the top of the flow merge dialog:

Option	Description
No source flow in	Skip retrieving new changes from the source Salesforce org; just merge from the current HEAD of the source Git branch.
No target flow in	Skip retrieving new changes from the target Salesforce org; just merge with the current HEAD of the target Git branch. This option may increase the risk of clobber during deployment to target Salesforce org.
No target flow out	Skip deploying the merged result to the target Salesforce org; leave the merged changes in the target Git branch.

For example, to speed up the flow merge job, you might skip the source and target flow in steps if you already know that neither environment's Salesforce org contains any new changes, perhaps because you have just run a flow in job on those environments.

Check only

This options runs the flow merge job in check-only mode. In this mode, the environment's state in OrgFlow's cloud remains unchanged, the committed changes are never pushed to the remote repository, and the deployments to Salesforce run as validation deployments (i.e. Salesforce will validate the deployment but not actually apply the changes to the metadata in the org). The result is a dry run that doesn't impact the state of the environment or Salesforce org in any way, but still allows you to discover potential merge conflicts and errors, and inspect the job result.

Merge options

When the same component has changed in both the source branch and the target branch, it is possible for merge conflicts to occur while merging between the two branches. The merge conflicts option lets you control how OrgFlow should behave when merge conflicts are detected. The use semantic merge option enables metadata-aware merge logic to help avoid some types of merge conflicts.

See merge conflicts for more information about these options.

The allow unsupported API versions option instructs OrgFlow to allow merging metadata into the target branch whose payload API version is not yet supported by target org's platform version. See allowing unsupported API versions in merge operations for more information about this option.

Source and target flow in options

Unless you you selected to skip the source or target flow in steps, you will see an expandable section of the dialog for configuring the options of the source and target flow in, respectively. See the flow in topic for more information about the available options.

Target flow out options

Unless you you selected to skip the target flow out step, you will see an expandable section of the dialog for configuring the options of the target flow out. See the flow out topic for more information about the available options.

Artifact options

These options lets you enable/disable collection of job artifacts during the flow merge job.

The collect retrieved metadata archives option saves the "raw" retrieved metadata archives, exactly as they were sent back from the metadata API before any processing was applied by OrgFlow. This can be helpful when diagnosing issues with the merge flow, for example to understand whether metadata in your repository looks a certain way because of OrgFlow's processing, or because Salesforce simply provided it in that way.

The collect deployment archive artifacts option saves the delta deployment metadata archives, exactly as they were uploaded to the metadata API by OrgFlow. This can be helpful when diagnosing issues with outbound flow, for example to understand the underlying reasons for deployment failures.