All jobs

Add dbt-checkpoint Pre-commit Hooks to a dbt Project

Yes. An agent extends your dbt project's pre-commit config with dbt-checkpoint hooks that fail a commit when a model lacks a description or tests, and 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 what the project already runs before a commit. In a project like dbt-labs/jaffle-shop, .pre-commit-config.yaml has two repos: pre-commit-hooks at v6.0.0 with check-yaml, end-of-file-fixer, trailing-whitespace and requirements-txt-fixer, and ruff-pre-commit at v0.14.10 with ruff-check --fix --exit-non-zero-on-fix and ruff-format. Both are about YAML, whitespace and Python; nothing looks at a model. requirements.in asks for pre-commit>=3.6.0, requirements.txt is compiled by uv and pins pre-commit==3.7.0, and the README's pre-commit section explains the four checks and says SQLFluff was left out on purpose because it does not work well with the dbt Cloud IDE, keeping .sqlfluff (dialect snowflake, templater dbt-cloud) only as a future-proofing file. The agent respects that decision and does not add a SQLFluff hook.

It then measures the models against the checks it is about to add. dbt_project.yml names the project jaffle_shop at version 3.0.0, puts tests under data-tests/, which is empty, and configures staging as views and marts as tables. Six staging models and seven marts have properties files, and every model has a description. Column documentation is uneven: the staging files describe every column, orders.yml and customers.yml describe most, but locations.yml describes none of its three columns, products.yml and supplies.yml describe only the model, and metricflow_time_spine.yml has a date_day column with no description. Tests are uneven too: every stg_* model has not_null and unique on its id, orders and customers carry model-level dbt_utils.expression_is_true tests, order_items tests its columns, and locations, products, supplies and metricflow_time_spine have no test at all, even though locations.yml already marks location_id as a primary entity. packages.yml pins dbt_utils 1.4.1 and dbt-audit-helper from git, with the resolved commit in package-lock.yml.

From that the agent adds a dbt-checkpoint repo to the config at a pinned tag and chooses hooks the repository can pass on the day they land: check-model-has-description, check-model-has-properties-file, check-script-semicolon, check-script-has-no-table-name, which passes because every model selects from ref() or source(), and check-model-has-tests with --test-cnt 1. For the last one it adds not_null and unique on the primary key of the four models that have none, date_day in the case of the time spine, the same shape the staging models use, so the hook holds everywhere rather than being scoped around the gap. check-model-columns-have-desc is added with a files filter limited to models/staging/, where it already passes, and the pull request lists the marts columns that would have to be described before the filter can be widened. The dbt-checkpoint hooks read target/manifest.json, so the agent adds the dbt-parse hook ahead of them and documents in the README section that a local profile is needed for the parse.

Before opening anything the agent installs pre-commit from requirements.txt and the dbt CLI the Taskfile.yml installs, writes a throwaway profiles.yml outside the repository, runs dbt deps and dbt parse, and runs pre-commit run --all-files to see every hook pass over the whole tree, including the new tests it added. Because .github/workflows/ci.yml only triggers dbt Cloud jobs through dbt_cloud_run_job.py and never runs pre-commit, it adds a small lint job to that workflow that installs the same pins, parses with a dummy profile and runs pre-commit run --all-files, so a commit made from the dbt Cloud IDE, where git hooks do not run, is still checked on its pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add dbt-checkpoint hooks to this dbt project's pre-commit configuration. Read .pre-commit-config.yaml, requirements.in, requirements.txt, dbt_project.yml, packages.yml, package-lock.yml, Taskfile.yml, the README's pre-commit section, .github/workflows/ci.yml and every properties file under models/ first. Keep the existing hooks and do not add SQLFluff, since the README explains why it was left out. Add the dbt-checkpoint repo at a pinned tag with dbt-parse first, then check-model-has-description, check-model-has-properties-file, check-script-semicolon, check-script-has-no-table-name and check-model-has-tests with --test-cnt 1; add not_null and unique tests on the primary key of each model that has no test so that hook passes everywhere; add check-model-columns-have-desc scoped with a files filter to the directory where every column is already described, and list in the pull request the columns that block widening it. Install pre-commit and dbt in the sandbox, write a throwaway profile outside the repository, run dbt deps, dbt parse and pre-commit run --all-files, and fix anything that fails. Add a lint job to the GitHub Actions workflow that runs the same pre-commit pass on pull requests. Update the README's list of checks and open a pull request with the pre-commit output.",
  "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

The pull request changes .pre-commit-config.yaml, adds data_tests to the four marts properties files that had none, adds a lint job to .github/workflows/ci.yml, and extends the README's list of checks. No SQL changes: the models, macros and seeds are as they were, and the dbt Cloud jobs in the workflow are untouched.

The description lists each new hook with what it checks and quotes the pre-commit run --all-files summary from the sandbox showing every hook passing, followed by the table of marts columns without descriptions that the scoped hook leaves for later. The dbt parse and pre-commit commands with their full output are in the session transcript at GET /o/{org}/sessions/{id}/messages.

Before merging, a reviewer reads the new tests to confirm the keys they assert are the right grain for those models, checks the pinned dbt-checkpoint tag, and runs pre-commit install once locally so the hooks fire on their own commits. A follow-up message to the same session can add the missing column descriptions and widen the files filter to the whole models/ tree.

Run it on every terminal hand-off

An analytics engineer who keeps catching undocumented models in review starts this from the terminal with this body and goes back to the model they were writing. The run reads the real properties files, so the hooks it enables and the tests it adds come from where the project stands, not from a default list that fails on day one.

Send a request_id, a UUID, with the body so a retried start returns the run it already began. When the run finishes, its GET /o/{org}/sessions/{id} answer names the pull request.

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

Why run it on Rush?

The hard part of adopting dbt-checkpoint is not the YAML, it is finding out which hooks the repository can pass and closing the gaps so the first commit after merge does not fail for everyone. The agent runs the whole pass in its own sandbox with a parsed manifest, reads what fails, adds the tests or the scope needed, and runs it again until it is clean, before anyone else sees it.

Every dbt parse and pre-commit run the agent executed is kept with its output in the session record, so the claim that the hooks pass is backed by the run that showed it. A data team with several dbt projects can send this request for each at once and get one pull request per project, each with the hooks that project can hold today and a list of what blocks the rest.

Frequently asked questions

Why not add SQLFluff while you are at it?

Because the project's README says it was left out deliberately: the dbt-cloud templater does not work well with the dbt Cloud IDE, and .sqlfluff is kept only as a reference. The agent follows the repository's stated decision and names it in the pull request, so a team that has moved to the local CLI can ask for it in a follow-up.

Do the hooks need a warehouse connection?

The dbt-checkpoint checks read target/manifest.json, which dbt parse produces without running a query, but parsing needs a profile that names an adapter. The README section the agent writes shows a minimal local profile, and the CI job uses a dummy one for the same reason.

Will commits from the dbt Cloud IDE be checked?

Git hooks do not run inside the IDE, so a commit made there bypasses pre-commit. That is why the agent adds a lint job to the GitHub Actions workflow: the pull request still gets the same pass, and a model without a description fails the check there.

Why scope the column-description hook to staging?

Because locations.yml, products.yml, supplies.yml and metricflow_time_spine.yml have columns with no description today, and enabling the hook repo-wide would fail every commit that touches them until someone writes the text. Scoping it to models/staging/ makes it enforceable now; the pull request lists the exact columns that stand between the team and the wider filter.

More dbt jobs

The same job on other stacks

Keep reading