Skip to content

ci.mdx

Latest commit

 

History

History
156 lines (106 loc) · 6.42 KB

ci.mdx

File metadata and controls

156 lines (106 loc) · 6.42 KB
title GitHub & GitLab Data Quality Code Review
sidebarTitle Code Review

Every time a developer changes a dbt model, there's a question no one can easily answer before merging: is this safe to ship?

Your dbt tests tell you if the code compiles. They don't tell you if the model you just refactored has been failing tests for the past week, whether it feeds a dashboard your CEO looks at every morning, or whether there's already an open incident on it that your data team is investigating.

Elementary's PR / MR Review answers all of that automatically. The moment a pull request touches your dbt models, a structured comment appears with everything your team needs to make a confident merge decision — without leaving the PR.

Elementary PR review comment

Why it matters

Data quality issues are exponentially cheaper to catch before merge than after. But today, most teams have no visibility into data health at review time — reviewers check the SQL, not the data. By the time a broken model hits production, it's already in dashboards, downstream models, and stakeholder reports.

Elementary closes that gap by bringing live data quality context directly into the code review workflow.

What you get on every PR

  • Test history — pass/fail counts for each changed model over the last 7 days, so reviewers know if they're touching something that's already fragile
  • Active incidents — any open data quality issues on those models right now, before the change lands on top of them
  • Downstream blast radius — exactly which models, pipelines, and dashboards depend on what's changing, two levels deep
  • Health summary — a plain-language signal on whether it's safe to merge, powered by Claude

The comment updates automatically on every new push, so the review always reflects the latest state. No noise, no duplicate comments.

How it works

The review is powered by Claude connected to the Elementary MCP server. When a PR is opened or updated:

  1. A CI job detects which models changed using git diff
  2. Claude queries Elementary for live data quality context on those exact models
  3. A structured Markdown summary is posted as a comment on the PR or MR

No custom scripts. No webhook setup. No infrastructure to manage. Two secrets and one file.

Setup

Prerequisites

GitHub Actions

Step 1 — Add the workflow file

Create .github/workflows/elementary-review.yml in your dbt repository:

name: Elementary Data Quality Review

on:
  pull_request:
    paths:
      - "models/**/*.sql"
      - "models/**/*.yml"
      - "dbt_project.yml"

jobs:
  elementary-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: elementary-data/elementary-ci@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          elementary-api-key: ${{ secrets.ELEMENTARY_API_KEY }}

Step 2 — Add two repository secrets

Go to Settings > Secrets and variables > Actions and add:

Secret Description
ANTHROPIC_API_KEY Your Anthropic API key
ELEMENTARY_API_KEY Your Elementary Cloud API key

That's it. The review only runs on PRs that touch files matching the path filter — other PRs are ignored entirely.

This works for pull requests opened from branches within the same repository. GitHub does not pass repository secrets to `pull_request` workflows triggered by forks or Dependabot.
Input Default Description
models-path models/ Path to your dbt models directory
diff-filter ACMR File changes to include: A=Added, C=Copied, M=Modified, R=Renamed
claude-model claude-haiku-4-5-latest Claude model to use. Switch to claude-sonnet-4-latest for deeper analysis on complex changes
base-ref PR base branch Branch to diff against
mcp-config-path (auto-generated) Path to a custom MCP config file. Only needed for self-hosted Elementary setups 
- uses: elementary-data/elementary-ci@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    elementary-api-key: ${{ secrets.ELEMENTARY_API_KEY }}
    models-path: "dbt/models/"
    claude-model: "claude-sonnet-4-latest"

GitLab CI

Step 1 — Add the include to your .gitlab-ci.yml

include:
  - remote: 'https://raw.githubusercontent.com/elementary-data/elementary-ci/v1/templates/mr-review.yml'

Step 2 — Add two CI/CD variables

Go to Settings > CI/CD > Variables and add:

Variable Masked Description
ANTHROPIC_API_KEY Yes Your Anthropic API key
ELEMENTARY_API_KEY Yes Your Elementary Cloud API key

GitLab's built-in CI_JOB_TOKEN is used to post the MR comment — no extra token setup needed.

The review only runs on MRs that touch files matching the changes filter — other MRs are ignored entirely.

Troubleshooting

No comment appears after the job runs

Make sure both contents: read and pull-requests: write are set under permissions in the workflow. An explicit permissions block sets any unlisted scope to none — omitting contents: read causes the checkout step to fail before Elementary runs.

git diff returns no changed models

Make sure fetch-depth: 0 is set on the checkout step. Without full git history the runner cannot compare branches and the diff will be empty.

The comment says the MCP server is unreachable

Verify ELEMENTARY_API_KEY is correctly set and the MCP server is enabled for your account. See the MCP setup guide.

If a model has never been synced through Elementary, the comment will note that no history is available yet. Results populate automatically after the next Elementary sync.

Using a different AI provider?

The review currently uses Claude via the Anthropic API. If your team uses a different provider and you'd like to see it supported, we'd love to hear from you — reach out at support@elementary-data.com or on the Community Slack.