---
title: Scopes
description: Declare the areas of your codebase once, so the merge queue batches by them and Job Selection skips the CI jobs a pull request does not need.
---

Scopes name the areas of your codebase that a pull request touches. You declare them once, in the
`scopes` section of `.mergify.yml`, and every Mergify feature that needs to know what a change
affects reads that declaration:

- The [merge queue](/merge-queue) batches pull requests that touch the same scopes, and
  [merges one right away](/merge-queue/direct-merge) when the base branch only moved in scopes it
  does not touch.

- [Job Selection](/ci-insights/job-selection) skips the CI jobs whose scopes a pull request does
  not touch.

Here's a quick walkthrough of how we use scopes on Mergify's own monorepo:

<Youtube video="GOqDmZl6EI0" title="How Mergify scopes work in a monorepo" />

## How the merge queue batches by scope

How scopes shape a batch depends on the [queue mode](/merge-queue/queue-modes):

- **Serial and isolated modes** prefer the closest match: pull requests whose scopes overlap are
  batched together first, and unrelated ones still share a batch when Mergify needs them to fill it.
  See [Batching in serial and isolated modes](#batching-in-serial-and-isolated-modes).

- **Parallel mode** batches together only pull requests carrying exactly the same scopes, and tests
  each batch on top of the work ahead of it in every scope it carries. See [Batching in parallel
  mode](#batching-in-parallel-mode).

### Batching in serial and isolated modes

When several pull requests are eligible for the next batch, Mergify compares each candidate's scopes
with the ones the batch already holds and prefers the closest match: the scopes the two have in
common, out of every scope either side names. Pull requests that overlap in scope are tested
together first, while an unrelated change waits for a later batch unless Mergify needs it to fill
the requested batch size.

```dot class="queue" title="Scope-aware batch selection in serial or isolated mode: the three pull requests that share frontend and api form the batch; the tooling change waits"
digraph {
  edge [arrowhead=none];

  subgraph cluster_preferred {
    class="batch";
    label="Preferred batch";
    PR1 [label="PR #101\nScopes: frontend, api", class="queued"];
    PR2 [label="PR #214\nScopes: frontend", class="queued"];
    PR3 [label="PR #305\nScopes: api, docs", class="queued"];
  }

  PR4 [label="PR #412\nScope: tooling", class="muted"];

  frontend [shape=oval, class="config"];
  api [shape=oval, class="config"];
  docs [shape=oval, class="config"];
  tooling [shape=oval, class="config"];

  PR1 -> frontend;
  PR1 -> api;
  PR2 -> frontend;
  PR3 -> api;
  PR3 -> docs;
  PR4 -> tooling;
}
```

In the example above, the queue selects the three pull requests that share the `frontend` and `api`
scopes first. The change that only touches the `tooling` scope is kept aside unless Mergify needs it
later to complete the batch. In parallel mode, the same four pull requests would form four batches,
since no two of them carry the same scopes.

[How Pull Requests Are Grouped Into a Batch](/merge-queue/batches#how-pull-requests-are-grouped-into-a-batch)
covers the full order of precedence, including how priority and stacks come before scopes.

### Batching in parallel mode

In [parallel mode](/merge-queue/queue-modes#parallel-mode), each scope is a lane, and scopes decide
both which pull requests share a batch and which batches wait on each other:

- **A batch holds one set of scopes.** Mergify batches together only pull requests carrying exactly
  the same scopes, in queue order, up to `batch_size`. A pull request with `api` and `frontend` is
  never batched with one that carries only `api`, nor with one that carries `api` and `docs`, and
  pull requests carrying no scope are batched only with each other. The exception is a
  [stack](/merge-queue/stacks#stack-aware-batching): its pull requests are batched as if they
  carried the scopes of the bottom pull request of the stack.

- **A batch waits on every scope it carries.** It is tested on top of the last batch ahead of it in
  each of its scopes, and merges only after them. Outside
  [barriers](#barrier-behavior-in-the-queue), a batch that shares no scope with the batches ahead
  of it is tested and merged on its own.

So a pull request with two scopes costs one batch and one CI run, not one per scope. That run tests
it on top of the work ahead in both scopes, and the batch holds it only with pull requests carrying
the same two scopes.

```dot class="queue" narrow="flow" title="Parallel mode with batch_size: 3. Batch 3 carries api and frontend, so it is tested once, on top of batches 1 and 2; PR #605 shares api but adds docs, so it gets batch 4, behind batch 3"
digraph {
  B1 [label="Batch 1\nPR #601 (api)", class="pending"];
  B2 [label="Batch 2\nPR #602 (frontend)", class="pending"];
  B3 [label="Batch 3\nPR #603, PR #604\n(api, frontend)", class="queued"];
  B4 [label="Batch 4\nPR #605 (api, docs)", class="queued"];

  B1 -> B3 [label="api"];
  B2 -> B3 [label="frontend"];
  B3 -> B4 [label="api"];
  { rank=same; B1; B2; }
}
```

PR #603 and PR #604 carry the same two scopes, so they share batch 3 and a single CI run, which
includes the changes of batches 1 and 2. Batch 3 merges once those two batches have merged. PR #605
shares `api` with batch 3 but also carries `docs`, so it is not added to batch 3: it gets a batch of
its own, tested on top of batch 3.

Since only pull requests with the same scopes share a batch, pull requests spread over many
different combinations of scopes form small batches, whatever `batch_size` allows.

[How parallel mode works](/merge-queue/queue-modes#how-parallel-mode-works) covers the rest of the
cycle: how many batches are tested at once, and what a failing batch holds back.

## Scope assignment lifecycle

Scopes can be attached to pull requests automatically, manually, or both at once — a configuration
that matches file patterns still reads what your tooling uploads for a pull request's head commit:

- **File pattern detection:** Define scopes directly in your configuration and Mergify evaluates
  them itself, matching each pull request's changed files against your patterns. No CI job or GitHub
  Action is required for the queue to batch by scope. On top of the file matches, a pull request
  also picks up any scopes reported for its head commit, so a build tool can add scopes the
  patterns miss. See [file-pattern scopes](/configuration/scopes/file-patterns) for a step-by-step
  setup.

- **Manual upload:** Use the [`gha-mergify-ci`](https://github.com/Mergifyio/gha-mergify-ci)
  GitHub Action, the
  [`mergifyio/mergify-ci`](https://github.com/Mergifyio/mergify-ci-buildkite-plugin) Buildkite
  plugin, the [REST API](/api/pull-requests), or the `mergify ci scopes-send` CLI to push scopes
  computed by your own tooling. There is a build tool guide for [Nx](/configuration/scopes/nx),
  [Bazel](/configuration/scopes/bazel), [Pants](/configuration/scopes/pants), and
  [Turborepo](/configuration/scopes/turborepo), plus one for
  [any other build tool](/configuration/scopes/others).

### Limits on an upload

An upload sent through the [REST API](/api/pull-requests) or the [Mergify CLI](/cli/usage) has to
stay within these limits:

- A scope name is at most 1024 characters.
- A scope name cannot contain a NUL byte or an unpaired UTF-16 surrogate.
- An upload carries at most 10,000 scopes.

An upload that breaks any of them is refused in full with a `422`, and nothing is stored: the pull
request keeps whatever was uploaded for it last, which is the stale result of an earlier run rather
than no result at all. If your detection tooling can emit a generated name (a path from a build
graph, for example), cap its length on your side, so an over-long name fails the job that produced
it instead of leaving the queue to batch on the previous run's scopes.

## Configuration schema

Declare scopes at the top level of your `.mergify.yml` file:

```yaml
scopes:
  source:
    files:
      frontend:
        include:
          - apps/web/**/*
      api:
        include:
          - services/api/**/*.py
      docs:
        include:
          - docs/**/*
  merge_queue_scope: merge-queue

queue_rules:
  - name: default
    batch_size: 3
```

### Top-level keys

- `scopes.source`: selects how scopes are provided.
  - `files`: map scope names to the file patterns that define them. Each entry accepts `include`
    and optional `exclude` lists of [glob patterns](/configuration/data-types#globs). A pull
    request also picks up any scopes, and the
    [`all_scopes`](#declaring-a-pull-request-impacts-every-scope) flag, reported for its head
    commit through the [REST API](/api/pull-requests), which `mergify ci scopes-send` calls when
    it knows that commit. The queue does not wait for them, and an upload addressed by pull
    request number is ignored.

  - `manual`: instructs Mergify to expect scopes that your CI uploads with the `gha-mergify-ci`
    GitHub Action, the `mergifyio/mergify-ci` Buildkite plugin, the Mergify CLI, or the REST API.
    These are the only scopes a pull request gets, and the queue waits for them.

  - `null`: disables scopes entirely.

- `scopes.merge_queue_scope`: optional name of the scope reported on a merge queue batch build, so
  that CI jobs can tell one from an ordinary pull request build (defaults to `merge-queue`). It is
  reported whether or not the queue opened a [draft pull
  request](/merge-queue/batches/draft-pull-requests) for the batch, and a pull request cannot carry it: the
  queue drops that name from the scopes a pull request reports for itself. See [The merge queue
  scope](/configuration/scopes/file-patterns#the-merge-queue-scope).

- `scopes.capacities`: optional map of scope name to the number of speculative checks that scope may
  run at the same time, used to limit per-scope concurrency in any mode. See [Limiting concurrency
  per scope](/merge-queue/queue-modes#limiting-concurrency-per-scope). A key holding `*`,
  `?`, `[`, or `{` is a glob over scope names, with the syntax of the [glob
  patterns](/configuration/data-types#globs) a `files` source uses; any other key names one scope
  exactly. An exact key may be any name the scopes API accepts, whatever the source: a Bazel
  package label like `//lib/core`, a scoped package name like `@acme/web`, or a name your file
  patterns declare. The source decides which scopes a pull request carries, not which of them you
  may cap. A `files` source reads the scopes reported for a pull request's head commit on top of
  its own file matches, so a name only a build tool ever reports is capped there too, as long as
  its report lands before the queue starts checking that pull request.

- `scopes.default_capacity`: optional capacity applied to every scope that no `capacities` key
  matches, so scope sets that change from one pull request to the next stay bounded without you
  listing each one. Like `capacities`, it applies in any mode. See [Capping scopes you did not
  list](/merge-queue/queue-modes#capping-scopes-you-did-not-list).

- `scopes.barrier_files`: optional file filters marking files that impact every scope. Only valid
  with a `files` source. A pull request that changes a matching file becomes a merge queue barrier,
  and so does one whose head commit was reported with `all_scopes: true`, even when no file
  matches. See
  [Declaring a pull request impacts every scope](#declaring-a-pull-request-impacts-every-scope).

### Manual source example

```yaml
scopes:
  source:
    manual:

queue_rules:
  - name: default
    batch_size: 5
```

With the configuration above you must push scopes yourself, typically from a CI job that analyses the
pull request and runs the `scopes-upload` action of `gha-mergify-ci` on GitHub Actions, or of the
`mergifyio/mergify-ci` plugin on Buildkite. This is the recommended approach when build systems
such as Bazel, Nx, Pants, or Turborepo already know which projects are affected.

A `manual` source has no file patterns to match, so scope detection (the `scopes` action) refuses it
on pull requests and pushes and fails the step. Compute the scopes with your build tool and upload
them instead. The [Nx](/configuration/scopes/nx), [Bazel](/configuration/scopes/bazel),
[Pants](/configuration/scopes/pants), and [Turborepo](/configuration/scopes/turborepo) guides show how.

## Declaring a pull request impacts every scope

Some pull requests invalidate everything: a build-system configuration change or a shared
toolchain bump. Enumerating every scope by hand is brittle, and the list goes stale as soon as
your set of scopes changes.

Instead, mark the change as a **barrier**, a pull request that impacts every scope. Mergify sets an
`all_scopes` flag on it and [serializes the queue](#barrier-behavior-in-the-queue) around it. How
you set the flag depends on where your scopes come from:

- **File-pattern scopes:** declare `scopes.barrier_files` and Mergify sets the flag whenever a pull
  request changes a matching file. An upload addressed to the pull request's head commit can also
  set `all_scopes: true`, so a build tool can raise a barrier the patterns do not cover.

- **Manual scopes:** set `all_scopes: true` when you upload scopes, through the GitHub Action, the
  Buildkite plugin, the CLI or the API.

### Barrier files (file-pattern scopes)

When your scopes come from [file patterns](/configuration/scopes/file-patterns), declare the files
that impact every scope under `scopes.barrier_files`. Whenever a queued pull request changes a
matching file, Mergify flags it with `all_scopes` and treats it as a barrier, with no CI job or
manual upload required.

```yaml
scopes:
  source:
    files:
      frontend:
        include:
          - apps/web/**/*
      api:
        include:
          - services/api/**/*.py
  barrier_files:
    include:
      - .github/workflows/**
      - Makefile

queue_rules:
  - name: default
    batch_size: 3
```

With this configuration, a pull request that changes `.github/workflows/**` or `Makefile` (files
that affect the whole repository) becomes a barrier, whichever scopes it also belongs to.

`barrier_files` accepts the same `include` and optional `exclude` patterns as a scope, with two
constraints:

- **At least one `include` pattern is required.** An empty or exclude-only filter would match every
  pull request and silently serialize the entire queue, so Mergify rejects it. The same rule lives
  in the JSON schema, so the dashboard and other config editors catch it too.

- **`barrier_files` only works with a `files` source.** A `manual` source reports the barrier
  through the API instead (see below), and a configuration with no source has no scopes to impact.
  Mergify rejects `barrier_files` in either case. Reporting the barrier through the API is not
  itself manual-only: a `files` source reads the flag off an upload addressed to the head commit
  as well.

A renamed file is matched at both of its paths, so moving a file *out of* a barrier pattern makes
the pull request a barrier too: the barrier file is gone from the location you declared.

You can also manage these patterns from the dashboard: the **Barrier files** editor in the queue
configuration **Scopes** section edits the same `barrier_files` filters for file-pattern scopes.

### Marking a barrier on upload

When you upload scopes yourself, set the `all_scopes` flag on the pull request. With the
[`gha-mergify-ci`](/integrations/gha/reference) GitHub Action or the
[`mergifyio/mergify-ci`](/integrations/buildkite#declaring-a-pull-request-impacts-every-scope)
Buildkite plugin, set `all_scopes: true` on the `scopes-upload` action, or on the `scopes` action
when a `files` source detects the scopes. With the [Mergify CLI](/cli/usage), pass `--all` to
`scopes-send`:

```bash
mergify ci scopes-send -s build-system --all
```

The CLI detects the head commit under GitHub Actions, Buildkite and CircleCI. Anywhere else, add
`--head-sha` with the pull request's head commit. In a Jenkins multibranch pipeline, that is all
the CLI needs: [Reporting scopes from Jenkins](/integrations/jenkins#reporting-scopes-from-jenkins)
says which commit to pass. On CircleCI and on any other CI, the CLI cannot tell which pull request
it runs for: add `--pull-request` too, as the
[Any CI recipe](/configuration/scopes/others#any-ci-mergify-cli) explains.

When you upload a scopes JSON file with `--scopes-json`, the CLI also honors an
`"all_scopes": true` field in the file itself, so your detection tooling can set the flag without
touching the command line.

You can send the flag through the [REST API](/api/pull-requests) as well. Address the upload by
commit, so it names the revision the scopes were computed for. This endpoint needs an application
key granted [CI Reporting](/api/usage#ci-reporting), which a key granted Every resource does not
hold:

```bash
curl -X PUT \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <your-application-key>" \
     -H "Content-Type: application/json" \
     -d '{"scopes": ["build-system"], "all_scopes": true}' \
     https://api.mergify.com/v1/repos/<owner>/<repository>/commits/<head-sha>/scopes
```

Send the pull request's head SHA, which is not always the revision your job checked out: on a
`pull_request` event the default checkout is a merge commit, and an upload keyed on that commit
matches no pull request head. The pull-request-number variant of this endpoint is deprecated: it
cannot record which revision an upload was computed for, so whichever upload arrives last takes
effect, whatever head it came from.

The flag complements the `scopes` list rather than replacing it: keep reporting the concrete
scopes your tooling detected, and set `all_scopes: true` on top when the change affects every
target.

### Barrier behavior in the queue

A pull request flagged with `all_scopes` conflicts with every scope, so the merge queue treats it
as a barrier:

- It shares a batch only with other barrier pull requests, and never runs its checks in parallel
  with other batches.

- Its batch takes its place in the queue when it stops filling, as every batch does: when it
  reaches `batch_size`, or when
  [`batch_max_wait_time`](/merge-queue/batches#configuring-batch-merging) runs out. Until then,
  another batch can [go ahead of it](#while-a-barriers-batch-fills).

- Every batch that took its place before the barrier completes first.

- Every batch that takes its place after the barrier waits for it to merge, including batches in
  scopes that had nothing queued when the barrier took its place.

- With [per-scope capacities](/merge-queue/queue-modes#limiting-concurrency-per-scope), the
  barrier consumes one slot in every capped scope.

The queue serializes at the barrier and resumes normal scope-aware batching once the flagged pull
request merges. Because a barrier defeats parallelism and is batched only with other barriers,
reserve `all_scopes` for changes that genuinely require testing against everything.

The flag is visible in the [merge queue status API](/api/merge-queue) and on the draft pull request
description created by the queue.

#### While a barrier's batch fills

A barrier orders the queue from the moment its batch stops filling, not from the moment the pull
request enters the queue. When another batch stops filling first, priority decides which of the two
goes ahead:

- A batch of the same or higher [priority](/merge-queue/priority) goes ahead of the barrier, even
  one holding pull requests queued after it. The barrier is then tested on top of that batch, so
  its checks still run against every change merged before it.

- A batch of lower priority waits behind the barrier: Mergify stops filling the barrier's batch
  early and places it first.

This window lasts at most `batch_max_wait_time`, counted from when the first barrier pull request
in the batch entered the queue, and closes as soon as the batch reaches `batch_size`. With the
default `batch_size` of 1, a barrier's batch is full as soon as it holds one pull request, so there
is no window at all.

## Best practices

- Keep scope names stable and small in number so batches stay meaningful.

- Prefer scopes that align with your CI topology: if a test suite covers a specific service or
  package, create a scope with the same boundary.

- Still configure sane `batch_max_wait_time` values: scopes help Mergify pick the right pull
  requests, but you control how long it waits for an ideal batch.

- Monitor merge queue analytics to verify that scope-aware batching increases success rate and
  reduces redundant CI runs; adjust scope definitions when you see batches mixing unrelated changes.
