Monorepo

In monorepo environments, not every pull request affects the entire codebase. Running the full validation matrix for each change quickly becomes wasteful, yet batching unrelated pull requests still makes the queue churn through work that doesn’t matter. This page explains the pain points first and then shows how Mergify’s monorepo capabilities keep batching efficient without sacrificing safety.

To solve this, Mergify introduces scopes—named regions of your repository that describe which services, packages, or domains a change touches. The rest of this guide shows how scopes pair with monorepo-aware tooling to batch compatible pull requests, keep unrelated work apart, and drive only the CI jobs that matter. For the full schema and advanced strategies, see Merge Queue Scopes.

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

• A Python service change and a JavaScript frontend change might be batched together
• Both sets of tests run even though they’re completely independent
• If one fails, both PRs are affected by the batch split process

With scopes, Mergify can:

• Batch together PRs that affect the same scopes (e.g., multiple Python changes)
• Keep independent changes in separate batches
• Reduce unnecessary CI runs for unrelated parts of your codebase

1. Define scopes in .mergify.yml using either file patterns or data emitted by your build system. Start with the Scopes reference.

2. Batch by scope in Merge Queue to group compatible pull requests and keep unrelated work apart. With file patterns, Mergify evaluates them itself, so the queue batches by scope with no extra setup.

3. Optionally, collect scopes in CI via gha-mergify-ci when you compute scopes with a build system (Nx, Bazel, Turborepo) or want to gate expensive tests on the scopes a pull request touches.

Need scope-aware CI without the merge queue? Explore Monorepo CI for workflows that target GitHub Actions today.

Just declare file-pattern scopes in .mergify.yml. Mergify evaluates them and the merge queue batches by scope with no workflow to add, so you get scope-aware batching without introducing Nx, Bazel, or Turborepo first. When you also want scope-aware CI, the Monorepo CI GitHub Actions guide ships a ready-made gha-mergify-ci workflow. As your repository grows you can swap in more advanced tooling, and your scopes stay the same.

Scopes define discrete areas of your monorepo (like packages, services, or components). When a pull request is created, Mergify automatically determines which scopes are affected and uses this information to optimize batching. The Scopes reference covers the schema plus all tooling-specific guides, including file-pattern detection and integrations with Bazel, Nx, and Turborepo. If you already run Nx, Bazel, Turborepo, or another orchestrator, point it at gha-mergify-ci to upload those scope names—scopes are the feature Merge Queue consumes, regardless of how you compute them.

• Scopes reference: schema, file-pattern setup, and tooling guides (Nx, Bazel, Turborepo, custom uploaders).

• Parallel Scopes: once scopes are configured, enable parallel scopes to test and merge pull requests that touch different scopes simultaneously — significantly reducing merge times in monorepos.

• Monorepo CI: opinionated GitHub Actions workflows if you need turnkey automation.