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. Collect scopes in CI via gha-mergify-ci so every workflow knows which services a pull request touches.

3. Reuse scopes in Merge Queue to batch compatible pull requests, keep unrelated work apart, and gate expensive tests only when those scopes are present.

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

Start with Monorepo CI and its GitHub Actions guide. It ships a ready-made gha-mergify-ci workflow that detects scopes through file patterns, so you can adopt scope-aware batching without introducing Nx, Bazel, or Turborepo first. As your repository grows you can swap in more advanced tooling—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).

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