---
title: Monorepo
description: Optimize merge queue batching for monorepos with scopes.
---

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.

:::tip
  Learn about merge queue strategies for monorepos at the
  [Merge Queue Academy](https://merge-queue.academy/use-cases/monorepos/).
:::

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](/merge-queue/scopes).

## The Batching Challenge in Monorepos

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

## Monorepo support at a glance

1. **Define scopes** in `.mergify.yml` using either file patterns or data emitted by your build
   system. Start with the [Scopes reference](/merge-queue/scopes).

2. **Collect scopes in CI** via [`gha-mergify-ci`](https://github.com/Mergifyio/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](/monorepo-ci) for workflows that
target GitHub Actions today.

### No monorepo tooling yet?

Start with [Monorepo CI](/monorepo-ci) and its GitHub Actions guide. It ships a ready-made
[`gha-mergify-ci`](https://github.com/Mergifyio/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.

## Understanding Scopes

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](/merge-queue/scopes) 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.

## Next steps

- [Scopes reference](/merge-queue/scopes): schema, file-pattern setup, and tooling guides (Nx, Bazel,
  Turborepo, custom uploaders).

- [Parallel Scopes](/merge-queue/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](/monorepo-ci): opinionated GitHub Actions workflows if you need turnkey automation.