All jobs

Add dbt Exposures for Your Dashboards from a Linear Issue

Yes. An agent reads the Linear issue, declares each dashboard as a dbt exposure on the right models and metrics, checks the project builds and opens a pull request.

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 starts from the issue and the repository in its own cloud sandbox and reads the project before it writes YAML. In a project like dbt-labs/jaffle-shop (jaffle_shop version 3.0.0, require-dbt-version: ">=2.0.0"), dbt_project.yml puts staging models in views and marts in tables, seeds the raw schema from seeds/jaffle-data only when load_source_data is set, and names profile: default. models/staging/__sources.yml declares the ecom source with raw_customers, raw_orders, raw_items, raw_stores, raw_products and raw_supplies; models/marts/ holds customers, orders, order_items, locations, products, supplies and metricflow_time_spine, each with a YAML file. orders.yml and customers.yml enable semantic models and define metrics such as order_total, orders, new_customer_orders, large_orders, food_orders, drink_orders and tax_paid. A search for exposures: across models/ finds nothing, which is the gap the issue describes: dashboards exist outside the project and nothing in dbt knows which models they read.

Then it reads the issue's list of dashboards and maps each to the project's graph. For each one it decides the type (dashboard, notebook, analysis, ml or application), the maturity, the url, the owner with a name and email, and most importantly depends_on: ref('orders') and ref('customers') for a revenue dashboard, metric('order_total') and metric('new_customer_orders') where the dashboard reads the semantic layer rather than a table, source('ecom', 'raw_orders') only if a dashboard really reads raw data. It cross-checks each dependency against the existing YAML so a typo in a model name fails at parse time, not in review.

The change lands in one new file, models/marts/exposures.yml, with an exposures: block, one entry per dashboard, in the same key order and description style the mart YAML files use. Nothing else in the project changes: no model, no test, no package. packages.yml keeps dbt_utils at 1.4.1 and dbt-audit-helper from git, and the agent runs dbt deps so parsing sees them.

The project's own CI in .github/workflows/ci.yml runs jobs in dbt Cloud against Snowflake, BigQuery and Postgres through a DBT_CLOUD_API_KEY secret, which a sandbox does not have. So the agent proves the change locally: it installs dbt with an adapter it can run on its own disk, such as DuckDB, which the README points to for local work, writes a throwaway profiles.yml (already gitignored) for the default profile, runs dbt deps, dbt parse, dbt seed --vars '{"load_source_data": true}' to load the CSVs in seeds/jaffle-data, dbt build, and dbt ls --resource-type exposure with --select +exposure:<name> to print each exposure's upstream graph. dbt docs generate confirms the exposures appear with their lineage. The profile and the DuckDB file never enter the commit.

Start it with one API call

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

{
  "agent": "claude",
  "input": "A Linear issue labeled agent lists our dashboards with their URLs, owners and the models or metrics each one reads, and says: \"Declare these as dbt exposures so lineage shows what breaks a dashboard.\" Before changing anything, read dbt_project.yml, packages.yml, the source and model YAML under models/, and confirm no exposures are declared yet. Add an exposures YAML file in the marts folder with one entry per dashboard: name, label, type, maturity, url, owner name and email, a description, and depends_on using ref() for models, metric() for metrics and source() only where a dashboard reads raw data. Check every dependency name against the existing YAML. Then prove it locally without the project's dbt Cloud jobs: install dbt with a local adapter, write a gitignored profiles.yml for the project's profile, run dbt deps, dbt parse, the seed command with the source-data variable, dbt build, and list each exposure's upstream selection; generate docs and confirm the exposures appear. Commit only the exposures file and open a pull request that links back to the issue and shows the upstream graph of each exposure.",
  "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 a single new file, models/marts/exposures.yml, and a description that lists each exposure with its type, owner and the output of dbt ls --select +exposure:<name>, so the reviewer sees the models, sources and metrics behind each dashboard without opening dbt. The throwaway profile and the local database file are not in the diff.

The transcript carries the proof: dbt deps, dbt parse, the seed run, dbt build with every model and test it ran, the dbt ls selections and dbt docs generate, including any parse error the agent hit and fixed, such as a ref to a model name that did not exist. The project's dbt Cloud CI runs on the pull request as it does for any branch, and exposures add no models for it to build.

Before merging, a reviewer checks that each url opens the dashboard it names, that each owner is a real person or team, that depends_on reflects what the dashboard queries rather than the whole mart layer, and that any dashboard reading the semantic layer depends on metric() entries rather than the tables underneath.

Run it on every Linear issue labelled agent

In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so each issue carries its own dashboard list and the prompt stays fixed. Changes made by an app integration never fire it, and the automation's max_runs_per_hour bounds how many runs a burst of labelling can start.

From your own server, the same job is one POST /o/{org}/sessions per issue, with the repository in resources and the issue's https://linear.app/<workspace>/issue/<ID> URL beside it so Rush reads the issue through your Linear connection. A webhook_url on the API key receives run.completed or run.failed for every run that key starts, with the session_url to read the pull request link from.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Exposure YAML is cheap to write and easy to get subtly wrong: a ref to a renamed model, a metric that lives in another file, a dependency on a staging view when the dashboard reads the mart. The check is a real dbt parse and dbt build, and in a Rush sandbox the agent gets a warehouse of its own, a local adapter on its own disk, seeded from the project's CSVs, so the parse and build run in full without a warehouse credential leaving your account.

A label in Linear becomes a reviewable pull request with its lineage printed in the description and every dbt command in the transcript. Several labelled issues, one per team's dashboards, can run at once, each in its own sandbox on its own branch, and each pull request links back to the issue that asked for it.

Frequently asked questions

Does this change any model or test?

No. Exposures are metadata about consumers of the graph. The diff is one YAML file, and dbt build runs the same models and tests as before; the exposures only appear in dbt ls, selectors and the docs lineage.

Our CI runs in dbt Cloud. How does the agent check its work?

It proves the change locally with a gitignored profiles.yml and a local adapter, running dbt deps, dbt parse, the seed, dbt build and dbt ls in the sandbox. The dbt Cloud jobs still run on the pull request as they do on every branch.

Can an exposure depend on a metric rather than a table?

Yes. depends_on takes metric('name') alongside ref() and source(), which fits a dashboard that reads the semantic layer, and the agent uses it where the issue says the dashboard queries metrics such as order_total or new_customer_orders.

What if the issue lists a dashboard whose models I have renamed?

dbt parse fails on a ref to a model that does not exist, and the agent fixes the name from the YAML it read or, if it cannot tell which model is meant, leaves that exposure out and says so in the pull request.

More dbt jobs

More jobs like this: Turn a Linear label into a PR

Keep reading