Skip to content

Commit 593c561

Browse files
joostboonjoostboon
committed
docs: rewrite CI page with PR/MR review feature and setup guide
1 parent 2f98ef7 commit 593c561

2 files changed

Lines changed: 264 additions & 18 deletions

File tree

‎docs/cloud/features/ci.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: "PR / MR Data Quality Review"
3+
sidebarTitle: "PR / MR Review"
4+
---
5+
6+
Every time a developer changes a dbt model, there's a question no one can easily answer before merging: _is this safe to ship?_
7+
8+
Elementary's PR / MR Review answers that question automatically. When a pull request touches your dbt models, a comment appears with everything your team needs to review the data quality impact — test results, active incidents, and downstream blast radius — without leaving the PR.
9+
10+
![Elementary PR review comment posted on a GitHub pull request](/pics/cloud/pr_impact_example.png)
11+
12+
## What you get on every PR
13+
14+
- **Test history** — pass/fail counts for each changed model over the last 7 days
15+
- **Active incidents** — any open data quality issues affecting those models right now
16+
- **Downstream impact** — which models, pipelines, and dashboards depend on what you're changing
17+
- **Health summary** — a clear signal on whether it's safe to merge
18+
19+
The comment updates automatically on every new push, so the review stays current without cluttering the PR thread.
20+
21+
## How it works
22+
23+
The review is powered by [Claude](https://www.anthropic.com) connected to the [Elementary MCP server](/cloud/mcp/intro). When a PR is opened:
24+
25+
1. A CI job detects which models changed using `git diff`
26+
2. Claude queries Elementary for live data quality context on those models
27+
3. A formatted summary is posted as a comment on the PR or MR
28+
29+
No custom scripts, no webhook setup, no infrastructure to manage.
30+
31+
## Setup
32+
33+
### Prerequisites
34+
35+
- An Elementary Cloud account with the [MCP server enabled](/cloud/mcp/setup-guide)
36+
- An [Anthropic API key](https://console.anthropic.com)
37+
38+
### GitHub Actions
39+
40+
**Step 1 — Add the workflow file**
41+
42+
Create `.github/workflows/elementary-review.yml` in your dbt repository:
43+
44+
```yaml
45+
name: Elementary Data Quality Review
46+
47+
on:
48+
pull_request:
49+
paths:
50+
- "models/**/*.sql"
51+
- "models/**/*.yml"
52+
- "dbt_project.yml"
53+
54+
jobs:
55+
elementary-review:
56+
runs-on: ubuntu-latest
57+
permissions:
58+
pull-requests: write
59+
steps:
60+
- uses: actions/checkout@v4
61+
with:
62+
fetch-depth: 0
63+
64+
- uses: elementary-data/elementary-ci@v1
65+
with:
66+
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
67+
elementary-api-key: ${{ secrets.ELEMENTARY_API_KEY }}
68+
```
69+
70+
**Step 2 — Add two repository secrets**
71+
72+
Go to **Settings > Secrets and variables > Actions** and add:
73+
74+
| Secret | Description |
75+
|---|---|
76+
| `ANTHROPIC_API_KEY` | Your Anthropic API key |
77+
| `ELEMENTARY_API_KEY` | Your Elementary Cloud API key |
78+
79+
That's it. Open a PR that touches a model file and the review comment appears automatically.
80+
81+
<Accordion title="Optional: customize the action">
82+
83+
| Input | Default | Description |
84+
|---|---|---|
85+
| `models-path` | `models/` | Path to your dbt models directory |
86+
| `diff-filter` | `ACM` | File changes to include: A=Added, C=Copied, M=Modified |
87+
| `claude-model` | `claude-haiku-4-5-20251001` | Claude model to use. Switch to `claude-sonnet-4-6` for deeper analysis |
88+
| `base-ref` | PR base branch | Branch to diff against |
89+
90+
```yaml
91+
- uses: elementary-data/elementary-ci@v1
92+
with:
93+
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
94+
elementary-api-key: ${{ secrets.ELEMENTARY_API_KEY }}
95+
models-path: "dbt/models/"
96+
claude-model: "claude-sonnet-4-6"
97+
```
98+
</Accordion>
99+
100+
### GitLab CI
101+
102+
**Step 1 — Add the include to your `.gitlab-ci.yml`**
103+
104+
```yaml
105+
include:
106+
- remote: 'https://raw.githubusercontent.com/elementary-data/elementary-ci/v1/templates/mr-review.yml'
107+
```
108+
109+
**Step 2 — Add three CI/CD variables**
110+
111+
Go to **Settings > CI/CD > Variables** and add:
112+
113+
| Variable | Masked | Description |
114+
|---|---|---|
115+
| `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key |
116+
| `ELEMENTARY_API_KEY` | Yes | Your Elementary Cloud API key |
117+
| `GITLAB_API_TOKEN` | Yes | A project or group token with `api` scope |
118+
119+
Open an MR that touches a model file and the review comment appears automatically.
120+
121+
## Troubleshooting
122+
123+
**No comment appears after the job runs**
124+
125+
For GitHub, make sure `pull-requests: write` is set under `permissions` in the workflow. GitHub Actions requires this to post PR comments.
126+
127+
**`git diff` returns no changed models**
128+
129+
Make sure `fetch-depth: 0` is set on the checkout step. Without full git history the runner cannot compare branches.
130+
131+
**The comment says the MCP server is unreachable**
132+
133+
Verify `ELEMENTARY_API_KEY` is correctly set and the MCP server is enabled for your account. See the [MCP setup guide](/cloud/mcp/setup-guide).
134+
135+
<Warning>
136+
If a model has never been synced through Elementary, the comment will note that no history is available yet. Results appear automatically after the next Elementary sync.
137+
</Warning>

‎docs/features/ci.mdx‎

Lines changed: 127 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,137 @@
11
---
2-
title: "Elementary CI"
3-
sidebarTitle: "Elementary CI"
2+
title: "PR / MR Data Quality Review"
3+
sidebarTitle: "PR / MR Review"
44
---
55

6-
<Snippet file="cloud/cloud-feature-tag.mdx" />
6+
Every time a developer changes a dbt model, there's a question no one can easily answer before merging: _is this safe to ship?_
77

8-
### Closed beta - Elementary Pull request impact analysis!
8+
Elementary's PR / MR Review answers that question automatically. When a pull request touches your dbt models, a comment appears with everything your team needs to review the data quality impact — test results, active incidents, and downstream blast radius — without leaving the PR.
99

10-
When making changes to your data project, it can sometimes be hard to fully understand the impact of your changes and be certain that there are no unintended consequences.
10+
![Elementary PR review comment posted on a GitHub pull request](/pics/cloud/pr_impact_example.png)
1111

12-
Our impact analysis will run on every pull request in your dbt project, so that you can see the downstream impact of your changes.
13-
You'll also be able to see if any of your dbt tests are failing or your models aren't being built successfully.
12+
## What you get on every PR
1413

15-
<img src="/pics/cloud/pr_impact_example.png" />
14+
- **Test history** — pass/fail counts for each changed model over the last 7 days
15+
- **Active incidents** — any open data quality issues affecting those models right now
16+
- **Downstream impact** — which models, pipelines, and dashboards depend on what you're changing
17+
- **Health summary** — a clear signal on whether it's safe to merge
1618

17-
Elementary CI automations help you make changes with confidence by providing a comprehensive view before merging your pull request.
19+
The comment updates automatically on every new push, so the review stays current without cluttering the PR thread.
1820

19-
## Want to join the beta?
21+
## How it works
2022

21-
<Card
22-
title="Schedule a call"
23-
href="https://cal.com/maayansa/elementary-intro-docs"
24-
></Card>
25-
<Card
26-
title="Reach out to us on Slack"
27-
href="https://elementary-data.com/community"
28-
></Card>
23+
The review is powered by [Claude](https://www.anthropic.com) connected to the [Elementary MCP server](/cloud/mcp/intro). When a PR is opened:
24+
25+
1. A CI job detects which models changed using `git diff`
26+
2. Claude queries Elementary for live data quality context on those models
27+
3. A formatted summary is posted as a comment on the PR or MR
28+
29+
No custom scripts, no webhook setup, no infrastructure to manage.
30+
31+
## Setup
32+
33+
### Prerequisites
34+
35+
- An Elementary Cloud account with the [MCP server enabled](/cloud/mcp/setup-guide)
36+
- An [Anthropic API key](https://console.anthropic.com)
37+
38+
### GitHub Actions
39+
40+
**Step 1 — Add the workflow file**
41+
42+
Create `.github/workflows/elementary-review.yml` in your dbt repository:
43+
44+
```yaml
45+
name: Elementary Data Quality Review
46+
47+
on:
48+
pull_request:
49+
paths:
50+
- "models/**/*.sql"
51+
- "models/**/*.yml"
52+
- "dbt_project.yml"
53+
54+
jobs:
55+
elementary-review:
56+
runs-on: ubuntu-latest
57+
permissions:
58+
pull-requests: write
59+
steps:
60+
- uses: actions/checkout@v4
61+
with:
62+
fetch-depth: 0
63+
64+
- uses: elementary-data/elementary-ci@v1
65+
with:
66+
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
67+
elementary-api-key: ${{ secrets.ELEMENTARY_API_KEY }}
68+
```
69+
70+
**Step 2 — Add two repository secrets**
71+
72+
Go to **Settings > Secrets and variables > Actions** and add:
73+
74+
| Secret | Description |
75+
|---|---|
76+
| `ANTHROPIC_API_KEY` | Your Anthropic API key |
77+
| `ELEMENTARY_API_KEY` | Your Elementary Cloud API key |
78+
79+
That's it. Open a PR that touches a model file and the review comment appears automatically.
80+
81+
<Accordion title="Optional: customize the action">
82+
83+
| Input | Default | Description |
84+
|---|---|---|
85+
| `models-path` | `models/` | Path to your dbt models directory |
86+
| `diff-filter` | `ACM` | File changes to include: A=Added, C=Copied, M=Modified |
87+
| `claude-model` | `claude-haiku-4-5-20251001` | Claude model to use. Switch to `claude-sonnet-4-6` for deeper analysis |
88+
| `base-ref` | PR base branch | Branch to diff against |
89+
90+
```yaml
91+
- uses: elementary-data/elementary-ci@v1
92+
with:
93+
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
94+
elementary-api-key: ${{ secrets.ELEMENTARY_API_KEY }}
95+
models-path: "dbt/models/"
96+
claude-model: "claude-sonnet-4-6"
97+
```
98+
</Accordion>
99+
100+
### GitLab CI
101+
102+
**Step 1 — Add the include to your `.gitlab-ci.yml`**
103+
104+
```yaml
105+
include:
106+
- remote: 'https://raw.githubusercontent.com/elementary-data/elementary-ci/v1/templates/mr-review.yml'
107+
```
108+
109+
**Step 2 — Add three CI/CD variables**
110+
111+
Go to **Settings > CI/CD > Variables** and add:
112+
113+
| Variable | Masked | Description |
114+
|---|---|---|
115+
| `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key |
116+
| `ELEMENTARY_API_KEY` | Yes | Your Elementary Cloud API key |
117+
| `GITLAB_API_TOKEN` | Yes | A project or group token with `api` scope |
118+
119+
Open an MR that touches a model file and the review comment appears automatically.
120+
121+
## Troubleshooting
122+
123+
**No comment appears after the job runs**
124+
125+
For GitHub, make sure `pull-requests: write` is set under `permissions` in the workflow. GitHub Actions requires this to post PR comments.
126+
127+
**`git diff` returns no changed models**
128+
129+
Make sure `fetch-depth: 0` is set on the checkout step. Without full git history the runner cannot compare branches.
130+
131+
**The comment says the MCP server is unreachable**
132+
133+
Verify `ELEMENTARY_API_KEY` is correctly set and the MCP server is enabled for your account. See the [MCP setup guide](/cloud/mcp/setup-guide).
134+
135+
<Warning>
136+
If a model has never been synced through Elementary, the comment will note that no history is available yet. Results appear automatically after the next Elementary sync.
137+
</Warning>

0 commit comments

Comments
 (0)