Skip to main content
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 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 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
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
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

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