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

# Connect a dbt Repository

> Create a workspace from a dbt project on GitHub: install the Upsolve GitHub App, pick the warehouse, merge the setup pull request and run the first sync.

Setting up takes about ten minutes and one pull request. You need:

* **Owner or admin** role in your Upsolve organization.
* A **GitHub repository** holding a dbt project (`dbt_project.yml`), and permission to install a GitHub App on it.
* A **connection** in your Upsolve project to the warehouse your dbt project builds into. See [Data Connection](https://docs.upsolve.ai/embedded-bi/data-connection/data-connection.md) if you don't have one yet.
* **GitHub Actions** enabled on the repository: the sync reads what an Actions run produces.

Supported dbt adapters: Postgres (including Supabase and Timescale connections), Redshift, Snowflake, BigQuery, ClickHouse, SQL Server, Microsoft Fabric, Trino and Athena. MySQL is not supported yet: `dbt-mysql` has no release for dbt 1.9 or later, which the sync needs.

Every one of these syncs your models, descriptions, prompts, skills and knowledge base. Answering from your [MetricFlow metrics](https://docs.upsolve.ai/ai-agent-builder/content-layer/dbt-metrics.md) needs a warehouse MetricFlow can compile for, which is fewer of them.

## 1. Create the workspace

In your project, click **New workspace** and choose **From a dbt repository**.

![The New workspace dialog asking how the workspace should be built, with Build in Upsolve and From a dbt repository (Beta) options](https://mintcdn.com/upsolve/ly_6q_O7-mhPeQj9/images/ai-agent-builder/content-layer/new-workspace-choice.png?fit=max\&auto=format\&n=ly_6q_O7-mhPeQj9\&q=85\&s=ca5c9ccb4ef80454787010bdef26de18)

Give it a name and an optional description, then click **Create and connect GitHub**.

![The New workspace dialog for a dbt repository, with Name and Description fields and a Create and connect GitHub button](https://mintcdn.com/upsolve/ly_6q_O7-mhPeQj9/images/ai-agent-builder/content-layer/new-workspace-name.png?fit=max\&auto=format\&n=ly_6q_O7-mhPeQj9\&q=85\&s=7d2c027fc392f6361e58faa0a08061cc)

The workspace opens on its setup page, which lists the five steps below. Until setup finishes, the workspace always opens here, so you can leave and come back: it picks up where you stopped.

![The setup page for a new dbt workspace, listing five steps: Repository and branch with a Connect GitHub button, What we found, Warehouse connection, Setup pull request and First sync](https://mintcdn.com/upsolve/ly_6q_O7-mhPeQj9/images/ai-agent-builder/content-layer/setup-steps.png?fit=max\&auto=format\&n=ly_6q_O7-mhPeQj9\&q=85\&s=c56e1f6af45acd7c8730c1d4285aae91)

## 2. Repository and branch

Click **Connect GitHub**. GitHub asks you to sign in, then to install the Upsolve GitHub App (listed on GitHub as **Upsolve Context Sync**) and choose which repositories it may see. You return to the setup page afterwards.

If the App can see several repositories, pick one. dbt projects are listed first. A repository another workspace already listens to shows which workspace and branch — you can connect a second workspace to it on a different branch (for example `staging` beside `main`).

Then choose the **branch** the workspace listens to. Its merges become workspace versions, and the Builder Agent's pull requests go into it. It defaults to the repository's default branch.

> [!NOTE]
>
> The App asks only for what a sync needs: to read the repository's contents and its Actions artifacts, and to open pull requests (the setup pull request, and changes you ask the Builder Agent to propose). It is given no warehouse credentials and never runs your models.

## 3. What we found

Upsolve reads the repository's default branch and shows what it found: the dbt project and its profile, its models, and its semantic models and metrics. It is a quick read of the files as written, so you can confirm Upsolve found the right project; `dbt parse` in your own CI stays the source of truth for every sync.

## 4. Warehouse connection

Choose the connection **your dbt project builds in**. The workspace queries the tables dbt built through this connection, so it must point at the database and schemas of the target you sync (usually `prod`). Upsolve checks that the models' tables are there.

## 5. Setup pull request

Click **Open pull request**. Upsolve opens one pull request into your branch that adds:

| File | What it does |
| - | - |
| `upsolve.yml` | Names the dbt target to parse. Holds row-level security later. |
| `upsolve/prompts/system.md` | The workspace's system prompt: what the workspace already had, or a starter to fill in. |
| `upsolve/prompts/sql.md`, `chart.md` | The SQL and chart prompts, if the workspace had any. |
| `upsolve/skills/…`, `upsolve/knowledge/…` | The workspace's existing skills and knowledge base files, if any. |
| `.github/workflows/upsolve-sync.yml` | Runs `dbt parse` on every push and pull request and uploads the parse for Upsolve. |

If the repository already has an `upsolve.yml` or `upsolve/prompts/system.md`, the pull request leaves it alone. Every other file in the table is written whether or not it exists, so **review the pull request's diff before merging**: it replaces an existing `.github/workflows/upsolve-sync.yml`, and any `sql.md`, `chart.md`, skill or knowledge file at the same path as one the workspace holds.

Because the pull request carries what the workspace holds now, the first sync replaces nothing in the workspace.

Review it like any other pull request and merge it. The setup page shows its status (*Open — waiting to be merged*, merged, or *Closed without merging*).

### If you don't commit a `profiles.yml`

Most teams don't. `dbt parse` still needs a profile, so the workflow writes a stub one at run time: its credentials are placeholders, because **parse never connects to your warehouse**. Its database and schema are real, though — dbt writes them into the table names Upsolve syncs — and are set to what setup found in your warehouse connection.

To change them later, set the `UPSOLVE_DBT_DATABASE` or `UPSOLVE_DBT_SCHEMA` **repository variable** (Settings → Secrets and variables → Actions → Variables) on GitHub.

### If your `profiles.yml` uses `env_var()`

Any `env_var('X')` with no default becomes an environment variable on the parse step, reading the repository's Actions variable `X` when set and a placeholder otherwise. A credential can stay a placeholder. Set the variable for anything that names a database or schema, or the synced tables will be named after the placeholder.

## 6. First sync

Once the setup pull request is merged, wait for its **Upsolve sync** workflow run to finish on the branch (a minute or two, in the repository's Actions tab), then press **Sync now**. The sync:

1. downloads the run's `upsolve-sync` artifact (dbt's `manifest.json` and `semantic_manifest.json`, `upsolve.yml` and the `upsolve/` folder),
2. enables exactly your dbt models as the workspace's tables, with dbt's descriptions,
3. replaces the prompts, skills and knowledge base with the repository's,
4. publishes a new version and stores its MetricFlow metrics against it.

When it succeeds, setup is complete and the workspace opens normally. The first sync's version always goes live, since there is no earlier version to keep. From then on, every merge into the branch syncs by itself.

Everything you chose during setup is under **Workspace settings → Git** afterwards: the repository and dbt target, the branch, **Promote each merge to production**, and the last sync with **Sync now**.

![Workspace settings, Git tab: the connected repository with its dbt target, the branch the workspace listens to, the Promote each merge to production option, and the last sync with a Sync now button](https://mintcdn.com/upsolve/ly_6q_O7-mhPeQj9/images/ai-agent-builder/content-layer/git-settings.png?fit=max\&auto=format\&n=ly_6q_O7-mhPeQj9\&q=85\&s=273c6eaeb29001cf9cb9b484005fb678)

> [!TIP]
>
> **Promote each merge to production** is shown during setup. Leave it off while you are getting started: each later merge then makes a version that you check in the Playground and promote yourself. Turn it on under Settings → Git once your [tests](https://docs.upsolve.ai/ai-agent-builder/tests.md) give you confidence.

## Troubleshooting a sync

A sync records its outcome on the workspace. A failure turns the sync chip at the top of the workspace to **Sync failed**; open it for the reason and what to fix.

| Message | What to do |
| - | - |
| The Upsolve sync workflow failed for the newest commit | Open the linked run in the repository's Actions tab, fix `dbt parse`, push, and sync again. |
| The Upsolve sync workflow is still running | Sync again when the run finishes. |
| The newest run kept no `upsolve-sync` artifact, or it expired | Re-run the workflow on GitHub, then sync again. |
| The Upsolve app cannot read this repository's workflow runs | On GitHub, accept the App's request for **Actions: read**, then sync again. |
| The sync artifact has no `upsolve.yml` | Restore `upsolve.yml` at the repository root. |
| `DRAFT_NOT_PUBLISHED` | Someone changed a repository-owned section in Upsolve before it was connected, and never published it. Publish or discard the draft, then sync again. |
| `RLS_UNKNOWN_MODEL` | `upsolve.yml` has an RLS rule for a name that is not a dbt model. |
| `FACT_TABLE_NOT_FILTERED` | `upsolve.yml` declares row-level security, but a model behind a MetricFlow measure is filtered by nothing. Add a condition for it under `rls.tables`, or a column rule on a column it has. |
| `FACT_TABLE_WITHOUT_RLS` | `require_on_facts` is on and a model behind a MetricFlow measure has no condition of its own. Add one under `rls.tables`: a global column rule does not count here. |
| The dbt project has no models to sync | The parsed target has no enabled models. Check the target in `upsolve.yml`. |
| `upsolve.yml` declares row-level security, which needs the Team plan | Upgrade, or remove the `rls` block. |
| `RLS_CONFIRMATION_NEEDED` | The commit loosens row-level security. An owner or admin opens the sync chip, reviews and accepts it, or revert the commit. |
| `RLS_UNKNOWN_PLACEHOLDER` | An RLS condition uses `{{x}}`. Write `{{user.x}}` or `{{organization.x}}`. |

Artifacts are kept for seven days, so a sync can only read a run from the last week. Push a commit (or re-run the workflow) to make a fresh one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.