Skip to main content
By creating a separate space to experiment with updates, you can develop confidently without disrupting production data. This approach supports scalable and reliable workflows, reducing the need for reactive fixes while improving traceability and accountability in the development process.

​
Branching in Omni

If you’re familiar with git - and it’s okay if you’re not! - branches in Omni are similar.In Omni, a branch is an isolated space that allows you to make changes to a model and/or content without affecting the live versions, typically referred to as production. This enables you to experiment, update, and refine your changes before applying any modifications to the live environment.
To demonstrate why branches are useful, let’s look at an example that starts with a change to a shared model.When changes are made directly to a shared model, the model’s history might look like this:The changes in this example were immediately applied to the model. If a query had been using the modified field, its logic and results could have changed unexpectedly. These differences might not be noticed right away, potentially leading to incorrect conclusions or broken content.Now consider this example, where changes to the model and impacted documents were made together in a branch:In this example, the branch contained updates to the field logic and impacted documents. You could navigate to documents that use the field, open the branch, and make the changes required to ensure the updated data was correct.When everything worked as expected, you would then merge the branch, applying the changes to the live version of the model and publishing new versions of the documents at the same time.Want to learn more?Check out this blog post to learn more about why traditional development practices - like branches - are useful for modern data teams.
Unlike a document draft which is specific to a single document, branches can include changes to a model and multiple documents. This makes branches especially useful for updating a model and any impacted content at the same time.Branches shouldn’t be thought of as entirely separate from document drafts - they act more as a layer of additional functionality on top of document drafts. When content changes are made in a branch, a draft of each modified document is attached to the branch. Publishing the branch publishes new versions of the documents.Refer to the Editing & publishing guide for a detailed overview, including a comparison between drafts and branches.
Branches can be used in the model IDE and documents.
Your connection permissions determine the level of access you have to branches:
View branchesCreate branchesMerge branches
ViewerX NoX NoX No
Restricted QueriersX NoX NoX No
Queriers✓ Yes✓ YesX No
Modelers✓ Yes✓ Yes✓ Yes
Connection Admins✓ Yes✓ Yes✓ Yes
Note: Create branches also includes the ability to make changes within a branch.
Yes, but only for changes to models. If a branch includes content changes, those changes will not be pushed to the connected git repository. However, the drafts of the content will be published when the branch is merged.When the git is configured for a connection, Branch Mode is required to make changes to the connection’s models. The dbt integration uses branches to enable switching dbt environments.

​
Creating branches

Connection Admin, Modeler, or Querier permissions are required to create branches.
  1. In a workbook or the model IDE, click Model > New branch or Model > Branch > New branch.
  2. When prompted, enter a name for the branch.
    To group (or nest) branches in the branch menu, you can use forward slashes. For example, these branch names:
    - add-new-topic
- field-updates/add-new-calc
- field-updates/rename-fields
- field-updates/update-field-def
- remove-topic
    Would create this structure in the branch menu:
    - add-new-topic
- field-updates
  - add-new-calc
  - rename-fields
  - update-field-def
- remove-topic
  3. Use the Branch from dropdown to select the starting point for the branch:
    • Shared model (latest) - Creates a branch from the latest version of the shared model
    • Existing branch - Creates a branch from an existing branch
    • Specific version - Creates a branch from a specific version of the underlying model
  4. Click Create.
  5. A green and pink header will display at the top of the page, indicating that you’re in the branch: The green and pink branch header displayed at the top of a workbook
At this point, you can begin making changes. Note: If you created the branch in a workbook, you’ll be automatically placed in a document draft.

​
Editing documents

Connection Admin, Modeler, or Querier permissions are required to edit documents in branches.
To open an existing branch in a document, click Model > Branch and select your branch. If your model has 10 or more branches, you can use the Search branches… option to quickly find the branch you need. You’ll be placed in a draft and any changes will be auto-saved as you work. You can add changes to the model associated with the document by opening the branch in the model IDE.

​
Moving drafts to branches

Branches can include changes to multiple documents. If the draft you want to move uses the same model as any documents in the branch, you can attach it to a branch. To attach an existing draft to a branch:
  1. Open the draft.
  2. Click File > Move to branch.
  3. Select the branch. The draft header at the top of the page will be updated to include the branch.
You can detach a draft from the branch at any time by clicking File > Move to different branch > Detach from branch in the workbook.
If a draft for a document is already attached to the branch, it will be overwritten if another draft for the same document is moved. For example, a branch has a draft for Document A attached to it. If a different draft for Document A is moved to the branch, the original draft will be overwritten.The opposite is also true - if you detach a draft from a branch and the source document already has a draft, it will be overwritten. You’ll be prompted to confirm the detachment when this occurs.

​
Viewing document changes

For every change you make in a document, an entry will be added to the Draft changes panel. Click See changes in the branch header or View workbook changes on the left side of the page to open the panel: The Draft changes panel showing a list of changes made to a document Note: The Draft changes panel will only display changes for the current document.

​
Requiring pull requests to publish document changes

For high-impact or sensitive documents, you may want to ensure that all changes are reviewed before they go live. Enabling Require pull requests to publish enforces a pull request–based workflow, so updates must be proposed, reviewed, and approved before they are published. When this setting is enabled:
  • Direct edits to the published document are blocked
  • Any change requires opening a branch and submitting a pull request
  • The document is only updated once the pull request is approved and merged
The Require pull requests to publish setting in document settings This setting is applied per document, allowing you to selectively enforce review workflows only where they’re needed. First enable the document setting under Settings > Content Permissions. Then turn it on on a given document from the File > Document settings menu. The Content Permissions section in organization settings with the Require pull requests to publish option To use this feature:
  • The git integration must be configured for the model the document is built on
  • You must have the Content Manager role on the document to enable or disable this setting
  • Users making changes must have the Querier role or higher, as changes require creating a branch

​
Finding and managing branches

When working with branches in the model IDE, you have two ways to find and select the branch you need:
  • Click Model > Branch and select your branch from the dropdown menu. To search for a branch, click the Search branches option to open a searchable dialog that makes it easier to find the branch you need. You can filter branches by name, then either switch to the branch or press Enter to select it.
  • The Branch management page, accessed by clicking the icon in the left navigation of the IDE: The Branch management page in the model IDE showing a list of branches You can view and manage all branches for a model on the Branches page. This page displays a list of all branches with key information like branch name, creator, and last updated time.

​
Switching branches via URL

This section is only applicable to workbooks and dashboards. To switch branches in the model IDE, use the Model > Branch menu.
You can load a document on a specific, existing branch by appending the ?branch= query parameter to its URL. This approach is useful when you want to:
  • Bookmark a direct link to a document on a specific branch
  • Share a branch-specific view of a document with a colleague
  • Quickly switch between branch states without navigating the UI
For example: 
https://<your-omni-instance>/dashboards/<dashboard-id>?branch=<branch-name>
Replace <branch-name> with the exact name of the existing branch you want to load. For example, if you want to load a workbook on a branch named feature/new-metrics: 
https://yourcompany.omniapp.co/workbooks/abc123?branch=feature%2Fnew-metrics
When adding the name of the branch, keep in mind that:
  • The branch must already exist. This parameter doesn’t create new branches. Additionally, if the branch name does not match an existing branch, the document will load without a branch.
  • You’ll need to URL-encode special characters. For example, / becomes %2F.

​
Editing models

Connection Admin, Modeler, or Querier permissions are required to edit models in branches.
After selecting your branch using one of the methods above, you can begin making changes to the model. Click Save to branch to add your changes to the branch: The Save to branch button in the model IDE While you’re working, you may want to periodically see how your changes will impact documents. You can do this by using the Content Validator or opening the branch in a workbook.

​
Viewing staged model changes

Each time you save a change in the IDE, an entry will be added to the Model history panel. Open this panel to view the changes currently on the branch, as well as the before and after (also called a diff) of each change: The Model history panel showing changes saved to a branch To view only the model files you’ve changed (and saved) in the branch, click the Browse mode dropdown in the file picker, then Staged. The IDE will update to filter out any unchanged files: The Browse mode dropdown in the model IDE file picker with the Staged option selected

​
Validating changes with the Content Validator

As you make changes to the model, Omni recommends using the Content Validator to check your work. This tool makes it easy to identify issues in content and proactively address them. Refer to the Content Validator guide for more information and the Common publishing workflows guide to learn how to incorporate validation into your development strategy.

​
Publishing and merging branches

Connection Admin or Modeler permissions are required to merge branches.
After you’ve verified your changes work as expected, you’ll need to merge the branch to apply them. The steps to merge a branch will vary if the git integration is enabled. If the integration is enabled, you’ll see a Create pull request button in the branch header: The Create pull request button in the branch header Click this button to create a pull request in the connected git repository. The changes in the branch will be applied to production once the pull request is merged. If the branch includes content changes, the drafts of the impacted documents will be published. If git isn’t enabled or pull requests aren’t required, follow these instructions:
  1. In the branch header at the top of the page, click Publish content drafts or Merge (which will display if the branch contains model changes).
  2. You’ll be prompted to confirm the merge. Note: If the branch contains modeling changes, you’ll also see a Delete branch after merge box. Omni recommends leaving this checked. The merge branch confirmation dialog with the Delete branch after merge option
  3. Click Merge branch.

​
Working with out of date drafts

There may be times when you see the following out of date warning when preparing to publish content: The out of date warning displayed when a draft is older than the published version When a draft is marked out of date, it means that a new version of the document has been published since the draft was created. Publishing the outdated draft will overwrite the currently published version of the document.
  1. Identify the changes in the outdated draft.
  2. Discard the draft.
  3. Create a new draft of the document.
  4. In the new draft, redo any changes you identified in step 1.
  5. When finished with all your changes, merge the branch.