Skip to content

Getting Started

dbt charts Cloud

This page describes dbt charts Cloud, the hosted product — these features are not part of the open source dct engine.

Setting up dbt charts Cloud takes three steps: connect the git repository that holds your dbt charts project, create a project pointing at it, and connect your warehouse. At the end, every dashboard in your repo is live, shared, and updating on every push.

Before you start you need:

  • A git repository containing a dbt charts project — a dbt_charts.yml and a charts/ directory of dashboards. If you don't have one yet, build it locally first with the open source engine: see Installation and the Quick Guide.
  • A warehouse that Cloud can reach over the internet (see Data connections).

Sign in and create an organization

Sign up with an email address and password, or with Google or GitHub sign-in where offered (social sign-in is used only to authenticate you — it does not grant Cloud access to your repositories).

Everything in Cloud belongs to an organization: members, projects, and warehouse connections are all org-scoped. Create one with a name and a URL slug, and you become its owner. Invite teammates by email — each invitation is a single-use link that expires after seven days. Members hold one of three org roles:

  • Owner — everything, including managing other owners. An org always keeps at least one.
  • Admin — manages members, the git connection, and warehouse connections.
  • Member — uses projects and dashboards, subject to access control.

Connect your git repository

Cloud reads dashboards straight from git — the repository stays the source of truth. There are two ways to connect one:

GitHub (recommended). Connecting starts in Cloud and finishes on GitHub. You authorize the dbt charts GitHub App, and Cloud then asks GitHub — as you, right then — which repositories you can reach. It offers only the ones GitHub says you administer, and connects the one you pick. Nothing about that answer is stored: every connection re-asks. Once connected, every push syncs automatically via webhook.

Two things follow from letting GitHub decide:

  • Admin on the repo is the requirement. Write access is not enough. If a repository you expected isn't offered, you don't administer it on GitHub — ask a GitHub admin for that repo, not a Cloud admin.
  • Cloud can't widen an installation. Which repositories an installation covers is chosen on GitHub, by someone who administers the account. If the App isn't installed yet, or covers the wrong repositories, Cloud sends you to GitHub's own install/configure page and picks the flow back up when you return. If you can't install it yourself, GitHub turns your install into a request for an account owner to approve — come back and connect once they do.

Git URL. Any other git host works via a plain https:// remote URL. The remote must be publicly reachable (private hosts and non-HTTP schemes are rejected), and syncing is by periodic poll or an on-demand sync rather than push webhooks.

One GitHub installation can serve several dbt charts organizations without sharing anything between them: an org only ever sees the repositories its own members connected. A repository can back more than one project in the same org — each project pins its own work branch, so distinct projects on the same repo are distinguished by branch, never by repository alone.

Disconnecting GitHub

Disconnecting GitHub (via Settings → GitHub → Disconnect) unbinds every project in the org from its repository — the projects themselves are not deleted. Their git data, branches, and dashboard history are preserved, and so is the repository URL on each project.

The GitHub App stays installed: it belongs to the GitHub account, and other dbt charts organizations may be using the same installation. Uninstalling it is done on GitHub, and that disconnects every org at once.

After disconnecting you can:

  • Reconnect — connect each project again from its Settings → Git page. There is no automatic re-link: reconnecting re-asks GitHub whether you still administer that repository, which is the point.
  • Delete a project from Settings → Projects if you no longer need it. This removes all dashboard and git data and cannot be undone.

Create a project

A project binds one repository (or one subdirectory of it) to a set of dashboards. Org admins create them — a project binds a repository to the whole org, so the tier matches what the action does.

GitHub (two-step). Step one hands you to GitHub, which reports back the repositories you administer; pick one. Cloud then reads that repo's default branch and tree to pre-fill the form: the project name and slug derive from the repository name, and the subdirectory is inferred from the location of your dbt_charts.yml (or charts/ directory) in the tree.

Git URL (one step). Follow the "Use a Git URL instead" link, and fill in all fields manually.

In either case you can edit the pre-filled values before saving. The fields are:

  • Name and slug — the slug becomes part of the project's URLs.
  • Repository — the GitHub repo you picked, or the git URL.
  • Subdirectory (optional) — where the dbt charts project lives inside the repo, e.g. data/dashboards. This is what makes monorepos work: several projects can share one repo with different subdirectories.
  • Default branch — the branch your team merges to (your repo's default branch if left blank on GitHub). It must exist. Cloud treats it as pull-only: Cloud never commits to it directly.
  • Work branch (optional, defaults to dbt-charts/<slug>) — the Cloud-owned branch where edits made in Cloud land. It must not already exist on the remote; Cloud creates it. Changes reach your default branch the same way any change does — through a pull request, which Cloud opens and keeps updated for you.

On creation Cloud runs a first sync: it fetches the default branch, registers every dashboard in charts/, and discovers the source names your YAML references. If the sync fails (bad branch, unreachable remote), nothing is half-created — fix the issue and try again.

Connect your warehouse

Dashboards name their sources in YAML (source: warehouse); Cloud maps each name to an org-level warehouse connection. After the first sync, an admin is prompted to map any unmapped sources — create a connection (PostgreSQL, Snowflake, BigQuery, or Redshift), test it, and pick the sources it serves. The full flow, per-warehouse fields, and security notes are on Data connections.

What you'll see

Once a project has a synced repo and mapped sources, its dashboards are live:

  • Dashboards track git. The dashboard list is exactly the board files in charts/ on the synced branch. Push a change and it shows up; on GitHub, sync is immediate via webhook.
  • Edits made in Cloud land on the work branch, visible immediately to the team and mergeable into the default branch via the rolling pull request. Dashboards under _drafts/ stay in a private working area until promoted — see access control.
  • Branch previews: append ?branch=<name> to preview any branch's YAML — see branch previews.
  • Freshness is governed by refresh policy — see Refresh.