> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploying Omni: Single instance deployment with git and dbt

> Set up and manage Omni in a single instance, single connection environment with git version control and dbt integration — the most common Omni deployment pattern.

export const categoryIcons = {
  'administration': 'lock',
  'api': 'terminal',
  'connections': 'database',
  'dashboards': 'table-columns',
  'embed': 'code',
  'errors': 'exclamation',
  'migration': 'angles-right',
  'modeling': 'wrench',
  'patterns': 'plus',
  'schedules & alerts': 'envelope',
  'visualizations': 'chart-column',
  'workbooks': 'book'
};

export const GuideSidebar = ({category, relatedLinks, updatedDate}) => {
  const [progress, setProgress] = React.useState(0);
  React.useEffect(() => {
    const sidebar = document.querySelector('.guide-sidebar');
    if (!sidebar) return;
    let container = sidebar.parentElement;
    while (container && !container.querySelector('.guide-header')) {
      container = container.parentElement;
    }
    if (container && !container.classList.contains('guide-page-layout')) {
      container.classList.add('guide-page-layout');
    }
  }, []);
  React.useEffect(() => {
    const handleScroll = () => {
      const scrollTop = window.scrollY;
      const docHeight = document.documentElement.scrollHeight - window.innerHeight;
      const scrollPercent = docHeight > 0 ? scrollTop / docHeight * 100 : 0;
      setProgress(Math.min(100, Math.max(0, scrollPercent)));
    };
    window.addEventListener('scroll', handleScroll, {
      passive: true
    });
    handleScroll();
    return () => window.removeEventListener('scroll', handleScroll);
  }, []);
  const icon = category ? categoryIcons[category.toLowerCase()] || 'book' : 'book';
  return <aside className="guide-sidebar">
      <div className="guide-sidebar-content">
        <a href="/guides" className="guide-sidebar-back">
          <Icon icon="arrow-left" iconType="solid" size={14} />
          <span>All guides</span>
        </a>

        <div className="guide-sidebar-section">
          <div className="guide-sidebar-label">Progress</div>
          <div className="guide-sidebar-progress">
            <div className="guide-mascot">
              <svg viewBox="0 0 688 690" width="48" height="48">
                <defs>
                  <clipPath id="progressClip">
                    <rect x="0" y={0} width="688" height={progress * 6.9} />
                  </clipPath>
                </defs>

                {}
                <path d="M343.67 1.5C542.684 1.5 685.84 149.351 685.84 344.84C685.84 540.328 542.685 688.18 343.67 688.18C144.655 688.18 1.5 540.318 1.5 344.84C1.50007 149.361 144.655 1.50005 343.67 1.5Z" fill="#FCFCF7" stroke="#FF5FA2" strokeWidth="3" />

                {}
                <path d="M343.67 0C143.81 0 0 148.55 0 344.84C0 541.13 143.81 689.68 343.67 689.68C543.53 689.68 687.34 541.14 687.34 344.84C687.34 148.54 543.53 0 343.67 0Z" fill="#FF5FA2" clipPath="url(#progressClip)" />

                {}
                <path d="M337.89 319.29C337.89 336.75 322.49 350.14 302.81 349.83C286.18 349.57 273.89 337.29 274.37 321.45C274.88 304.82 290.91 290.88 309.98 290.44C325.69 290.09 337.88 302.69 337.88 319.29H337.89Z" fill="#4D122C" />
                <path d="M566.17 319.29C566.17 336.75 550.77 350.14 531.09 349.83C514.46 349.57 502.17 337.29 502.65 321.45C503.16 304.82 519.19 290.88 538.26 290.44C553.97 290.09 566.16 302.69 566.16 319.29H566.17Z" fill="#4D122C" />
                <path d="M367.74 342.07C360.22 346.32 359.4 354.9 370.62 366.4C381.85 377.9 399.76 389.56 420.81 389.18C441.88 389.1 460.67 377.72 472.47 363.53C473.83 361.93 478.84 356.88 478.51 351.07C478.32 348.35 476.17 341.19 467.83 341.38C463.46 341.44 461.21 343.68 456.69 347.36C445.2 356.14 432.7 361.21 420.56 361.27C408.43 361.43 395.68 356.17 385.39 347.22C380.32 342.81 375.25 337.82 367.74 342.07Z" fill="#4D122C" />
              </svg>
            </div>
            <span className="guide-sidebar-progress-text">{Math.round(progress)}%</span>
          </div>
        </div>

        {category && <div className="guide-sidebar-section">
            <div className="guide-sidebar-label">Category</div>
            <div className="guide-sidebar-category">
              <Icon icon={icon} iconType="solid" size={14} />
              <span>{category}</span>
            </div>
          </div>}

        {updatedDate && <div className="guide-sidebar-section">
            <div className="guide-sidebar-label">Last updated</div>
            <div className="guide-sidebar-date">{updatedDate}</div>
          </div>}

        {relatedLinks && relatedLinks.length > 0 && <div className="guide-sidebar-section">
            <div className="guide-sidebar-label">Related</div>
            <ul className="guide-sidebar-links">
              {relatedLinks.map((link, index) => <li key={index}>
                  <a href={link.href}>{link.title}</a>
                </li>)}
            </ul>
          </div>}
      </div>
    </aside>;
};

export const GuideTitle = ({title}) => {
  return <div className="guide-header">
      <h1 className="guide-title">{title}</h1>
    </div>;
};

<GuideSidebar
  categoryIcons={categoryIcons}
  category="deployment"
  updatedDate="March 2026"
  relatedLinks={[
{ title: "Git integration setup", href: "/integrations/git/setup/github" },
{ title: "dbt integration setup", href: "/integrations/dbt/setup" },
{ title: "Branch Mode", href: "/content/develop/branch-mode" },
{ title: "Content Validator", href: "/modeling/develop/content-validator" }
]}
/>

<GuideTitle title="Deploying Omni: Single instance deployment with git and dbt" />

This guide covers the most common Omni deployment pattern: a single Omni instance connected to a single database, with git for model version control and dbt for semantic layer metadata.

If you're setting up Omni for the first time and your team uses dbt, start here.

This setup gives you:

* Structured model development and review through git branches and pull requests
* dbt metadata (descriptions, foreign key constraints) surfaced automatically in Omni
* A safe development workflow where changes are staged, validated, and merged before going live

## Requirements

Before you begin, make sure you have:

* An existing database connection in Omni
* **Organization Admin** permissions in Omni (required for git settings)
* **Connection Admin** permissions for the target connection (required for dbt setup)
* An existing git repository in GitHub, GitLab, Bitbucket, or Azure DevOps
* Permissions in your git provider to add webhooks and deploy/SSH keys
* A dbt project with an accessible git repository

## Set up the git integration

The [git integration](/integrations/git/setup/github) connects your Omni shared model to a git repository, enabling branch-based development and pull request workflows for model changes.

<Note>
  [Branch Mode](/content/develop/branch-mode) is required to make changes to the shared model when the git integration is enabled. All model changes must be made on a branch.
</Note>

## Set up the dbt integration

The [dbt integration](/integrations/dbt/setup) connects your dbt project to an Omni database connection. Once connected, Omni syncs dbt metadata — including field descriptions, foreign key constraints, and dbt Semantic Layer definitions — into your model automatically.

## Development workflow

<Note>
  With git and dbt connected, all model development in Omni happens on [branches](/content/develop/branch-mode). This keeps your shared model stable while changes are built, tested, and reviewed.
</Note>

<Steps>
  <Step title="Open a branch">
    From the Omni model IDE, create a new branch. Give it a descriptive name that matches your work. If you're making dbt changes in parallel, use the same branch name in both repositories to keep them in-sync.
  </Step>

  <Step title="Make your changes">
    On the branch, you can:

    * Add or edit fields, dimensions, measures, and views in the model IDE
    * Update topics and joins
    * Build and edit workbooks and dashboards — these are automatically attached to your branch

    Schema refreshes only pick up dbt models that already exist in your warehouse. If your change depends on a new or updated dbt model, build it in your warehouse first, then run a [schema refresh](/modeling/develop/schema-refreshes) so the latest fields are available on the branch.
  </Step>

  <Step title="Validate with the Content Validator">
    Before deploying, run the [Content Validator](/modeling/develop/content-validator) to check whether your model changes break any existing content. The Content Validator surfaces broken field references across all workbooks and dashboards, and lets you find and replace broken references in bulk before deploying.

    <Tip>
      Run the Content Validator before opening a pull request, not after. Catching broken references early keeps your PR review focused on model logic, not cleanup.
    </Tip>

    When the validator reports no broken references, your branch is ready to deploy.
  </Step>
</Steps>

## Deploy your changes

Once your branch passes validation, deploy it. The steps below depend on whether **Require pull requests** is enabled in your [git settings](/integrations/git/settings#pull-request-required). You set this during git integration setup and can change it at any time.

### With pull requests required (recommended)

<Steps>
  <Step title="Add your model changes to your branch in Omni">
    In the model IDE, click **Add to branch** to stage your in-progress model edits onto the current branch.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/omni-e7402367/images/add-to-branch.png" alt="Omni model IDE with the Add to branch button highlighted" />
  </Step>

  <Step title="Open a pull request">
    In your git provider, open a pull request from your Omni branch into `main` (or your default branch).

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/omni-e7402367/images/open-pull-request-1.png" alt="Pull request opened in GitHub from the Omni branch into main" />
  </Step>

  <Step title="Have your changes reviewed and approved in git">
    Request a review from your team. The PR must be approved before it can be merged.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/omni-e7402367/images/review-and-commit-pr.png" alt="Approved pull request ready to be merged" />
  </Step>

  <Step title="Merge the pull request and delete the branch">
    Merge the PR into `main` and delete the branch. Merging promotes the model changes to the shared model and publishes any content attached to the branch.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/omni-e7402367/images/merged-and-closed-pr.png" alt="Merged and closed pull request in the git provider" />
  </Step>
</Steps>

### Without pull requests required

With **Require pull requests** disabled, you can stage and merge model changes directly from the IDE in two steps.

<Steps>
  <Step title="Add your changes to the branch">
    With your branch open, click **Add to branch** to stage your changes.
  </Step>

  <Step title="Merge to the shared model">
    Click **Merge to shared model**. This promotes model changes and publishes attached content in one step.
  </Step>
</Steps>

1. With your branch open, click **Add to branch** to stage your changes.
2. Click **Merge to shared model**. This promotes model changes and publishes attached content in one step.

<Warning>
  Merging directly to the shared model bypasses peer review. For teams where model accuracy and stability matter, enabling **Require pull requests** is strongly recommended.
</Warning>

## Best practices

* [Working with dbt and Git](/integrations/dbt/git-workflows) — The full branch → schema refresh → validate → merge lifecycle for dbt and git
* [git integration settings reference](/integrations/git/settings) — Full reference for all git configuration options
* [git integration best practices](/integrations/git/best-practices) — Branch protection, monorepo setup, and more
* [dbt integration overview](/integrations/dbt/index) — Feature overview including dbt Semantic Layer and dynamic schema switching

## Next steps

* [git integration settings reference](/integrations/git/settings) — Full reference for all git configuration options
* [git integration best practices](/integrations/git/best-practices) — Branch protection, monorepo setup, and more
* [dbt integration overview](/integrations/dbt/index) — Feature overview including dbt Semantic Layer and dynamic schema switching
* [Branch Mode](/content/develop/branch-mode) — How branching works for both model and content changes
* [Content Validator](/modeling/develop/content-validator) — How to validate and repair content after model changes