Set up Omni’s dbt integration by connecting a dbt repository to an Omni database connection.
Omni’s dbt integration connects your dbt repository to an Omni database connection, syncing model metadata like descriptions, tags, and schema mappings into your Omni semantic model. This guide walks you through the setup process, from linking your Git repository to syncing dbt metadata into Omni.Omni supports three methods for connecting to your dbt repository:
GitHub App authentication - GitHub repositories only. Uses a GitHub app to perform authentication. Enables commit signing.
SSH authentication — Uses a deploy key to connect Omni to your repository. This is the traditional method and requires configuring a deploy key in your Git provider.
HTTPS token authentication — Uses an access token to authenticate. This method is simpler to set up because it doesn’t require deploy keys.
To view instructions, select the authentication method you want to use from the dropdown menu on the right side of the page, above the table of contents.
Select your authentication method from the dropdown to view setup instructions
Can I use the same Git repo for Omni models and dbt code?
We strongly recommend using two separate repositories: one for your dbt project and one for your Omni semantic model.This gives you:
Clear ownership — Separates data engineering from business logic.
Faster iteration — Prevents semantic refreshes from being tied to dbt compilation times.
Cleaner Git history — Keeps automatic commits from the Omni IDE out of your dbt pull requests.
Coordinated deployments — Ensures Omni model changes only apply after related dbt runs complete, so downstream content doesn’t break.
If you decide to keep Omni and dbt in the same repository, use separate branches for changes.
Can I use the same dbt repository for multiple database connections?
Yes. You can connect the same dbt repository to multiple Omni database connections. This is common when using different credentials for different environments, such as using separate Snowflake accounts for different departments.
You must configure dbt settings and environment variables for each individual connection to ensure models map to the correct database and schema.
Can I connect multiple dbt projects to a single Omni connection?
No. Each Omni connection supports exactly one dbt project integration. If you have multiple dbt projects, you must either:
Create separate connections for each project, or
Connect to one project formally and pull the other project’s tables as “raw” schemas
Can I query tables from different dbt projects in the same dashboard?
This is possible only if the tables are included in the same Omni connection.Since a connection can only have one dbt manifest, you can query tables from Project A (with full metadata) and Project B (as raw tables) in one dashboard.Combining tables from two separate Omni connections into a single query or dashboard tile isn’t supported.
This often happens if views are flagged with an ignored: true parameter. Omni’s sync may interpret complex views — especially those with dynamic logic like Jinja loops — as “not in use,” and automatically hide them to keep the model clean.To fix this:
1
Navigate to the model IDE.
2
Toggle the view mode to Model. The dropdown may default to Combined, so be sure to update it if needed.
3
Navigate to the file for the view and check for an ignored: true parameter.
4
Remove the parameter and promote the changes to the shared model.
'No models mapped to views' message in a dev environment
Omni only looks for tables in schemas explicitly allowed at the connection level. To fix this, you’ll need to:
1
Update the connection to include the dev schemas
Open the connection’s settings page and enter your dev schema pattern in the Include Schemas field. For example, DBT_USER_*.
2
Run a schema refresh
This will pull the dev schemas you just added into Omni. See Schema refreshes for more information.
'Circular reference' or duplication errors
This typically occurs when a dbt-imported measure shares the same name as an existing dimension in the Omni Semantic Layer.To fix the issue:
1
Rename the measure, changing the label or name to be unique (e.g., total_revenue).
2
Check the sql parameter to ensure it points to the raw database column, not the measure name.
3
Hide the dimension by adding the hidden: true parameter. This will hide the raw column in Omni.
dbt version and compatibility errors
If your dbt project requires a newer version, update it in Omni:
1
Navigate to Settings > Connections and click the connection.
2
Click the dbt tab.
3
Select the correct version from the dbt Version dropdown.
Connection test fails with GitHub App authentication
If the connection test fails when using GitHub App authentication, verify:
Installation ID is correct - The installation ID must be numeric and match the Omni GitHub App installation for your repository or organization. You can find this in your GitHub settings under Integrations > GitHub Apps > Configure.
GitHub App is installed - The Omni GitHub App must be installed and granted access to the repository. Check your GitHub organization or repository settings to confirm.
Repository URL is correct - The repository URL must be an HTTPS URL starting with https://github.com/.
GitHub App is configured in Omni - Your Omni instance must have the GitHub App configured. If the GitHub App option doesn’t appear in the authentication method dropdown, contact your Omni administrator.
If you continue to experience issues, try using SSH or HTTPS token authentication instead.
