Git workflow¶
dbt Charts Cloud
This page describes dbt Charts Cloud, the hosted
product — these features are not part of the open source dct
engine.
Cloud reads and writes your boards through git; the repository stays the source of truth, and every edit made in Cloud 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: upstream and work¶
Every project tracks two branches:
- The upstream branch (usually
main) is your repository's default branch, the one your team merges to on GitHub. Cloud never commits to it directly. - The work branch (named
dbt-charts/<project>by default) is where Cloud's edits land. Every board save in Cloud becomes a commit on this branch, authored by the person who saved. Cloud pushes it back to your remote, so the work branch is visible in your repository like any other branch, and changes flow into the upstream branch through your normal process. On GitHub, Cloud maintains a rolling pull request from the work 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: Cloud pulls the upstream branch, then carries the new upstream commits forward into the work branch so boards in Cloud reflect what your team merged. Cloud's own commits flow the other way with each push of the work branch.
Pushing is not publishing¶
A git push puts your commit on your git host. Cloud 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 | The push itself. GitHub sends a webhook and the sync starts within seconds. A daily reconcile picks up a delivery that never arrived. |
| Repository URL | Nothing watches the remote, so an hourly sweep is the only automatic sync. A push can wait up to an hour. |
Either way you can publish immediately, from the Git settings screen's Sync now button or from the CLI:
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 Cloud's copy of the repository, which is not always
one of yours. Cloud commits its own board edits to the work branch and merges
your upstream branch into it on every sync, so on a project that has been
edited in Cloud the served commit is a work-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 Cloud 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 work branch is ahead of upstream; the Connection card shows the repository, the upstream and work 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 Cloud sees at the work 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 Cloud'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.
Change branches¶
Edits don't have to land on the work branch directly. The Branches screen (linked from the Git settings) lists every branch Cloud knows about and lets you create a change branch: a branch off the work 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 work branch, and if the two branches changed the same lines,
Cloud walks you through a three-version resolution screen instead of
merging blindly. Delete discards the branch. On GitHub, an org admin
can also use Open PR to send a change branch straight to the upstream
branch as a pull request, skipping the work branch, for changes that
should go through your repository's own review instead of Cloud's.
Review mode¶
By default a project is in direct mode: saves commit straight to the work branch, and change branches merge without a review step. Projects that want an approval step can turn on branch mode, in Settings → Git → Edit:
In branch mode the work branch advances only through reviewed merges: every edit happens on a change branch (the Merge button becomes Propose), and merging one starts with a proposal. The Branches screen says which mode the project is in, so you can confirm the switch took.
A proposal opens a review: a page showing 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. A reviewer can Approve & merge, Request changes, or close the review; approving merges the branch into the work branch.
Commit history¶
The Commits screen (also linked from the Git settings) lists recent
commits on the work branch: who saved what, when, and the files each
commit touched, with expandable diffs. Because every Cloud 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 Cloud 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.