Skip to content

Commit 9402334

Browse files
jdjd
authored
docs(scopes): reorg monorepo in scopes (#9517)
This moves monorepo MQ docs into scopes, while keeping a high level monorepo page that explains how the MQ supports the different part of a monorepo (CI + MQ).
1 parent 661523a commit 9402334

File tree

10 files changed

+95
-164
lines changed

10 files changed

+95
-164
lines changed

‎src/content/docs/index.mdx‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import { BsRobot, BsRocket, BsPatchQuestion, BsCommand, BsBook, BsPlugin, BsStac
1313
import { BiRuler, BiBadgeCheck, BiCut, BiSolidCoinStack } from 'react-icons/bi';
1414
import { TbPackages, TbGitBranch, TbTopologyStarRing3 } from 'react-icons/tb';
1515
import { TiFlowParallel } from 'react-icons/ti';
16-
import { FaUserShield, FaRegLightbulb, FaGear, FaTrafficLight, FaRegCirclePause, FaBug, FaMoneyBill1, FaSnowflake, FaStairs } from 'react-icons/fa6';
16+
import { FaUserShield, FaRegLightbulb, FaGear, FaTrafficLight, FaRegCirclePause, FaBug, FaMoneyBill1, FaSnowflake, FaStairs, FaDiagramProject } 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';
@@ -76,6 +76,9 @@ import { SlRefresh, SlSpeedometer } from 'react-icons/sl';
7676
<Docset title="GitHub Actions" path="/monorepo-ci/github-actions" icon={SiGithubactions}>
7777
Wire scopes into gha-mergify-ci workflows.
7878
</Docset>
79+
<Docset title="Merge Queue integration" path="/merge-queue/monorepo" icon={BsBoxes}>
80+
Share scopes with batching strategies.
81+
</Docset>
7982
</DocsetGrid>
8083

8184
<h2 class="home-title">Merge Queue</h2>
@@ -106,12 +109,15 @@ import { SlRefresh, SlSpeedometer } from 'react-icons/sl';
106109
<Docset title="Batches" path="/merge-queue/batches" icon={TbPackages}>
107110
Increase velocity with batches.
108111
</Docset>
109-
<Docset title="Two‑Step CI" path="/merge-queue/two-step" icon={FaTrafficLight}>
110-
Fast + full validation strategy.
112+
<Docset title="Scopes" path="/merge-queue/scopes" icon={FaDiagramProject}>
113+
Group pull requests by impacted services.
111114
</Docset>
112115
<Docset title="Monorepo" path="/merge-queue/monorepo" icon={BsBoxes}>
113116
Optimization for large repositories.
114117
</Docset>
118+
<Docset title="Two‑Step CI" path="/merge-queue/two-step" icon={FaTrafficLight}>
119+
Fast + full validation strategy.
120+
</Docset>
115121
<Docset title="Deployment" path="/merge-queue/deploy" icon={AiOutlineDeploymentUnit}>
116122
Adopt safely in production.
117123
</Docset>

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

Lines changed: 40 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,17 @@ title: Monorepo
33
description: Optimize merge queue batching for monorepos with scopes.
44
---
55

6-
In monorepo environments, not every pull request affects the entire codebase. Running all tests for
7-
every change wastes time and CI resources. Mergify's **scopes** feature allows you to intelligently
8-
batch pull requests based on which parts of your codebase they modify, dramatically improving merge
9-
queue efficiency.
10-
11-
For a deep dive into how scopes influence batching, see [Merge Queue Scopes](/merge-queue/scopes).
12-
13-
## Understanding Scopes
14-
15-
Scopes define discrete areas of your monorepo (like packages, services, or components). When a pull
16-
request is created, Mergify automatically determines which scopes are affected and uses this
17-
information to optimize batching.
18-
19-
Scopes can be determined in several ways depending on your project's needs:
20-
21-
- **File patterns**: Match file paths to identify affected scopes
22-
23-
- **Build system integration**: Support for tools like Bazel, Nx, Turborepo, and
24-
others that can provide scope information based on dependency graphs and build targets
25-
26-
This flexibility allows you to use the approach that best fits your monorepo's architecture and
27-
existing tooling.
28-
29-
Need scope-aware CI without the merge queue? Explore [Monorepo CI](/monorepo-ci) for workflows that
30-
target GitHub Actions today.
6+
In monorepo environments, not every pull request affects the entire codebase. Running the full
7+
validation matrix for each change quickly becomes wasteful, yet batching unrelated pull requests
8+
still makes the queue churn through work that doesn't matter. This page explains the pain points
9+
first and then shows how Mergify's monorepo capabilities keep batching efficient without
10+
sacrificing safety.
11+
12+
To solve this, Mergify introduces **scopes**—named regions of your repository that describe which
13+
services, packages, or domains a change touches. The rest of this guide shows how scopes pair with
14+
monorepo-aware tooling to batch compatible pull requests, keep unrelated work apart, and drive only
15+
the CI jobs that matter. For the full schema and advanced strategies, see
16+
[Merge Queue Scopes](/merge-queue/scopes).
3117

3218
## The Batching Challenge in Monorepos
3319

@@ -43,34 +29,40 @@ With scopes, Mergify can:
4329
- Keep independent changes in separate batches
4430
- Reduce unnecessary CI runs for unrelated parts of your codebase
4531

46-
## Configuration Approaches
32+
## Monorepo support at a glance
4733

48-
Choose the approach that best fits your monorepo setup:
34+
1. **Define scopes** in `.mergify.yml` using either file patterns or data emitted by your build
35+
system. Start with the [Scopes reference](/merge-queue/scopes).
4936

50-
### File Patterns
37+
2. **Collect scopes in CI** via [`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci) so
38+
every workflow knows which services a pull request touches.
5139

52-
Use simple glob patterns to map file paths to scopes. This approach is straightforward
53-
to set up and works well when your monorepo follows clear directory boundaries.
40+
3. **Reuse scopes in Merge Queue** to batch compatible pull requests, keep unrelated work apart,
41+
and gate expensive tests only when those scopes are present.
5442

55-
**Best for:**
56-
- Projects with well-defined directory structure
57-
- Monorepos without complex dependency graphs
58-
59-
[Learn more about file patterns →](/merge-queue/monorepo/file-patterns)
43+
Need scope-aware CI without the merge queue? Explore [Monorepo CI](/monorepo-ci) for workflows that
44+
target GitHub Actions today.
6045

61-
### Monorepo Build Tools
46+
### No monorepo tooling yet?
6247

63-
Leverage your existing build tool (Nx, Bazel, Turborepo, etc.) to detect affected projects
64-
based on your dependency graph. This approach provides more accurate scope detection by
65-
understanding your project's dependencies.
48+
Start with [Monorepo CI](/monorepo-ci) and its GitHub Actions guide. It ships a ready-made
49+
[`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci) workflow that detects scopes through file
50+
patterns, so you can adopt scope-aware batching without introducing Nx, Bazel, or Turborepo first. As
51+
your repository grows you can swap in more advanced tooling—your scopes stay the same.
6652

67-
**Best for:**
68-
- Projects already using monorepo build tools
69-
- Complex dependency relationships
70-
- Teams wanting transitive dependency detection
53+
## Understanding Scopes
7154

72-
Learn more about build tool integrations:
73-
- [Nx](/merge-queue/monorepo/nx)
74-
- [Bazel](/merge-queue/monorepo/bazel)
75-
- [Turborepo](/merge-queue/monorepo/turborepo)
76-
- [Other](/merge-queue/monorepo/others)
55+
Scopes define discrete areas of your monorepo (like packages, services, or components). When a pull
56+
request is created, Mergify automatically determines which scopes are affected and uses this
57+
information to optimize batching. The [Scopes reference](/merge-queue/scopes) covers the schema plus
58+
all tooling-specific guides, including file-pattern detection and integrations with Bazel, Nx, and
59+
Turborepo. If you already run Nx, Bazel, Turborepo, or another orchestrator, point it at
60+
`gha-mergify-ci` to upload those scope names—**scopes are the feature Merge Queue consumes**, regardless
61+
of how you compute them.
62+
63+
## Next steps
64+
65+
- [Scopes reference](/merge-queue/scopes): schema, file-pattern setup, and tooling guides (Nx, Bazel,
66+
Turborepo, custom uploaders).
67+
68+
- [Monorepo CI](/monorepo-ci): opinionated GitHub Actions workflows if you need turnkey automation.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,13 +86,13 @@ Scopes can be attached to pull requests automatically or manually:
8686
- **File pattern detection:** Define scopes directly in your configuration so Mergify infers them
8787
from changed paths once your CI uploads the results via
8888
[`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci) or an equivalent integration.
89-
See [file-pattern scopes](/merge-queue/monorepo/file-patterns) for a
89+
See [file-pattern scopes](/merge-queue/scopes/file-patterns) for a
9090
step-by-step setup.
9191

9292
- **Manual upload:** Use the [`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci)
9393
GitHub Action, the REST API, or the `mergify scopes-send` CLI to push scopes computed by your own
9494
tooling (Nx, Bazel, Turborepo, etc.). Examples are available in the build tool guides under
95-
[Monorepo integrations](/merge-queue/monorepo).
95+
[Scopes integrations](/merge-queue/scopes).
9696

9797
## Configuration schema
9898

src/content/docs/merge-queue/monorepo/bazel.mdx renamed to src/content/docs/merge-queue/scopes/bazel.mdx

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
---
2-
title: Monorepo with Bazeel
3-
description: Configure monorepo scopes using Bazel for dependency-aware batching.
2+
title: Scopes with Bazel
3+
description: Configure merge queue scopes using Bazel's dependency graph for precise batching.
44
---
55

6-
If you're using monorepo tools like Bazel build systems that have built-in
7-
dependency graph analysis, you can leverage their affected project detection instead of using file
8-
patterns. This approach is often more accurate because these tools understand your project's
6+
If you're using monorepo tools like Bazel that have built-in dependency graph analysis,
7+
you can leverage their affected project detection instead of using file patterns.
8+
This approach is often more accurate because these tools understand your project's
99
dependency relationships.
1010

1111
## Configuring Manual Scopes
1212

13-
To use manual scopes mechanism, configure Mergify to expect scopes from your CI system:
13+
To use the manual scopes mechanism, configure Mergify to expect scopes from your CI system:
1414

1515
```yaml
1616
scopes:
@@ -24,7 +24,7 @@ queue_rules:
2424
2525
## Detecting Scopes with Bazel
2626
27-
In your GitHub Actions workflow, use `bazel query` command to determine affected projects and
27+
In your GitHub Actions workflow, use `bazel query` to determine affected projects and
2828
upload them to Mergify:
2929

3030
```yaml
@@ -50,9 +50,9 @@ jobs:
5050
HEAD: ${{ steps.refs.outputs.head }}
5151
BASE: ${{ steps.refs.outputs.base }}
5252
run: |
53-
scopes=$(
53+
scopes=$( \
5454
bazel query --keep_going --noshow_progress --output=package \
55-
"buildfiles(set($(git diff --name-only --diff-filter=ACMR "$BASE" "$HEAD" | tr '\n' ' ')))" \
55+
"buildfiles(set($(git diff --name-only --diff-filter=ACMR \"$BASE\" \"$HEAD\" | tr '\n' ' ')))" \
5656
2>/dev/null | sort -u | paste -sd, -
5757
)
5858
echo "scopes=$scopes" >> "$GITHUB_OUTPUT"

src/content/docs/merge-queue/monorepo/file-patterns.mdx renamed to src/content/docs/merge-queue/scopes/file-patterns.mdx

Lines changed: 10 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Monorepo with File Patterns
3-
description: Configure monorepo scopes using file patterns to optimize merge queue batching.
2+
title: Scopes with File Patterns
3+
description: Configure merge queue scopes using file patterns to batch pull requests intelligently.
44
---
55

66
Mergify allows you to define scopes using file patterns to intelligently batch pull requests
@@ -48,86 +48,18 @@ they share a common scope.
4848

4949
## Setting Up CI with Scopes
5050

51-
To leverage scopes in your CI workflow, use the
52-
[gha-mergify-ci](https://github.com/Mergifyio/gha-mergify-ci) GitHub Action. This action detects
53-
which scopes are affected by a pull request and allows you to run only the relevant tests.
51+
To wire scopes into GitHub Actions, follow the
52+
[Monorepo CI GitHub Actions guide](/monorepo-ci/github-actions). It walks through:
5453

55-
## GitHub Actions Integration
54+
- Adding the [`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci)
55+
workflow step that reads your file-pattern scopes and exposes them as outputs.
5656

57-
Here's a complete example showing how to set up scope-aware CI:
57+
- Conditioning downstream jobs (frontend, backend, docs, etc.) on those scope outputs.
5858

59-
```yaml
60-
name: Continuous Integration
61-
on:
62-
pull_request:
63-
64-
jobs:
65-
scopes:
66-
runs-on: ubuntu-24.04
67-
outputs:
68-
python-api: ${{ fromJSON(steps.scopes.outputs.scopes).python-api }}
69-
frontend: ${{ fromJSON(steps.scopes.outputs.scopes).frontend }}
70-
docs: ${{ fromJSON(steps.scopes.outputs.scopes).docs }}
71-
merge-queue: ${{ fromJSON(steps.scopes.outputs.scopes).merge-queue }}
72-
steps:
73-
- uses: actions/checkout@v5
74-
- name: Get PR scopes
75-
id: scopes
76-
uses: Mergifyio/gha-mergify-ci@v9
77-
with:
78-
action: scopes
79-
token: ${{ secrets.MERGIFY_TOKEN }}
80-
81-
python-tests:
82-
if: ${{ needs.scopes.outputs.python-api == 'true' }}
83-
needs: scopes
84-
uses: ./.github/workflows/python-tests.yaml
85-
secrets: inherit
86-
87-
frontend-tests:
88-
if: ${{ needs.scopes.outputs.frontend == 'true' }}
89-
needs: scopes
90-
uses: ./.github/workflows/frontend-tests.yaml
91-
secrets: inherit
92-
93-
docs-tests:
94-
if: ${{ needs.scopes.outputs.docs == 'true' }}
95-
needs: scopes
96-
uses: ./.github/workflows/docs-tests.yaml
97-
secrets: inherit
98-
99-
integration-tests:
100-
if: ${{ needs.scopes.outputs.merge-queue == 'true' }}
101-
needs: scopes
102-
uses: ./.github/workflows/integration-tests.yaml
103-
secrets: inherit
104-
105-
ci-gate:
106-
if: ${{ !cancelled() }}
107-
needs:
108-
- python-tests
109-
- frontend-tests
110-
- docs-tests
111-
- integration-tests
112-
runs-on: ubuntu-latest
113-
steps:
114-
- name: Verify all jobs succeeded
115-
uses: Mergifyio/gha-mergify-ci@v9
116-
with:
117-
action: wait-jobs
118-
jobs: ${{ toJSON(needs) }}
119-
```
120-
121-
### Key Components
122-
123-
1. **Scopes Job**: Detects which scopes are affected and outputs boolean values
124-
125-
2. **Conditional Jobs**: Each test suite runs only if its scope is affected
126-
127-
3. **Integration Tests**: The special `merge-queue` scope is automatically set to `true` when
128-
running in the merge queue context
59+
- Waiting on the right set of jobs so required checks always report, even when work is skipped.
12960

130-
4. **CI Gate**: Aggregates all job results, handling skipped jobs correctly
61+
That guide already includes complete workflow samples, so you do not need to duplicate the config
62+
here—just reuse the same scopes you declared above.
13163

13264
## The Merge Queue Scope
13365

src/content/docs/merge-queue/monorepo/nx.mdx renamed to src/content/docs/merge-queue/scopes/nx.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
---
2-
title: Monorepo with Nx
3-
description: Configure monorepo scopes using Nx for dependency-aware batching.
2+
title: Scopes with Nx
3+
description: Configure merge queue scopes using Nx's dependency graph to drive batching.
44
---
55

6-
If you're using monorepo tools like Nx build system that have built-in dependency graph analysis,
6+
If you're using tools like the Nx build system that have built-in dependency graph analysis,
77
you can leverage their affected project detection instead of using file patterns.
8-
This approach is often more accurate because these tools understand your project's
8+
This approach is often more accurate because these tools understand your project's
99
dependency relationships.
1010

1111
## Configuring Manual Scopes
1212

13-
To use manual scopes mechanism, configure Mergify to expect scopes from your CI system:
13+
To use the manual scopes mechanism, configure Mergify to expect scopes from your CI system:
1414

1515
```yaml
1616
scopes:

src/content/docs/merge-queue/monorepo/others.mdx renamed to src/content/docs/merge-queue/scopes/others.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Monorepo with other Build Tools
3-
description: Configure monorepo scopes using other build tools for dependency-aware batching.
2+
title: Scopes with Other Build Tools
3+
description: Configure merge queue scopes using your preferred monorepo tooling.
44
---
55

66
If you're using monorepo tools that have built-in
@@ -10,7 +10,7 @@ dependency relationships.
1010

1111
## Configuring Manual Scopes
1212

13-
To use manual scopes mechanism, configure Mergify to expect scopes from your CI system:
13+
To use the manual scopes mechanism, configure Mergify to expect scopes from your CI system:
1414

1515
```yaml
1616
scopes:
@@ -24,7 +24,7 @@ queue_rules:
2424
2525
## Detecting Scopes with Your Build Tool
2626
27-
In your GitHub Actions workflow, use the monorepo tool to determine affected projects and
27+
In your GitHub Actions workflow, use your monorepo tool to determine affected projects and
2828
upload them to Mergify:
2929
3030
```yaml

src/content/docs/merge-queue/monorepo/turborepo.mdx renamed to src/content/docs/merge-queue/scopes/turborepo.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Monorepo with Turborepo
3-
description: Configure monorepo scopes using Turborepo for dependency-aware batching.
2+
title: Scopes with Turborepo
3+
description: Configure merge queue scopes using Turborepo's dependency graph awareness.
44
---
55

66
If you're using monorepo tools like Turborepo that have built-in
@@ -10,7 +10,7 @@ dependency relationships.
1010

1111
## Configuring Manual Scopes
1212

13-
To use manual scopes mechanism, configure Mergify to expect scopes from your CI system:
13+
To use the manual scopes mechanism, configure Mergify to expect scopes from your CI system:
1414

1515
```yaml
1616
scopes:

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@ Define your scopes first so every workflow speaks the same language:
107107

108108
Once those scopes exist, pick the workflow that matches your setup:
109109

110+
- [Scope configuration reference](/merge-queue/scopes)
110111
- [GitHub Actions setup](/monorepo-ci/github-actions)
111-
- [Monorepo integrations for merge queue](/merge-queue/monorepo)
112+
- [Merge queue monorepo overview](/merge-queue/monorepo)
112113

113114
Looking for a different CI provider? [Let us know](mailto:[email protected]); more platforms are on our roadmap.

0 commit comments

Comments
 (0)