All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading