Git workflow

Platform (dbtCharts.com)

This page describes dbt Charts Platform, the hosted product at dbtCharts.com. These features are not part of the open source dct engine.

Platform reads and writes your boards through git; the repository stays the source of truth, and every edit made in Platform is a real git commit you can see, review, and merge. This page walks the whole lifecycle: the two branches every project has, how edits become commits, change branches and merging, review mode, and what the Git settings screen tells you.

Connecting a repository in the first place is covered in Getting started; this page assumes a project is already bound to one.

Two branches: the repository branch and the dbt Charts branch

Every project tracks two branches:

• The repository branch (usually main) is your repository's default branch, the one your team merges to. Platform never commits to it directly.
• The dbt Charts branch is the branch Platform serves, renders, and edits. Every board save in Platform becomes a commit on it, authored by the person who saved. Platform keeps it in your repository under the name dbt-charts/<project> by default, so it is visible there like any other branch, and changes flow into the repository branch through your normal process. On GitHub, GitLab (as a merge request) and Bitbucket, Platform maintains a rolling pull request from the dbt Charts branch automatically; it opens with the first pushed edit and keeps updating as more land, and a Create PR button on the Git settings screen brings it back if it was closed.

Syncing keeps both sides current: Platform pulls the repository branch, then carries the new commits forward into the dbt Charts branch so boards in Platform reflect what your team merged. Platform's own commits flow the other way with each push of the dbt Charts branch.

When a project reviews changes as pull requests on the repository host, dbtcharts.com serves the repository branch instead: a board shows what your team merged, and a change is live once its pull request merges and Platform syncs. Edits never land on the dbtcharts.com branch.

Quickstart boards

Some Fivetran dbt packages ship starter boards for their models. Platform doesn't run dbt deps, so it can't read them from dbt_packages/. Instead, when a sync finds your project pinning a supported package in packages.yml or package-lock.yml, Platform commits that package's boards to charts/<package>/ on the dbt Charts branch, in one commit authored by Platform, and pushes it like any other edit. From there they are ordinary boards: edit, move, or delete them, and your changes stick. Platform adds a package's boards to a project once, and never over a charts/<package>/ folder the project already has. A project in branch mode gets none, since its dbt Charts branch only advances through merges. Supported today: fivetran/zendesk, pinned through dbt Hub or the https://github.com/fivetran/dbt_zendesk.git Git repository. HTTPS and SSH Git pins are recognized in either pin file.

Before rendering, connect the warehouse and map the project's default source to the dbt target's database and base schema or dataset, before dbt adds package or custom-schema suffixes. Platform does not read your local profiles.yml. Keep the boards' ref() calls and dialect: duckdb declarations: dbt Charts resolves the model locations and translates the authored SQL for the connected warehouse.

Pushing is not publishing

A git push puts your commit on your git host. Platform publishes it on the next sync, which is also what re-renders the boards the commit changed. Those are two separate events, and how soon the second one follows the first depends on how the project is connected:

Connection	What syncs it automatically
GitHub (App or token), GitLab or Bitbucket	The push itself. The host sends a webhook and the sync starts within seconds. A daily reconcile picks up a delivery that never arrived.
Other Git host	Nothing watches the remote, so an hourly sweep is the only automatic sync. A push can wait up to an hour.

Under pull-request reviews the same holds for a merge: a pull request merged on the host is published by the sync that follows it.

Either way you can publish immediately, from the Git settings screen's Sync now button or from the CLI:

dct cloud project sync

How to know your change is live. dct cloud boards prints, per board, when its served render ran and the commit that render read the board from:

SLUG            STATUS  RENDERED_AT       COMMIT   URL
exec-overview   ready   2026-09-06 10:50  8a2f27c  https://dbtcharts.com/acme/analytics/d/exec-overview

Read it before your push and again after the sync. A board you edited is serving your work once its own two values move: a later RENDERED_AT, and a different COMMIT.

If neither has moved, the change is not confirmed yet rather than not published. A sync queues the re-renders and they run behind live page views, each re-running the board's queries, so this can take a few minutes on a slow warehouse. STATUS needs its own reading, because a render that fails writes no new complete render, so the two columns cannot move for it: they only ever prove success. A warning that appeared since your first reading is your answer, because the only way a board reaches it is a newer failed attempt: the re-render ran and failed. A warning that was already there is inconclusive, since it carries no date and may be the old failure or a new one of your own commit, so open the board rather than dismissing it. An unchanged errored is the previous render's chart diagnostic, because it describes the very render RENDERED_AT names. A board still reading ready or not_rendered with nothing moved is simply waiting on its queued re-render; look again shortly, and run dct cloud project sync only if you are not sure the sync ever ran.

Compare only the boards your commit changed. A board it did not touch normally keeps both values, because nothing re-renders content that did not change; that is a board already serving the right bytes, not one waiting to catch up.

COMMIT names a commit in Platform's copy of the repository, which is not always one of yours. Platform commits its own board edits to the dbt Charts branch and merges your repository branch into it on every sync, so on a project that has been edited in Platform the served commit is a dbt Charts branch commit and will not equal your git rev-parse HEAD. On a project only ever edited through git the two are the same sha. The sha changing is the signal in both cases.

STATUS: ready on its own only means a render exists, not that it is a render of your edit. A board that has never finished a render shows - in both columns, as does one last rendered before Platform began recording commits; neither is backfilled with a guess, and the column fills in on the board's next render.

The Git settings screen

Settings → Git is the home for all of this. The Status card shows when the project last synced and pushed and how far the dbt Charts branch is ahead of the repository branch; the Connection card shows the repository, the repository branch and dbt Charts branch names, and the folder inside the repository the project reads (for repositories that hold more than one project). The Files panel browses exactly what Platform sees at the dbt Charts branch tip: the same files, at the same commit, that your boards render from.

When a sync cannot complete (the histories have diverged after a force push, or Platform's copy of the repository is missing something it needs) the status is reported here too, with the reason, instead of silently serving stale boards.

When a project reviews changes as pull requests on the repository host, Platform syncs only the repository branch: it no longer fetches, merges into or pushes the dbtcharts.com branch, and leaves that branch as it is. A pull request Platform opened before the switch stays open on the host; merge or close it there.

Change branches

Edits don't have to land on the dbt Charts branch directly. The Branches screen (linked from the Git settings) lists every branch Platform knows about and lets you create a change branch: a branch off the dbt Charts branch where a set of edits can be developed together and merged as one unit.

While a change branch is open you can browse and edit any board on it: board URLs gain a branch scope (/b/<branch>/…), so a link to the in-progress version is shareable like any other board. When the work is ready, Merge shows you the changed files and folds the branch back into the dbt Charts branch, and if the two branches changed the same lines, Platform walks you through a three-version resolution screen instead of merging blindly. Delete discards the branch. On GitHub, GitLab and Bitbucket, an org admin can also use Open PR to send a change branch straight to the repository branch as a pull request, skipping the dbt Charts branch, for changes that should go through your repository's own review instead of Platform's.

When a project reviews changes as pull requests on the repository host, a change branch is cut from the repository branch instead, and its changed files are compared against the repository branch, so they match the pull request's own diff.

Review mode

By default a project is in direct mode: saves commit straight to the dbt Charts branch, and change branches merge without a review step. On the Enterprise plan, projects that want an approval step can turn on branch mode, under Review mode in the project's Settings → General:

In branch mode the dbt Charts branch advances only through reviewed merges: every edit happens on a change branch (the Merge button becomes Request merge), and merging one starts with a request. The Branches screen says which mode the project is in, so you can confirm the switch took. The Authors can merge their own changes switch below it is off by default: someone else with merge permission has to approve every review. Both switches save the moment you flip them.

When the project reviews changes as pull requests on the repository host, the pull request is the review and merging happens there. If your change branch conflicts with the repository branch, update it from the repository branch on dbtcharts.com; the pull request then merges on the host.

In an organization that reviews pull requests on the host, turning branch mode on waits for the dbtcharts.com branch to be pushed. While that branch holds commits the repository has not received, or its last push failed, the switch is refused with the reason.

Edits you make from a board, a folder page, or the AI assistant collect on one change branch of your own until you propose it. Once that branch is under review, merged, or closed, your next edit starts a new one; a review that requests changes keeps taking them. Renaming or moving a board or folder changes who can see it only when the change merges: until then the dbt Charts branch keeps the board at its old path with its old access. The moved board on your branch keeps that same access, unless you chose to let it take its new folder's access; sharing changes made at the old path meanwhile reach it when the change merges.

The request page previews the review it opens: every changed board with the current and proposed versions rendered side by side, a visual comparison that can highlight exactly the pixels that changed, and the exact YAML diff. Submitting it opens the review. The author sees it as awaiting review and can withdraw it. A reviewer who holds the Merge reviews permission on every file the review changes (and at project level for files that are not boards) can Approve & merge, Request changes, or close the review; approving merges the branch into the dbt Charts branch. A member who can edit boards but cannot merge can still request changes. The built-in Admin role carries the merge permission.

Which branch you are on

The branch you are on is yours, not part of the address. Check out a change branch from the Branches screen, or pick one in the rail's branch menu, and every page you open (the project home, folders, boards, search and chat) shows that branch until you go back. A bar above the page names the branch, counts its changes, and offers Request merge (or View review once one is open) and Back to the dbt Charts branch. Your first edit on the dbt Charts branch in branch mode starts a change branch and checks you out on it, and when the branch merges you land back on the dbt Charts branch. A link with /b/<branch>/ in it still opens that branch for whoever follows it, without moving you. Board and folder actions (rename, move, duplicate, delete, new folder) and data file uploads run on the branch you are on, and the Data Sources settings list the file sources on that branch.

Commit history

The Commits screen (also linked from the Git settings) lists recent commits on the dbt Charts branch: who saved what, when, and the files each commit touched, with expandable diffs. Because every Platform edit is a real commit, this is the full audit trail of how your boards got to their current state, and it reads the same in Platform and in git log.

Related

• Getting started: connecting the repository and creating the project.
• Access control: who can edit which boards; edits always commit as the person who made them.
• Refresh: keeping board data current between edits.