Skip to content

Commit 1250aed

Browse files
jdjd
authored
docs(monorepo): add Monorepo CI (#9490)
This adds a dedicated documentation section for monorepo CI management using gha-mergify-ci.
1 parent 400d1aa commit 1250aed

File tree

9 files changed

+319
-5
lines changed

9 files changed

+319
-5
lines changed

‎src/components/Footer/footer.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ export const productCategory: Category = {
3838
text: 'Merge Queue',
3939
href: 'https://mergify.com/product/merge-queue',
4040
},
41+
{
42+
text: 'Monorepo CI',
43+
href: 'https://mergify.com/product/monorepo-ci',
44+
},
4145
{
4246
text: 'Merge Protections',
4347
href: 'https://mergify.com/product/merge-protections',

‎src/content/docs/index.mdx‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@ import { MdOutlineLightbulb, MdMonitorHeart } from 'react-icons/md';
1111
import { GoGitMerge, GoCodeReview } from 'react-icons/go';
1212
import { BsRobot, BsRocket, BsPatchQuestion, BsCommand, BsBook, BsPlugin, BsStack, BsLightbulb, BsBoxes } from 'react-icons/bs';
1313
import { BiRuler, BiBadgeCheck, BiCut, BiSolidCoinStack } from 'react-icons/bi';
14-
import { TbPackages, TbGitBranch } from 'react-icons/tb';
14+
import { TbPackages, TbGitBranch, TbTopologyStarRing3 } from 'react-icons/tb';
1515
import { TiFlowParallel } from 'react-icons/ti';
1616
import { FaUserShield, FaRegLightbulb, FaGear, FaTrafficLight, FaRegCirclePause, FaBug, FaMoneyBill1, FaSnowflake, FaStairs } from 'react-icons/fa6';
1717
import { FaShieldAlt } from 'react-icons/fa';
1818
import { AiOutlineDeploymentUnit, AiOutlineFile, AiOutlineApi } from 'react-icons/ai';
1919
import { LiaShareAltSolid } from 'react-icons/lia';
2020
import { FiType } from 'react-icons/fi';
2121
import MergeQueueIcon from '../../components/MergeQueueIcon.astro';
22-
import { SiSlack, SiGithub, SiX, SiYoutube, SiLinkedin } from 'react-icons/si';
22+
import { SiSlack, SiGithub, SiX, SiYoutube, SiLinkedin, SiGithubactions } from 'react-icons/si';
2323
import { IoIosRemoveCircleOutline } from 'react-icons/io';
2424
import { GrTest } from 'react-icons/gr';
2525
import { SlRefresh, SlSpeedometer } from 'react-icons/sl';
@@ -37,6 +37,7 @@ import { SlRefresh, SlSpeedometer } from 'react-icons/sl';
3737
<div class="quick-links">
3838
<a href="/ci-insights" class="ql">CI Insights</a>
3939
<a href="/merge-queue" class="ql">Merge Queue</a>
40+
<a href="/monorepo-ci" class="ql">Monorepo CI</a>
4041
<a href="/merge-protections" class="ql">Merge Protections</a>
4142
<a href="/workflow" class="ql">Workflow Automation</a>
4243
</div>
@@ -65,6 +66,18 @@ import { SlRefresh, SlSpeedometer } from 'react-icons/sl';
6566
</Docset>
6667
</DocsetGrid>
6768

69+
<h2 class="home-title">Monorepo CI</h2>
70+
Scope-aware CI workflows that only run the jobs that matter.
71+
72+
<DocsetGrid>
73+
<Docset title="Overview" path="/monorepo-ci" icon={TbTopologyStarRing3}>
74+
Define scopes once and reuse them across CI.
75+
</Docset>
76+
<Docset title="GitHub Actions" path="/monorepo-ci/github-actions" icon={SiGithubactions}>
77+
Wire scopes into gha-mergify-ci workflows.
78+
</Docset>
79+
</DocsetGrid>
80+
6881
<h2 class="home-title">Merge Queue</h2>
6982
Deterministic, parallel, and resource‑aware merging.
7083

‎src/content/docs/integrations/gha.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,3 +79,6 @@ You can:
7979

8080
- React to failures in GitHub Actions runs by adding comments, labels, or even
8181
requesting reviews.
82+
83+
- Optimize monorepo pipelines by running only the jobs touched by a pull
84+
request; see [Monorepo CI with GitHub Actions](/monorepo-ci/github-actions).

‎src/content/docs/merge-queue/monorepo.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ Scopes can be determined in several ways depending on your project's needs:
2626
This flexibility allows you to use the approach that best fits your monorepo's architecture and
2727
existing tooling.
2828

29+
Need scope-aware CI without the merge queue? Explore [Monorepo CI](/monorepo-ci) for workflows that
30+
target GitHub Actions today.
31+
2932
## The Batching Challenge in Monorepos
3033

3134
Without scopes, Mergify batches pull requests together regardless of what they change. This means:

‎src/content/docs/merge-queue/scopes.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ Mergify scopes describe the areas of your codebase that a pull request touches.
77
to pull requests, the merge queue can build smarter batches, reuse the same CI work, and avoid
88
mixing unrelated changes.
99

10+
Looking to use scopes outside of the merge queue? Check out [Monorepo CI](/monorepo-ci) for
11+
scope-driven CI workflows.
12+
1013
## Scope-aware batching at a glance
1114

1215
When several pull requests are eligible for the next batch, Mergify compares their scopes and

‎src/content/docs/monorepo-ci.mdx‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Monorepo CI
3+
description: Run the right tests for the right pull requests by combining scopes with your CI system.
4+
---
5+
6+
Monorepos supercharge collaboration, but they also make continuous integration
7+
expensive. Every change potentially touches hundreds of packages or services,
8+
and running the full test matrix for all of them at every pull request update
9+
quickly becomes unsustainable.
10+
11+
Mergify Monorepo CI brings precision testing to your existing CI pipelines by
12+
tagging each pull request with **scopes**. Scopes are named slices of your
13+
repository that describe a service, package, or set of files (see
14+
[Merge Queue Scopes](/merge-queue/scopes) for the full specification). A scope acts as
15+
the contract between your codebase and your CI: if a pull request touches files
16+
that belong to the `frontend` scope, every workflow that cares about that scope
17+
knows it has work to do.
18+
19+
With scopes in place you can:
20+
21+
- Detect which projects or services are really impacted by a change.
22+
- Run only the CI jobs that matter for those scopes.
23+
- Reuse those scopes later in the merge queue to build smarter batches.
24+
25+
Today, GitHub Actions is the first CI platform with native support through our
26+
[`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci) action.
27+
28+
## How it works
29+
30+
```dot class="graph"
31+
strict digraph {
32+
fontname="sans-serif";
33+
rankdir="LR";
34+
nodesep=0.9;
35+
ranksep=1.1;
36+
splines=polyline;
37+
38+
node [shape=box, style="rounded,filled", fontname="sans-serif", margin="0.35,0.2", color="#165B33", fillcolor="#347D39", fontcolor="white"];
39+
edge [fontname="sans-serif", color="#374151", penwidth=1.2, arrowhead=normal];
40+
41+
subgraph cluster_repo {
42+
label="Repository";
43+
style="rounded";
44+
color="#1CB893";
45+
fontcolor="#063C2C";
46+
47+
PR [label="Pull request\nchanges"];
48+
ScopesConfig [fillcolor="#1CB893", fontcolor="#063C2C", color="#0B7A5C", margin="0.4,0.2", label="Scopes config\n(.mergify.yml)"];
49+
}
50+
51+
Detect [fillcolor="#2563EB", color="#1E40AF", label="gha-mergify-ci\n(scopes)"];
52+
53+
subgraph cluster_ci {
54+
label="GitHub Actions jobs";
55+
style="rounded";
56+
color="#1CB893";
57+
fontcolor="#063C2C";
58+
59+
Frontend [label="Frontend tests"];
60+
API [fillcolor="#6B7280", color="#4B5563", label="API tests\n(skipped)"];
61+
Docs [fillcolor="#347D39", color="#165B33", label="Docs checks"];
62+
}
63+
64+
Queue [fillcolor="#111827", color="#0B1120", label="Merge Queue\n(optional reuse)"];
65+
66+
PR -> Detect;
67+
ScopesConfig -> Detect;
68+
Detect -> Frontend [label="scope: frontend"];
69+
Detect -> Docs [label="scope: docs"];
70+
Detect -> Queue [style=dashed, color="#9CA3AF", fontcolor="#9CA3AF"];
71+
}
72+
```
73+
74+
1. **Define scopes** in your `.mergify.yml` file by mapping the areas of your repository (via file
75+
patterns) to scope names that matter for your CI.
76+
77+
2. **Collect scopes in CI.** A helper (currently
78+
[`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci)) inspects the
79+
pull request diff and dispatches only the jobs whose scopes are touched.
80+
81+
3. **Drive your jobs conditionally.** Use the reported scopes to decide which
82+
workflows, test suites, or deployment steps should run for the current pull
83+
request.
84+
85+
4. **(Optional) Share scopes with Merge Queue.** The very same scopes help the merge queue build
86+
batches that group related pull requests, reuse your CI runs, and unlock advanced strategies like
87+
[batch merging](/merge-queue/batches) or [two-step CI](/merge-queue/two-step).
88+
89+
## What you can do with Monorepo CI
90+
91+
- Gate language-specific test suites with fine-grained scope checks.
92+
- Trigger targeted build pipelines for individual services or packages.
93+
- Run nightly or specialized workflows only when relevant scopes change.
94+
95+
## Get started
96+
97+
Define your scopes first so every workflow speaks the same language:
98+
99+
1. List the services, packages, or domains that deserve their own scope.
100+
101+
2. Map each scope to file patterns inside the
102+
[`scopes`](/merge-queue/scopes#configuration) block of your `.mergify.yml`
103+
file.
104+
105+
3. Commit the configuration and open a pull request to verify that the reported
106+
scopes match your expectations.
107+
108+
Once those scopes exist, pick the workflow that matches your setup:
109+
110+
- [GitHub Actions setup](/monorepo-ci/github-actions)
111+
- [Monorepo integrations for merge queue](/merge-queue/monorepo)
112+
113+
Looking for a different CI provider? [Let us know](mailto:[email protected]); more platforms are on our roadmap.

‎src/content/docs/monorepo-ci/github-actions.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Monorepo CI with GitHub Actions
3+
description: Use `gha-mergify-ci` to run only the workflows impacted by a pull request.
4+
---
5+
6+
import { Image } from "astro:assets"
7+
import ghaSummaryScreenshot from "../../images/monorepo-ci/github-actions/summary.png"
8+
9+
Mergify's GitHub Actions integration makes scopes actionable in your CI. This
10+
guide shows how to wire scopes into your workflows so that each pull request
11+
runs only the jobs it truly needs.
12+
13+
## Prerequisites
14+
15+
Before you start, declare scopes in your `.mergify.yml` so the action knows
16+
which areas of the repo map to each scope name:
17+
18+
```yaml
19+
scopes:
20+
source:
21+
files:
22+
frontend:
23+
includes:
24+
- apps/web/**/*
25+
api:
26+
includes:
27+
- services/api/**/*
28+
docs:
29+
includes:
30+
- docs/**/*
31+
```
32+
33+
## Workflow outline
34+
35+
A typical GitHub Actions pipeline with scopes consists of three parts:
36+
37+
1. **Detect scopes** using the
38+
[`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci) action.
39+
40+
2. **Reuse the scope outputs** to conditionally run jobs.
41+
42+
3. **Publish a final status** (for example with a `ci-gate` job) if you want one
43+
check that reflects all the jobs that ran.
44+
45+
```dot class="graph"
46+
strict digraph {
47+
fontname="sans-serif";
48+
rankdir="LR";
49+
nodesep=0.9;
50+
ranksep=1.1;
51+
splines=polyline;
52+
53+
node [shape=box, style="rounded,filled", fontname="sans-serif", margin="0.35,0.2", color="#165B33", fillcolor="#347D39", fontcolor="white"];
54+
edge [fontname="sans-serif", color="#374151", penwidth=1.2, arrowhead=normal];
55+
56+
PR [label="Pull request\nchanges"];
57+
Config [fillcolor="#1CB893", color="#0B7A5C", fontcolor="#063C2C", label="Scopes config\n(.mergify.yml)"];
58+
Detect [fillcolor="#2563EB", color="#1E40AF", label="detect-scopes job\n(gha-mergify-ci)"];
59+
60+
Frontend [label="frontend-tests\n(run)"];
61+
API [fillcolor="#6B7280", color="#4B5563", label="api-tests\n(skipped)"];
62+
Docs [label="docs-tests\n(run)"];
63+
Gate [fillcolor="#111827", color="#0B1120", label="ci-gate\n(optional)"];
64+
65+
PR -> Detect;
66+
Config -> Detect;
67+
Detect -> Frontend [label="scope: frontend"];
68+
Detect -> Docs [label="scope: docs"];
69+
Detect -> API [style=dashed, color="#9CA3AF", fontcolor="#9CA3AF", label="scope: api (false)"];
70+
Frontend -> Gate;
71+
Docs -> Gate;
72+
}
73+
```
74+
75+
## Example workflow
76+
```yaml
77+
name: Monorepo CI
78+
on:
79+
pull_request:
80+
81+
jobs:
82+
detect-scopes:
83+
runs-on: ubuntu-24.04
84+
outputs:
85+
frontend: ${{ fromJSON(steps.scopes.outputs.scopes).frontend }}
86+
api: ${{ fromJSON(steps.scopes.outputs.scopes).api }}
87+
docs: ${{ fromJSON(steps.scopes.outputs.scopes).docs }}
88+
steps:
89+
- uses: actions/checkout@v5
90+
91+
- name: Detect scopes
92+
id: scopes
93+
uses: Mergifyio/gha-mergify-ci@v11
94+
with:
95+
action: scopes
96+
97+
frontend-tests:
98+
needs: detect-scopes
99+
if: ${{ needs.detect-scopes.outputs.frontend == 'true' }}
100+
uses: ./.github/workflows/frontend-tests.yaml
101+
secrets: inherit
102+
103+
api-tests:
104+
needs: detect-scopes
105+
if: ${{ needs.detect-scopes.outputs.api == 'true' }}
106+
uses: ./.github/workflows/api-tests.yaml
107+
secrets: inherit
108+
109+
docs-tests:
110+
needs: detect-scopes
111+
if: ${{ needs.detect-scopes.outputs.docs == 'true' }}
112+
uses: ./.github/workflows/docs-tests.yaml
113+
secrets: inherit
114+
115+
ci-gate:
116+
if: ${{ !cancelled() }}
117+
needs:
118+
- frontend-tests
119+
- api-tests
120+
- docs-tests
121+
runs-on: ubuntu-24.04
122+
steps:
123+
- name: Report status
124+
uses: Mergifyio/gha-mergify-ci@v11
125+
with:
126+
action: wait-jobs
127+
jobs: ${{ toJSON(needs) }}
128+
```
129+
130+
### How it works
131+
132+
- `detect-scopes` calls `gha-mergify-ci` with the `scopes` action, which
133+
inspects the pull request diff and returns a JSON map of scopes set to `true`
134+
or `false`.
135+
136+
- Each job checks the scope it cares about before running, dramatically reducing
137+
redundant builds.
138+
139+
- The final `ci-gate` job ensures that the aggregated status reflects the actual
140+
CI coverage, even if some jobs were skipped.
141+
142+
Mergify also publishes annotations that can be seen in your GitHub Actions jobs
143+
summary.
144+
145+
<Image src={ghaSummaryScreenshot} alt="GitHub Actions summary showing detected scopes and ci-gate result" />
146+
147+
## Protecting the branch with `ci-gate`
148+
149+
Once `ci-gate` publishes a single status, add it as a required check in your
150+
GitHub branch ruleset so that only pull requests with the relevant jobs executed
151+
can merge.
152+
153+
## Merge Queue integration
154+
155+
Ready to reuse the same scopes for batching? Head over to [Merge Queue
156+
Scopes](/merge-queue/scopes) to see how they power smarter batches.

‎src/content/images/monorepo-ci/github-actions/summary.png‎

160 KB
Loading

0 commit comments

Comments
 (0)