# Publish dbt Docs to GitHub Pages

Yes. An agent adds a workflow that builds your dbt project on DuckDB, runs dbt docs generate, and deploys the site to GitHub Pages on every merge, then opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/publish-dbt-docs/dbt/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the project is built and where its CI runs before it writes a workflow, because a docs site has to be generated from a compiled project with a reachable target. In a project shaped like dbt-labs/jaffle-shop, `dbt_project.yml` names `jaffle_shop` at version `3.0.0` with `require-dbt-version: ">=2.0.0"` and `profile: default`, puts staging models in views and marts in tables, keeps `target/` in `clean-targets`, and enables the seeds under `seeds/jaffle-data` only when the `load_source_data` var is true. `packages.yml` pulls `dbt-labs/dbt_utils` 1.4.1 and `dbt-audit-helper` from git. `.gitignore` already excludes `target/`, `dbt_packages/`, `logs/` and `profiles.yml`, and `requirements.txt` holds `pre-commit`, `requests` and `jafgen` but no dbt; the `Taskfile.yml` installs `dbt` into a venv. `models/staging/__sources.yml` declares the `ecom` source with six raw tables, every mart has a YAML file with descriptions, data tests and metrics, and `macros/cents_to_dollars.sql` dispatches on the adapter with a `default__` branch that casts with `::numeric(16, 2)`.

The three existing workflows, `ci.yml`, `cd_staging.yml` and `cd_prod.yml`, do not run dbt on the runner: each sets `DBT_ACCOUNT_ID`, `DBT_PROJECT_ID` and `DBT_PR_JOB_ID` and runs `.github/workflows/scripts/dbt_cloud_run_job.py`, which triggers a dbt platform job with a `DBT_CLOUD_API_KEY` secret and polls it, on `macos-latest` with Python 3.12 and `uv`. The dbt platform's own Catalog is refreshed by those jobs, but nothing produces a static site, and dbt's documentation says a `dbt docs generate` step in a platform job is turned into `dbt compile --write-catalog` and produces no `index.html`. A site anyone can open from a link has to be built by the repository itself.

The agent adds `.github/workflows/docs.yml` on `push` to `main` and `workflow_dispatch`, with two jobs. `build` runs on `ubuntu-latest`, sets up Python 3.12 and `uv` as the other workflows do, installs dbt at a release that satisfies `require-dbt-version` together with the DuckDB adapter, writes a `profiles.yml` for the `default` profile into the runner's home directory with a DuckDB file under the runner's temp path, and runs `dbt deps`, `dbt seed --full-refresh --vars '{"load_source_data": true}'`, `dbt build`, and `dbt docs generate --output-dir site`, which dbt v2 documents as writing a self-contained directory, the app, hashed assets and a copy of the index, meant for GitHub Pages and similar hosts. Building before generating is what gives the site real column types rather than only what the YAML says. The job uploads `site/` with `actions/upload-pages-artifact`. `deploy` needs `build`, runs in the `github-pages` environment with `permissions: pages: write` and `id-token: write`, and calls `actions/deploy-pages`, whose output is the site URL. A `concurrency` group on `pages` keeps two merges from racing.

Proof in the sandbox is the same sequence by hand: the agent installs dbt with the DuckDB adapter, writes the throwaway profile outside the clone, runs `dbt deps`, the seed, `dbt build` and `dbt docs generate --output-dir site`, lists `site/`, serves it with `python -m http.server` and opens it in the sandbox browser to confirm the lineage graph and the `orders` model page render, keeping a screenshot. The `default__cents_to_dollars` branch is the one DuckDB gets, since no `duckdb__` variant exists, and the build output in the record shows how it compiled. It runs `actionlint` on the new workflow and `pre-commit run --all-files` with the repository's hooks, adds `site/` to `.gitignore`, and writes a README section with the one step the API cannot do: in the repository's settings, under Pages, set the source to GitHub Actions.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Publish this dbt project's documentation to GitHub Pages and open a pull request. Read dbt_project.yml, packages.yml, requirements.txt, Taskfile.yml, .gitignore, .pre-commit-config.yaml, README.md, every workflow under .github/workflows and the script they call, models/staging/__sources.yml and macros/cents_to_dollars.sql first. Add .github/workflows/docs.yml on push to main and workflow_dispatch with a build job on ubuntu-latest that sets up Python 3.12 and uv, installs dbt at a release satisfying require-dbt-version with the DuckDB adapter, writes a profiles.yml for the default profile pointing DuckDB at a file under the runner temp directory, runs dbt deps, dbt seed --full-refresh --vars '{\"load_source_data\": true}', dbt build and dbt docs generate --output-dir site, and uploads site with actions/upload-pages-artifact; and a deploy job in the github-pages environment with pages: write and id-token: write that runs actions/deploy-pages, with a concurrency group. Do not change the existing dbt platform workflows or any model. In the sandbox run the same commands with a profile outside the repository, list site, serve it locally and open the lineage graph and the orders model page in the browser, take a screenshot, run actionlint on the workflow and pre-commit run --all-files, add site/ to .gitignore, and add a README section that explains enabling the Pages source as GitHub Actions. Paste every result and the site listing in the pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with `.github/workflows/docs.yml`, a line in `.gitignore` and a section in `README.md`. No model, macro, YAML file or existing workflow changes. The description shows the `site/` listing from the sandbox build, the screenshot of the lineage graph, the `dbt build` summary with every model, test and seed it ran, and says what must happen after merging: enable the Pages source in the repository settings, then the first push to `main` deploys.

The run's record keeps every command with its output: the adapter install, `dbt deps`, the seed, `dbt build` including how the `cents_to_dollars` cast compiled on DuckDB, `dbt docs generate`, the local serve, `actionlint` and the pre-commit run. The existing `dbt Cloud CI` workflow runs on the pull request as it does today, untouched.

Before merging, a reviewer decides whether the site may be public, since GitHub Pages on a public repository publishes model SQL, column descriptions and test names to anyone with the link, and whether the docs should build from the warehouse the platform jobs use instead of DuckDB, which would mean a warehouse secret on the runner. Then they merge, flip the Pages source, and open the URL `deploy-pages` prints.

## Run it on every merge to main

Once merged, the workflow itself runs on every push to `main`, so the site tracks the models that just landed with no further Rush run. To add the same workflow to several dbt projects, send one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`; each run reads its own `dbt_project.yml`, seeds and adapter needs, and opens its own pull request.

Give the API key a `webhook_url` and `run.completed` arrives with `data.session_url` for each run, so a script collects the pull request links and the site listings from the descriptions.

## Why run it on Rush?

A docs workflow is only trusted once someone has seen the site it produces, and producing it means a dbt install, an adapter, a profile that must not be committed, a seed load and a full build. In a Rush sandbox the agent does all of that on its own disk, opens the generated site in a browser and keeps the screenshot, the build log and the `site/` listing in the run's record, so the pull request arrives with the site already seen rather than a workflow that will be debugged on `main`.

DuckDB keeps the runner free of warehouse credentials, which is what makes the workflow safe to merge on day one; the pull request names the trade-off plainly. The same request works on any dbt project with a `dbt_project.yml`, each in its own sandbox at the same time.

## Frequently asked questions

### Why build on DuckDB instead of the project's warehouse?

The existing workflows reach Snowflake, BigQuery and Postgres only through dbt platform jobs and a `DBT_CLOUD_API_KEY`; the runner has no warehouse credentials. DuckDB builds the whole project from the seeds on the runner's disk, so the site has real column types with no new secret. A reviewer who wants warehouse-accurate docs swaps the adapter and adds the secret.

### Why run dbt build before dbt docs generate?

The site's column metadata comes from the relations that exist in the target. Generating without building gives pages with descriptions and lineage from the YAML but no column types. Building first on the seeded DuckDB file fills them in.

### Will the site be public?

On a public repository, yes: GitHub Pages serves it to anyone with the URL, and it contains model SQL and descriptions. On a private repository, Pages access follows the plan's settings. The pull request flags this for the reviewer rather than deciding it.

### Does the dbt platform Catalog change?

No. The platform jobs keep refreshing Catalog metadata on every run as before. This workflow adds a static site beside it, built by the repository, which is the form you can link from a README or a wiki.

## More dbt jobs

- [Review Pull Requests on a dbt Project](https://getrush.ai/run/review-pull-requests/dbt/)
- [Upgrade dbt and Its Packages](https://getrush.ai/run/upgrade-dbt-packages/dbt/)
- [Write dbt Data Tests](https://getrush.ai/run/write-dbt-tests/dbt/)

## More jobs like this: Hand off a long task

- [Reduce Cold Starts in Cloud Functions for Firebase](https://getrush.ai/run/reduce-cold-starts/firebase-functions/)
- [Reduce Cold Starts for a NestJS API on Serverless Framework](https://getrush.ai/run/reduce-cold-starts/serverless/)
- [Reduce a Docker Image's Size for a Flask App](https://getrush.ai/run/reduce-image-size/docker/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
