This feature enables users to branch out multiple versions of an org, for the purpose of testing new workflows or for different workstreams (one team is working on new products, while other teams are finalizing an MVP). The feature is not currently enabled by default, and requires special access to enable from the Org Features page.
Enable the Branching Feature
Once enabled, the users may need to refresh the tabs in order to see it take effect.
The branch UI will show up only on the Catalog, Asset, Stages, and Renders pages, listed at the top of the page.
Access the Branch UI
From this UI, users can create a new branch by clicking on the Create New Branch entry in the main branch UI.
Creating a new Branch
New branches will always be clones of the main branch. It is not possible to make new branches of other branches.
The main branch UI can also be used to switch between the branches.
Switching to another branch will always take the user to the Catalog Items listing. The reason for this is because the user may has the potential to be on an asset page that does not exist in the target branch.
Click on the View Changes entry in the main branch UI dropdown to access the Merging and Changes page.
Access Branch Changes
Branch Changes Page
On this page, users can access the following features:
- Preview changes made on the current branch
- Update the current branch with changes made in the main branch - Pull operation
- Merge the current branch back into the main branch
In order to perform a merge operation, the users must first bring the current branch up to date with a pull operation, which will pull any changes made in the main branch into the current branch.
Users can access the Branch Management page through the Branch Management entry in the main branch UI.
Access Branch Management
The Branch Management Page
On this page, users can either delete branches or switch to the Merging and Changes page.
- The Orders, saved Configurations, and Custom Apps or Webhooks are not managed by the branching system. They only exist at the top org level, and are thus always available in all branches of that particular org.
- New API functionality is now available that enables developers to target data in specific branches. Already existing Custom Apps and webhooks are not aware of the branching system (For example, if a webhook is set to trigger based on new asset imports, then any imports into any branch of the current org will trigger the webhook).
- Custom Apps and webhooks that affect items or assets by name will only affect these items or assets in the main branch, if the code is not branch-aware.
- Migrations/Data Transfer from one org to another will only migrate the main branch. It will not migrate any of the branching system.
- There are no branch-specific permissions available at this time for users.
We suggest that teams planning to use branching will treat the main branch as a protected branch. Even though there is currently no way to set user permissions to prevent users from editing the main branch directly, the implementation team can communicate this idea across the whole team, and avoid work directly inside the main branch. All work should be done inside the other branches, and then tested thoroughly prior to a merge back into the main branch. This workflow is similar to the way GitHub would be used.