# Add Model Groups and Access Levels to a dbt Project

Yes. An agent adds a dbt group with an owner, marks staging models private and marts public, proves the rules with dbt parse and opens a pull request.

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

## What the agent does

The agent reads the project as it is. In a repository shaped like dbt-labs/jaffle-shop, `dbt_project.yml` names the project `jaffle_shop` at version 3.0.0 with `require-dbt-version: ">=2.0.0"`, sets `staging` models to views and `marts` to tables, and gates the `jaffle-data` seeds behind a `load_source_data` variable. There is no `groups:` block and no `access` or `group` property on any model. `models/staging/__sources.yml` declares the `ecom` source in the `raw` schema with six tables, six `stg_*` models each have a YAML file with `not_null` and `unique` tests and a `dbt_utils.expression_is_true` check, and `stg_orders.sql` reads the source, renames columns and converts cents through the project's own `cents_to_dollars` macro. `models/marts` holds `customers`, `orders`, `order_items`, `products`, `locations`, `supplies` and `metricflow_time_spine`, and `orders.yml`, `customers.yml` and `order_items.yml` carry the semantic layer spec with `semantic_model: enabled: true`, entities, dimensions and `type: simple` metrics. `packages.yml` pins `dbt_utils` 1.4.1 and `dbt-audit-helper` from git, `.sqlfluff` sets the Snowflake dialect with the `dbt-cloud` templater, and `.github/workflows/ci.yml` triggers dbt Cloud CI jobs for Snowflake, BigQuery and Postgres on each pull request.

The design follows how dbt enforces access. A `private` model can be referenced only by models in its own group, a `protected` model by any model in the same project, and a `public` model by other projects too. The marts read the staging models, so staging and marts must share a group for staging to be private; the agent therefore adds `models/groups.yml` with one group, `jaffle_shop`, whose `owner` has a `name` and an `email` placeholder for the reviewer to fill in, since dbt requires an owner on every group. In `dbt_project.yml` it adds `+group: jaffle_shop` under `models.jaffle_shop`, `+access: private` under `staging` and `+access: public` under `marts`, so every model inherits its group from the project folder and its access from its layer, and a new staging model is private without anyone remembering to say so. Where a model file already has a YAML entry, it adds nothing, because the folder-level config is the single source; the pull request says so to stop the two from drifting.

Access rules only matter if something checks them, so the agent reads every `ref()` in `models/marts` and confirms each one points at a staging model or another mart, all inside the one group. It then writes a deliberate violation, a scratch model assigned to a second scratch group that refs `stg_orders`, runs `dbt parse`, keeps the error message that names the private model and the referencing one, and deletes both the scratch model and the scratch group, so the pull request shows what the rules refuse rather than asserting it. Because the repository has no `profiles.yml` and the sandbox has no warehouse credentials, it installs `dbt-core` with the Postgres adapter, writes a throwaway profile outside the repository with placeholder values, and runs `dbt deps` and `dbt parse`, which read the project and the packages without opening a connection.

It also adds a short section to `README.md` on what `private` means for the `stg_*` models, why marts are `public`, and how a future second group would need its own staging layer or a `protected` model to read from, runs `sqlfluff lint` only if the templater can run without dbt Cloud credentials and otherwise says it skipped it, and then pushes a branch and opens a pull request. The repository's dbt Cloud CI jobs run on the pull request as they do for every change, and a parse error from a wrong group would stop those jobs at the start.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add model groups and access levels to this dbt project. Define one group with an owner in models/groups.yml, assign every model to it in dbt_project.yml, set +access private on the staging folder and +access public on the marts folder, and confirm every ref in marts stays inside the group. Install dbt-core with the Postgres adapter, write a throwaway profile outside the repository, run dbt deps and dbt parse, show that a scratch model in a second group referencing a staging model fails to parse and remove it, add a README section on the group and the access levels, and open a 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 on its own branch with three files changed: a new `models/groups.yml`, a few lines added under `models.jaffle_shop` in `dbt_project.yml`, and a README section. The description names the group and its placeholder owner, states that `stg_*` models are now private to the group and the marts public, and quotes the parse error the deliberate violation produced.

The proof is in the session. The trajectory at `GET /o/{org}/sessions/{id}/messages` keeps the `dbt deps` and `dbt parse` output for the clean project and the error output for the scratch violation, so a reviewer sees dbt enforce the rule rather than a sentence claiming it will. The dbt Cloud CI jobs the repository already runs on each pull request start from the same parse.

Before merging, a reviewer replaces the owner placeholder with the real team and address, confirms that no analysis or downstream project reads a staging model directly, since it no longer can, and decides whether `metricflow_time_spine` should be public with the other marts or protected. Nothing about the SQL, the tests or the semantic models changes in this pull request.

## Run it on every new model layer added

An analytics team that grows the project by folder sends `POST /o/{org}/sessions` with this prompt when a new layer appears, such as an `intermediate` folder, naming the folder and the intended access in the prompt and the repository in `resources`. Each run reads `models/groups.yml` and the `dbt_project.yml` config as they are, adds one folder-level block, and checks the refs again with `dbt parse`.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when the turn ends, with `session_url` to read the pull request from. A `request_id` that is a UUID v5 of the folder name makes a retried request return the run it already started instead of opening a second pull request.

## Why run it on Rush?

Groups and access are a small edit that is easy to get wrong in one direction: mark a model private, miss one `ref` from outside its group, and the whole project stops parsing on the next CI run. On Rush the run reads every `ref` in its own cloud sandbox, runs `dbt parse` with a throwaway profile, and provokes the error on purpose so the pull request shows exactly what the rule refuses, while your own `profiles.yml` and warehouse credentials never leave your machine.

The result is checkable rather than claimed. The pull request is three files, the trajectory keeps the parse output for the clean project and for the violation, and the repository's dbt Cloud jobs run on the pull request as usual. Nothing reaches main until it merges.

## Frequently asked questions

### Does dbt parse need a warehouse connection?

No. `dbt parse` reads the project, the packages and the profile and builds the manifest without connecting, which is enough to enforce group and access rules. The agent writes a throwaway profile with placeholder values outside the repository and never receives your credentials.

### Why one group rather than one per folder?

Because a private model can only be referenced from its own group, and the marts reference the staging models. Separate staging and marts groups would make every mart fail to parse. One group with private staging and public marts gives the protection most teams want; a second group makes sense when a second domain gets its own staging layer, and the README section the agent adds says so.

### Why set group and access in dbt_project.yml rather than in each model's YAML?

The folder-level `+group` and `+access` config applies to every model under `staging` and `marts`, including ones added later, and keeps one place to read. Per-model properties would work too, and the agent uses them if your prompt asks for a model that differs from its folder.

### Who should own the group?

dbt requires a `name` or `email` on the group's `owner`, and the agent cannot know your team, so it writes a placeholder and marks it in the pull request for the reviewer to fill in. A follow-up on the same session can set it from a value you provide.

### Does this change any SQL or the semantic models?

No. The models, tests, sources, seeds and the semantic layer YAML are untouched. The pull request adds a groups file, a few lines of project config and a README section, and the trajectory shows the parse output before and after.

## More dbt jobs

- [Ship a Breaking Change to a dbt Model With Model Versions](https://getrush.ai/run/add-model-versions/dbt/)
- [Add dbt-checkpoint Pre-commit Hooks to a dbt Project](https://getrush.ai/run/add-pre-commit-hooks/dbt/)
- [Add Semantic Models and Metrics to a dbt Project](https://getrush.ai/run/add-semantic-models/dbt/)

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

- [Add a Minimum Supported Rust Version Check to a Rust CLI](https://getrush.ai/run/add-msrv-check/rust-cli/)
- [Add an MSRV Check to a Tokio Project](https://getrush.ai/run/add-msrv-check/tokio/)
- [Serve Storybook Stories From the App's MSW Handlers](https://getrush.ai/run/add-msw-to-storybook/msw/)

## 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/)
