Skip to main content
This guide covers a two-instance Omni deployment: a staging instance where all active development happens, and a production instance that receives promoted changes through git. The production instance uses git follower mode to stay in-sync with staging’s main branch. This setup provides true environment isolation — developers work entirely in staging, and production is only updated through a deliberate, git-controlled promotion process. It is the recommended approach for teams that need:
  • A stable, read-only production environment that cannot be affected by in-progress development
  • Strict control over what reaches production and when
  • Full separation of developer and end-user data access

Git follower mode

Git follower mode lets you centralize model development by designating one Omni model as a leader and another as a follower. The follower is read-only and automatically updates when changes are merged from the leader’s base branch into the follower’s base branch through a pull request. This is useful for creating dev/production environments or deploying a model across multiple regions or organizations. The staging instance holds the leader model: all development branches are opened here, all changes are tested here, and all PRs target staging’s main branch. When you’re ready to promote to production, you create a release branch in git that carries the changes from staging’s main into production’s base branch (e.g., prod). The production instance’s follower model automatically detects this branch and creates a matching Omni branch, which you validate before merging. Git follower mode promotes model changes only. Content (workbooks and dashboards) must be migrated separately to production using the content migration APIs, the agent skills or Omni CLI.

Requirements

Before you begin:
  • Two separate Omni instances: one for staging, one for production
  • Organization Admin permissions on both instances
  • Connection Admin permissions on both models’ connections
  • A staging database and a production database of the same type (e.g., both Snowflake) with identical schemas
  • A git repository in GitHub, GitLab, or Azure DevOps
  • Permissions in your git provider to add webhooks and deploy/SSH keys

Architecture overview

Initial setup

  1. Create production database connection in production Omni instance
  2. Create staging database connection in staging Omni instance 
  3. Set up the git integration on each instance
    • In staging, you’ll be pointed to the main branch
    • In production, you’ll check the box for “Git Follower” and point to a separate base branch (e.g. prod - make sure you configure this in git as well)

Development workflow (staging)

All development happens on the stage instance which acts as the leader.
1

Open a branch

From the  staging instance model IDE, create a new branch. Make model and content changes on this branch.
2

Validate with the Content Validator

Run the Content Validator on your branch to surface any broken references before promoting.
Run the Content Validator before opening a pull request. Catching broken references early keeps your PR focused on model logic, not cleanup.

Deployment workflow (staging)

1

Merge model changes to STAGE

Merge your changes to the shared model of STAGE (the leader instance)
  • With pull requests required (recommended):
    • Open a PR to main and merge after review. This publishes attached content on the leader instance only.
  • Without pull requests: Merge the branch directly from the model IDE.
Content changes (published workbooks and dashboards) are not automatically propagated to the production instance through git follower. Git follower syncs model changes only. To replicate content across instances, use the content migration API.

Promotion workflow (staging to production)

Because STAGE is leader to follower PROD, the changes in stage’s main need to be moved to prod through a pull request.
1

Create release branch in git

  • In git repository
    • Create a branch off of the base branch of stage (main) (e.g. release-to-prod-YYYYMMDD). This pull request wraps all “followed” changes into the newly created branch.
    • Create a pull request that merges your changes into the follower’s base branch (prod in git)
    Make sure the “Always create branches” setting is enabled in Omni as it will create a branch in Omni with the same name
2

Migrate content from STAGE to PROD instance

As git follower only promotes model changes, use the content migration API to promote content across instances prior to promoting model changes.
It’s a best practice to consider your folder structures and their mapping between STAGE and PROD. This can be accomplished with Content, Folders, and Documents APIs.
Use the get-document-state endpoint to create a copy of the content. Use create-document endpoint to create a new document on PROD that will also be published.
You may also consider using the get-draft-state endpoint when migrating a draft.  Viewing data, ownership, schedules and history will NOT transfer to the copy and will need to be updated separately.
If the document already exists, use create-draft-and-patch-document to create the draft of the published version and then the publish-draft endpoint to publish it. You may also consider patch-draft for further patch iterations on a draft. 
Migrate content after the model promotion is confirmed in production. This ensures the PROD model is in the correct state before any content references it.
3

Review changes in the Omni PROD instance

  • In the Omni PROD instance
    • Open the model. The PROD model is read-only due to git follower settings, so you review changes here but don’t edit them.
    • Open the release-to-prod-YYYYMMDD branch
    • Test the changes by reviewing the Content Validator for any issues
4

Merge the release branch into base prod branch

  • In git repository:
    • Merge the pull request in git to merge the release branch changes into the base branch (likely prod)
  • At this point, your model changes are live in the production instance

Permissions considerations

Structuring permissions across two instances keeps the production environment clean and reduces the risk of accidental changes. Consider restricting developer access to the production instance to read-only. Changes to the production model should only arrive through the git promotion process, not through direct Omni access.

Best practices

Mirror your database schemas

The shared model is the same across both instances — it doesn’t know which instance it’s in. If your staging and production schemas diverge (different tables, columns, or data types), model references that work in staging will break in production after promotion. Keep schemas structurally identical.

Use a consistent release branch naming convention

A format like release-to-prod-YYYYMMDD makes it straightforward to identify in-flight promotions, track the history of what landed in production and when, and quickly roll back by reverting the PR.

Plan content migration as part of your release checklist

Content migration is often skipped under time pressure. Build it explicitly into your release process — document which content needs to move with each release and trigger migration before announcing changes are live to end users.

Refresh the production schema after promotion

After merging a release, perform a schema refresh on the production model to ensure the schema matches staging. This is especially important after releases that include database schema changes.

Next steps