---
title: Scopes with Bazel
description: Configure merge queue scopes using Bazel's dependency graph for precise batching.
---

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

## Configuring Manual Scopes

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

```yaml
scopes:
  source:
    manual:

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

## Detecting Scopes with Bazel

Use `bazel query` to determine affected projects and upload them to Mergify.

### GitHub Actions

```yaml
name: Detect Scopes
on:
  pull_request:

jobs:
  detect-scopes:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5

      - name: Get git refs
        id: refs
        uses: Mergifyio/gha-mergify-ci@v11
        with:
          action: scopes-git-refs

      - name: Get scopes
        id: scopes
        env:
          HEAD: ${{ steps.refs.outputs.head }}
          BASE: ${{ steps.refs.outputs.base }}
        run: |
          scopes=$( \
            bazel query --keep_going --noshow_progress --output=package \
              "buildfiles(set($(git diff --name-only --diff-filter=ACMR \"$BASE\" \"$HEAD\" | tr '\n' ' ')))" \
            2>/dev/null | sort -u | paste -sd, -
          )
          echo "scopes=$scopes" >> "$GITHUB_OUTPUT"

      - name: Scopes upload
        uses: Mergifyio/gha-mergify-ci@v11
        with:
          action: scopes-upload
          token: ${{ secrets.MERGIFY_TOKEN }}
          scopes: ${{ steps.scopes.outputs.scopes }}
```

### Buildkite

Using the
[`mergifyio/mergify-ci`](https://github.com/Mergifyio/mergify-ci-buildkite-plugin)
Buildkite plugin, a first step resolves the merge-queue-aware base and head
SHAs and exposes them as meta-data, while a second step computes the affected
projects with `bazel query` and uploads them to Mergify:

```yaml
steps:
  - label: ":mag: Get git refs"
    key: git-refs
    plugins:
      - mergifyio/mergify-ci#v1:
          action: scopes-git-refs

  - label: ":mag: Detect and upload scopes"
    depends_on: git-refs
    command: |
      BASE=$(buildkite-agent meta-data get "mergify-ci.base")
      HEAD=$(buildkite-agent meta-data get "mergify-ci.head")
      SCOPES=$( \
        bazel query --keep_going --noshow_progress --output=package \
          "buildfiles(set($(git diff --name-only --diff-filter=ACMR \"$BASE\" \"$HEAD\" | tr '\n' ' ')))" \
        2>/dev/null | sort -u | paste -sd, - \
      )
      buildkite-agent meta-data set "mergify-ci.scopes" "$SCOPES"
    plugins:
      - mergifyio/mergify-ci#v1:
          action: scopes-upload
          token: "${MERGIFY_TOKEN}"
```

### Any CI (Mergify CLI)

Install the [Mergify CLI](/cli) in your pipeline and export `MERGIFY_TOKEN`.
Use `mergify ci git-refs` to get the merge-queue-aware base and head SHAs and
`mergify ci scopes-send` to upload the detected scopes:

```bash
REFS=$(mergify ci git-refs)
BASE=$(echo "$REFS" | awk '/^Base:/ {print $2}')
HEAD=$(echo "$REFS" | awk '/^Head:/ {print $2}')

bazel query --keep_going --noshow_progress --output=package \
  "buildfiles(set($(git diff --name-only --diff-filter=ACMR \"$BASE\" \"$HEAD\" | tr '\n' ' ')))" \
  2>/dev/null | sort -u \
  | jq -R -s '{scopes: split("\n") | map(select(length > 0))}' > scopes.json

mergify ci scopes-send --file scopes.json
```

:::note
In the context of merge queue pull requests, the `HEAD` and `BASE` git references are specifically
calculated to detect changed projects in the current batch only, not in the batches this one depends
on. This ensures that your monorepo tool identifies only the projects affected by the PRs in the
current batch, allowing for more granular and efficient testing.
:::