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

# Working with dbt and Git

> Manage Omni model changes using dbt and Git workflows, including branches, pull requests, and dynamic environments.

Managing changes across your data stack shouldn't feel like a black box. By integrating dbt and Git with Omni, you can align your analytics development with software engineering best practices using branches, pull requests, and dynamic environments to test changes before they reach your end users.

This guide covers the core workflows for keeping Omni in sync with dbt, collaborating with Git, and managing the end-to-end development lifecycle.

## Common questions

<AccordionGroup>
  <Accordion title="What workflows does Omni support for dbt and Git?">
    Omni supports both [bottom-up (dbt to Omni)](#dbt-to-omni) and [top-down (Omni to dbt)](#omni-to-dbt) development patterns.
  </Accordion>

  <Accordion title="Do business users need Git access to push changes to dbt?">
    No. Omni handles the connection using a centralized deploy key or integration. You can manage which users have permission to push changes within Omni's internal settings.
  </Accordion>

  <Accordion title="Will changes in an Omni branch be rebased when others merge?">
    Yes, shared model changes are automatically rebased and picked up by other branches upon merge.
  </Accordion>

  <Accordion title="Will branch-based draft changes be rebased if someone else is working on the same document?">
    No. Draft changes do not get rebased. If multiple people edit the same document draft, subsequent merges can overwrite previous changes. Coordinate with others when collaborating on the same dashboard to avoid accidental overwrites.
  </Accordion>

  <Accordion title="Can folder structures (e.g., user/branch-name) be used for Omni branches?">
    Yes. Folder-structured branch names aren't automatically matched between Omni and dbt, so you'll need to manually repoint your dbt branch to the working branch in the Omni model IDE to keep the workflows synced.
  </Accordion>

  <Accordion title="What happens if a dbt change breaks a dashboard?">
    Before merging your branch, use Omni's [Content Validator](/modeling/develop/content-validator) to find and fix any broken references (e.g., a deleted column). You can fix these globally from the validator interface before the changes go live.
  </Accordion>
</AccordionGroup>

## Requirements

To follow the workflows in this guide, you'll need:

* A [configured dbt integration](/integrations/dbt/setup) on your Omni connection
* [Virtual schemas](/integrations/dbt/index#dbt-environments) or [connection nvironments](/connect-data/dynamic-environments) configured to use the environment switcher
* Permissions to push changes from Omni to dbt, if using top-down workflows

## Governance and SDLC controls

For teams requiring governance, Omni supports a software-engineering-style development lifecycle. Three Omni features make this possible:

* **Omni's [Git integration](/integrations/git),** which allows you to sync your Omni model to a Git repository and enforce pull requests for all model changes.

  <Warning>
    We recommend having separate Git repositories for your dbt code and your Omni code.
  </Warning>

* **Dynamic environments**. Use [connection environments](/connect-data/dynamic-environments) to swap entire databases or [dynamic schemas](/modeling/models/dynamic-schemas) to swap underlying schemas within a single connection. This allows you to point an Omni branch at a CI schema to test breaking changes.

* **Content drafts**. [Drafts](/content/develop/drafts) allow you to iterate on dashboards privately. You can attach these drafts to specific branches to see how underlying model changes impact the visualization.

<h2 id="dbt-to-omni">
  Bottom-up: dbt to Omni
</h2>

This is the standard flow where you define core logic (tables, views, schemas) in dbt. Omni inherits this logic, including descriptions and metadata, so you only have to define it once.

<Steps>
  <Step title="Prepare the data and code">
    Before Omni can detect a new model, it must be materialized as a table or view in your database and committed to your dbt Git repository so Omni can access the metadata.

    1. **Materialize your dbt model.** Run `dbt build` (or `dbt run`) against your development target. Omni cannot query a model that hasn't been materialized in your database yet.
    2. **Push to Git.** Push your dbt code to a feature branch in your Git provider.
  </Step>

  <Step title="Sync with Omni">
    1. **Create a branch.** In the Omni model IDE, create a new branch for testing changes from dbt.
    2. **Switch dbt environments.** Use the environment selector in the Omni header to point your branch to your dbt development environment.
           <Tip>
             Switching dbt environments requires [Virtual Schemas](/integrations/dbt/index#dbt-environments) to be configured.
           </Tip>
    3. **Refresh the schema.** Click **Model > Refresh Schema**. [Schema refreshes](/modeling/develop/schema-refreshes) trigger Omni to pull the updated manifest from Git and the new table structures from your database.
  </Step>

  <Step title="Model and validate">
    1. **Develop in Omni**. Your new dbt model will display in the IDE. You can now add it to topics, define joins, or create measures.
    2. **Validate Omni content**. Use the [**Content Validator**](/modeling/develop/content-validator) to see how your changes impact existing dashboards. You can perform a global find-and-replace for renamed fields across all content if needed.
    3. **Merge and publish**. Once your dbt pull request is merged, merge your Omni branch to promote your metadata changes to production.
  </Step>
</Steps>

<h2 id="omni-to-dbt">
  Top-down: Pushing changes from Omni to dbt
</h2>

If you'd rather model visually, Omni also lets you push transformations from the Omni UI back to dbt. You can also restrict this workflow to specific users based on Omni data permissions. See [Creating new dbt models from Omni queries](/integrations/dbt/models#creating-new-dbt-models-from-omni-queries) for the full workflow.

<Tip>
  Use Omni as a prototyping layer. Build views in Omni first to test if they provide value before committing to the full dbt materialization process.
</Tip>

## Next steps

* [Connecting dbt to Omni](/integrations/dbt/setup) — Set up the dbt integration if you haven't already
* [Working with dbt models](/integrations/dbt/models) — Author and edit dbt models from Omni
* [Content Validator](/modeling/develop/content-validator) — Catch broken references before merging model changes
* [Connection environments](/connect-data/dynamic-environments) — Configure dynamic environments for safe testing