Developing content and models with Branch Mode

More structured than draft-only mode but less complex than the Git integration, Branch Mode brings lightweight version control to Omni, letting you test changes to models and content before making them visible to your teammates. 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

What's a branch?

If you’re familiar with version control systems like 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.

Why use branches?

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.

Check out our blog post to learn more about why traditional development practices - like branches - are useful for modern data teams.

What's the difference between a branch and a document draft?

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 and publishing guide for a detailed overview, including a comparison between drafts and branches.

Where can branches be used?

Branches can be used in the model IDE and documents.

Who can use branches?

Your connection permissions determine the level of access you have to branches:

	View branches	Create branches & make changes	Merge branches
Viewer	X No	X No	X No
Restricted Queriers	X No	X No	X No
Queriers	✓ Yes	✓ Yes	X No
Modelers	✓ Yes	✓ Yes	✓ Yes
Connection Admins	✓ Yes	✓ Yes	✓ Yes

Viewers and Restricted Queriers can view branches if the branch’s Open to viewers setting is enabled. See Opening a branch to viewers for more information.

Do branches work with the Git and dbt integrations?

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.

Can extension models have their own branches?

Yes. Set the extension’s branch workflow to Develop independently. Its branches are then scoped to the extension and separate from the parent shared model’s branches.Refer to Branches and Git for extension models for more information.

Creating branches

Connection Admin, Modeler, or Querier permissions are required to create branches.

Omni UI
API
CLI

To create a branch:

In the model IDE, click Model > Branch > New branch
In a workbook, click Model > New branch or Model > Branch > New branch

When prompted, enter a name for the branch.

Want to group branches in the branch menu?

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

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

Click Create.
A green and pink header will display at the top of the page, indicating that you’re in the branch:

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.

If the model’s connection has environments configured, creating a branch will also display an environment switcher. While in a branch, user attribute-based environment assignment is ignored - refer to How environment selection is resolved for how the environment sources interact.

Use the Create model API to create a branch:

curl --request POST \
  --url https://{your-omni-org}.omniapp.co/api/v1/models \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "modelKind": "BRANCH",
  "baseModelId": "5da4e30e-45e2-4693-b87d-51c39d69963f"
}
'

Use the omni models create-branch command to create a branch using the Omni CLI:

omni models create-branch <model-id>

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:

Open the draft.
Click File > Move to branch.
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

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

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 for a given document from the File > Document settings menu. 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

Omni UI
API
CLI

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 IDE sidebar, or by clicking Model > Branch > Manage 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. Note: Manage branches only appears in the menu once the model has at least one branch, and isn’t available on schema models.

Use the List branches API to retrieve a list of branches you have access to:

curl --request GET \
  --url 'https://{your-omni-org}.omniapp.co/api/v1/branches' \
  --header 'Authorization: Bearer {token}'

To list branches for a specific model, use the List models API with the modelKind and baseModelId query parameters:

curl --request GET \
  --url 'https://{your-omni-org}.omniapp.co/api/v1/models?modelKind=BRANCH&baseModelId=5da4e30e-45e2-4693-b87d-51c39d69963f' \
  --header 'Authorization: Bearer {token}'

Use the omni models list command to list the branches for a specific model using the Omni CLI:

omni models list --model-kind "BRANCH" --base-model-id "<model_id>"

Opening a branch to viewers

By default, Viewers and Restricted Queriers always see the shared model as it is in production, even if a branch has a direct link. Enabling the Open to viewers setting allows these users - and embed users - to see the branch’s content instead of production when they follow a direct link, such as a ?branch= URL or an embed branch parameter. These users are only able to view the branch’s contentk and the branch won’t be listed in their branch pickers.

Omni UI
API

Turning this toggle on requires permission to edit every model in the branch. Turning it off only requires permission to edit the branch on one of its models, so anyone who could change what viewers see can also turn it back off.

To enable Open to viewers for a specific branch:

Navigate to the Branch management page, accessed by clicking the icon in the IDE sidebar, or by clicking Model > Branch > Manage branches.
Click the name of the branch.
Toggle Open to viewers to On.

This setting is automatically disabled whenever a model is added to the branch, for example when:

A new model layer is added to the branch
A trashed model layer is restored

Renaming the branch or refreshing its schema doesn’t disable the setting.

Use the Open or close a branch to viewers API to enable or disable openToViewers for a branch:

curl --request PATCH \
  --url https://blobsrus.omniapp.co/api/v1/branches/{branchId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "openToViewers": true
}
'

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.

Save to branch captures changes made in the shared model IDE while in a branch. If you’ve added fields or calculations to your workbook model using the workbook UI (for example, quick aggregates or custom SQL fields), those changes are stored in the workbook layer and won’t be staged automatically. To include them in the branch, open the workbook model changes drawer and click Add to branch. See Promoting workbook changes in a branch for steps.

Click Save to branch to add your IDE 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:

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. When creating a pull request from a branch with draft content, Omni keeps the repository’s pull request template, if one exists, and adds a link to view the branch content below it in the pull request description. This makes it easier for reviewers to see what documents will be published when the pull request is merged, reducing the risk of stale branches overwriting newer changes.

The automatic PR description link works for GitHub and GitLab pull requests. Azure DevOps and Bitbucket do not support pre-filling pull request descriptions via URL parameters, so the link will not be added for these providers.

If Git isn’t enabled or pull requests aren’t required, follow these instructions:

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).
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.
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.

Identify the changes in the outdated draft.
Discard the draft.
Create a new draft of the document.
In the new draft, redo any changes you identified in step 1.
When finished with all your changes, merge the branch.

Drafts that restrict access for Restricted Queriers

When you’re merging a branch, Omni checks each attached draft against the published version of its document to see whether Restricted Queriers and Viewers would lose access to any dashboard tabs. If one or more drafts would restrict access, you’ll see something similar to the following on the branch page or merge review:

1 draft restricts access for Restricted Queriers

Drafts that restrict access are also marked with an icon next to their name in the drafts table. Hover the icon to see the affected tabs and the reason for each, for example:

Restricted Queriers and Viewers lose access to: Revenue by region (SQL)

This check only runs for models with Restricted Querier or Viewer roles assigned. Additionally, publishing and merging are not blocked by this warning.

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Developing content and models with Branch Mode

Branching in Omni

Creating branches

Editing documents

Moving drafts to branches

Viewing document changes

Requiring pull requests to publish document changes

Finding and managing branches

Opening a branch to viewers

Switching branches via URL

Editing models

Viewing staged model changes

Validating changes with the Content Validator

Publishing and merging branches

Working with out of date drafts

Drafts that restrict access for Restricted Queriers

​Branching in Omni

​Creating branches

​Editing documents

​Moving drafts to branches

​Viewing document changes

​Requiring pull requests to publish document changes

​Finding and managing branches

​Opening a branch to viewers

​Switching branches via URL

​Editing models

​Viewing staged model changes

​Validating changes with the Content Validator

​Publishing and merging branches

​Working with out of date drafts

​Drafts that restrict access for Restricted Queriers

Branching in Omni

Creating branches

Editing documents

Moving drafts to branches

Viewing document changes

Requiring pull requests to publish document changes

Finding and managing branches

Opening a branch to viewers

Switching branches via URL

Editing models

Viewing staged model changes

Validating changes with the Content Validator

Publishing and merging branches

Working with out of date drafts

Drafts that restrict access for Restricted Queriers