Getting Started

dbt Charts Platform is the hosted product at dbtCharts.com, an optional layer on top of the open source dct engine documented everywhere else on this site. It connects to the git repository holding your boards and adds what a team needs beyond a single local dct serve process: who can see and edit which boards, warehouse connections shared across projects, comments, and Wizard, an AI agent that builds and edits boards with you. The YAML language, boards, charts, queries, and variables are unchanged: a board authored for Platform is the same YAML you preview locally.

Setting up Platform 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 board in your repo is live, shared, and updating on every push.

The easy way: hand this to your coding agent

The fastest path to a live board is to paste this into the coding agent you're already using in this repository and let it drive the setup end to end. The cloud-setup skill it reads carries every step; the prompt names it and grants the two permissions the setup needs, so the agent doesn't stop to ask for them halfway.

Paste into Claude Code, Codex, dbt Wizard, or any coding agent:

Publish this repository's boards to dbtcharts.com with dbt Charts. You may
push dbt Charts files to this repository's default branch and create a
read-only warehouse credential for dbt Charts Platform.
Start with: uv tool install dbt-charts && dct skills cloud-setup
(the install takes a few minutes: give it a long timeout rather than retrying)

The agent needs you in the browser once. It runs dct cloud login, which prints a code and a URL: sign in (or create an account), pick or create the organization the CLI should reach, and approve. Right after, unless the repository is public, it connects the repository itself: with gh signed in there is no browser step, otherwise it hands you a link to authorize GitHub and install the App, and the page after tells you to go back to the terminal, with nothing else to press. Everything else (connecting the project, wiring up the warehouse, mapping sources, rendering) the agent does itself, serving the boards locally so you can watch as it goes.

Prefer doing it by hand? The manual steps below are the same flow, walked through in the UI.

Everything here from the terminal. Each step below is also a dct cloud verb. To script the setup yourself, or to see exactly what the agent runs, follow Automating setup.

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 Platform can reach over the internet (see Data connections), unless your boards only read file sources.

Sign in and create an organization

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

Everything in Platform 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 admin. Invite teammates by email; each invitation is a single-use link that expires after seven days. Members hold one of three org roles:

• Admin: manages members, the git connection, and warehouse connections. An org always keeps at least one.
• Creator: uses and builds projects and dashboards, subject to access control. This is the default for a new invitation.
• Viewer: read-only. Access control still decides which dashboards they see, but a Viewer's grants are capped to view-only capabilities, so no grant can give them edit rights.

To let a whole company in without inviting each person, an admin adds an allowed email domain under organization settings, with the role (Viewer or Creator) and any teams new joiners get. Before saving, Platform shows how many existing users have a verified address at that exact domain; confirming adds them to the organization right away, and anyone who later signs up or verifies an address there joins automatically. People already in the organization are left as they are. You can only add a domain where you have a verified address yourself, and personal email providers such as gmail.com are refused. Someone who is removed stays out until an admin adds the domain again, they are invited back, or they verify or pair another address at the domain.

Connect your git repository

Platform reads dashboards straight from git; the repository stays the source of truth. A repository can be on GitHub, on gitlab.com, on bitbucket.org, or on any other host that serves plain HTTPS git. There are five ways to connect one. From the terminal, each is a dct cloud project connect subcommand named for its host (github, gitlab, bitbucket, git); see the CLI reference.

GitHub App (recommended). Connecting starts in Platform and finishes on GitHub. You authorize the dbt Charts GitHub App, and Platform 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 Platform admin.
• Platform 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, Platform 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.

GitHub personal access token. For organizations that don't allow GitHub App installs. Pick the GitHub tile, expand Use a fine-grained personal access token instead, and paste the repository URL and a token; see Personal access token below.

GitLab. Pick the GitLab tile on the New project page and paste the repository URL and an access token; see GitLab below for which token to create.

Bitbucket. Pick the Bitbucket tile on the New project page and paste the repository URL and a repository access token; see Bitbucket below.

Other Git host. A repository can also be connected by its plain HTTPS URL, with no App install. Pick the Other Git host tile on the New project page. For a private repository, enter a username and a password or token (from the CLI, dct cloud project connect git with --git-username and --git-password). The credential needs write access: Platform pushes your edits to the dbt-charts/<project> branch of the repository. Credentials in the URL itself and non-HTTP schemes are rejected, and syncing is by periodic poll or an on-demand sync rather than push webhooks.

A self-hosted Git server has to be reachable from the public internet, like a warehouse: a URL that resolves to a private or internal network address is rejected, and a server reachable only through a VPN cannot be reached at all. If the server restricts inbound traffic by address, allow 34.85.252.27/32, the same address Platform queries warehouses from; see Network access.

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 dbt Charts branch, so distinct projects on the same repo are distinguished by branch, never by repository alone.

Personal access token

Some GitHub organizations don't allow third-party App installs. For those, the GitHub tile also offers a fine-grained personal access token. Platform opens pull requests with it, as with the App, and registers a webhook on the repository with it. The webhook covers pushes and pull requests, so a push syncs within seconds and Platform learns when a pull request merges or closes. A daily reconcile picks up any delivery GitHub drops.

Create the token under Settings › Developer settings › Fine-grained tokens on GitHub:

• Resource owner: the account or organization that owns the repository. An organization that requires approval for tokens must approve it first.
• Repository access: Only select repositories, and pick the one repository. Metadata read-only is added automatically.
• Repository permissions: Contents: Read and write, Pull requests: Read and write and Webhooks: Read and write.

Platform uses the webhook permission to register that webhook, and removes it when you delete the project or point it at another repository.

Paste the repository URL (the HTTPS one from Code) and the token into Platform; Platform signs in as x-access-token, so there is no username to enter. Platform checks at connect time that the token can push, read pull requests and list the repository's webhooks. GitHub doesn't report a token's permissions, so a token without Pull requests: Read and write only fails when the first pull request opens, with a message naming the missing permission.

Fine-grained tokens expire, after at most 366 days, and belong to the account that created them; see Replacing a token.

GitLab

The GitLab tile connects a repository on gitlab.com with an access token. Self-managed GitLab is not covered by this tile; use Other Git host.

Whatever token you use needs the api scope and the Maintainer role on the project. Platform checks at connect time that the token can push, has the api scope, and can manage the project's webhooks, and rejects one that can't. Maintainer is what lets Platform register a push webhook on the project, so a push to the repository reaches Platform within seconds.

Platform opens merge requests for the dbt Charts branch like pull requests on GitHub: a merge request opens as a draft while a board fails to compile, and goes ready once every board compiles.

Token	Works	gitlab.com plan	Owned by	Expiry
Service account (project or group)	Yes, recommended	Free and up	Not a person	Can be none
Project access token	Yes	Premium and up	The project's bot	Up to 365 days
Group access token	Yes	Premium and up	The group's bot, for the whole group	Up to 365 days
Personal access token	Yes	All	A person	Up to 365 days
Deploy token	No	All		Read-only, no API

A service account is the recommended choice: it is not tied to a person, so the connection keeps working when people leave, and it is free on every GitLab plan. A project service account is created by a project Maintainer under Settings › Service accounts; a group service account needs an Owner of the top-level group. Add it to the project with the Maintainer role, create a personal access token for it with the api scope, and paste that token into Platform.

Bitbucket

The Bitbucket tile connects a repository on bitbucket.org with a repository access token. Bitbucket Data Center is not covered by this tile; use Other Git host.

Create the token under Repository settings › Security › Access tokens in the repository, and give it these permissions:

• Repositories: Write
• Pull requests: Write
• Webhooks: Read and write

Bitbucket shows the token only once, so copy it before leaving the page. Paste the repository URL (the HTTPS one from Clone) and the token into Platform; Platform signs in as x-token-auth, the username Bitbucket requires for these tokens, so there is no username to enter. Platform checks the token when you connect, and rejects one that can't manage webhooks. Webhooks: Read and write is what lets Platform register a push webhook on the repository, so a push to it reaches Platform within seconds.

A repository access token belongs to the repository, not a person, so the connection keeps working when people leave, and it is available on every Bitbucket Cloud plan. It only works for the repository it was created in. Bitbucket app passwords no longer work.

Platform opens a pull request for your edits as on GitHub: it opens as a draft while any board fails to compile and is marked ready once every board compiles.

Replacing a token

When a token expires or loses access, syncing stops and the project's Settings → Git page says so. Create a new token with the same permissions and paste it under Settings → Git → Edit; leaving the field blank keeps the saved token.

Disconnecting GitHub

Disconnecting GitHub (via Settings → General → Overview → Disconnect all repositories, beside the org's project list) 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 the bottom of its Project settings page. This removes its dashboards and Platform's git data, and cannot be undone. Platform also removes the push webhook it registered. The dbt Charts branch and any open pull or merge request stay in your repository for you to close.

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 App (two-step). Step one hands you to GitHub, which reports back the repositories you administer; pick one. Platform 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 folder path is inferred from the location of your dbt_charts.yml (or charts/ directory) in the tree. You can edit the pre-filled values before saving.

GitLab, Bitbucket, GitHub personal access token, and Other Git host (one step). Paste the repository URL and the credential on the tile's form and fill in the fields below yourself; nothing is pre-filled.

Managed repository (one step). Choose the Managed repository tile and give the project a name, a slug and an optional description. dbt Charts keeps the repository for you, so there is no Git host, token or App install, and the project is ready as soon as you create it. The tile appears only for organizations where managed repositories are turned on. A managed project has no Sync now or pull-request actions. Its Settings → Git screen shows Connect a repository; see Connect a managed project to a Git host.

The fields for a connected repository are:

• Name and slug: the slug becomes part of the project's URLs.
• Repository: the GitHub repo you picked, or the URL you pasted. Platform reads the dbt project from this same repository; boards in a separate repo from their dbt project work with dct but not yet in Platform.
• Folder path (optional): where the dbt Charts project lives inside the repo, for example, data/dashboards. This is what makes monorepos work: several projects can share one repo with different folder paths. If that folder's dbt_charts.yml sets boards_dir to anything but charts, the project is read-only in Platform: edit its boards in the repository.
• Repository branch: the branch your team merges to (your repo's default branch if left blank on GitHub). It must exist. Platform treats it as pull-only: Platform never commits to it directly.
• dbt Charts branch (optional): the Platform-owned branch where edits made in Platform land. Left blank, it is dbt-charts/<slug>, or dbt-charts/<slug>-2, -3 and so on if that name is taken. A name you choose must not already exist on the remote. Platform creates it. Changes reach your repository branch the same way any change does: through a pull request, which Platform opens and keeps updated for you.

On creation Platform 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.

The project's Settings → Git screen tracks the connection from here on: when it last synced and pushed, the repository and branches, and a file browser over exactly what Platform sees.

Connect a managed project to a Git host

When your team wants the project on GitHub, GitLab, Bitbucket or another Git host, open Settings → Git and choose Connect a repository. The page lists what gets pushed: the repository branch, the dbt Charts branch, the folder and the commit count. Pick a host, enter its credential, and choose Connect repository.

1. Create the repository on the host first, empty: no README, .gitignore or license. A repository that already has commits is refused.
2. For GitHub, choose Continue with GitHub, pick the repository and confirm the push. GitLab, Bitbucket and Other Git host take a repository URL and a token (Other Git host also takes a username). The token needs write access, because dbt Charts pushes to the repository.
3. dbt Charts pushes the project's full history on both branches, then switches the project to the host. Until the push finishes the project stays a managed repository, and Settings → Git shows the progress.

If the push fails, Settings → Git shows the host's message and the project is still managed. Fix the problem on the host and connect again; a repository an earlier attempt half-filled is accepted. Connecting is one-way: the project cannot go back to a managed repository afterward.

Connect your warehouse

Dashboards name their sources in YAML (source: warehouse); Platform maps each name to an org-level warehouse connection. After the first sync, an admin is prompted to connect any source that has none: create a connection (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks, or Trino), test it, and choose the project sources it serves under Use in projects. A connection no source uses can't be queried, so finish this step before you chat with the data. 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.
• A push is not a publish. Your commit goes live on the next sync, which a GitHub, GitLab, or Bitbucket project starts within seconds of the push and an Other Git host project only picks up on an hourly sweep. dct cloud project sync (or Sync now on the Git settings screen) publishes right away, and dct cloud boards proves it landed: a board you edited gets a later RENDERED_AT and a different COMMIT once its re-render finishes. See the git workflow.
• Edits made in Platform land on the dbt Charts 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: board URLs gain a branch scope (/b/<branch>/…) to view any branch's version; see the git workflow.
• Freshness is governed by refresh policy; see Refresh.
• The New menu on the project home adds a folder, a board, a board recreated from a screenshot, or a data file; see Attach files in chat and Upload a file on dbtcharts.com.

Open a board in fullscreen

Add ?_fullscreen=true to a board URL to open it in fullscreen, the same presentation view as the board's present button. It suits wall displays and shared links meant for presenting:

https://dbtcharts.com/<org>/<project>/d/<board>?_fullscreen=true

• Other parameters are kept. Platform switches fullscreen on, then redirects to the same URL without _fullscreen, so board variables such as region=EMEA still apply.
• It sticks for your session. Later boards you open in the same browser session stay fullscreen. ?_fullscreen=false leaves fullscreen the same way.
• Only true and false are accepted. Any other value gets a 400 error.
• Exit button. A fullscreen board shows an Exit button in the top right corner while the mouse is moving, and hides it again when the mouse stops.
• Requests with a bearer token (such as the CLI) never set the session flag.

Related

• dct cloud: every step on this page from the terminal
• Data connections: warehouse types, testing, and source mapping
• Access control: who can see and edit what
• Refresh: keeping dashboard data current
• AI Wizard: tuning what the project's chat panel knows