---
title: Batch Metadata
description: The metadata Mergify attaches to every batch it tests, and how your CI reads it with mergify ci queue-info.
---

Mergify attaches metadata to every batch it tests: the pull requests it holds, their scopes, the
failed batches a [split](/merge-queue/batches/failures) descends from, and the commit it was built
on. A CI job reads it to test only the scopes a batch touches.

## Reading the metadata

On a merge queue batch build, `mergify ci queue-info` prints the batch's metadata as JSON, and
exposes it as a `queue_metadata` step output when `$GITHUB_OUTPUT` is set. It reads a Git note on
the batch's head commit, so it works in any CI that checks out the queue branch, with no token.
Elsewhere it exits with an error.

```yaml
- uses: Mergifyio/setup-cli@v1

- name: Read the merge queue metadata
  id: queue-info
  if: startsWith(github.event.pull_request.title, 'merge queue:')
  continue-on-error: true
  run: mergify ci queue-info
```

```json
{
  "scopes": ["backend", "frontend"],
  "all_scopes": false,
  "pull_requests": [
    { "number": 123, "scopes": ["backend"] },
    { "number": 124, "scopes": ["frontend"] }
  ],
  "previous_failed_batches": [
    {
      "batch_pr_number": 980,
      "batch_pr_head_sha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
      "checked_pull_requests": [123, 124, 125, 126]
    }
  ],
  "previous_check_retries": [],
  "checking_base_sha": "f4a9c1e9b2d34c5a6f7081923abcde4567890123"
}
```

## Fields

- `scopes`: the [scopes](/configuration/scopes) of the batch's pull requests, empty without scopes.

- `all_scopes`: `true` when the batch holds a
  [barrier](/configuration/scopes#declaring-a-pull-request-impacts-every-scope), so test every scope.
  Treat a missing key as unknown, not `false`.

- `pull_requests`: the pull requests the batch checks, with their scopes.

- `previous_failed_batches`: the failed batches this batch was split from, oldest first, so its
  parent is the last. `batch_pr_head_sha` is the commit that batch's CI ran on; `batch_pr_number`
  is `null` for a batch [checked without a draft](/merge-queue/batches/ci#without-a-draft-pull-request).

- `previous_check_retries`: earlier runs of this same batch, re-run after their checks failed, each
  with its `attempt` number.

- `checking_base_sha`: the commit the batch's pull requests sit on, so a diff from it holds only
  their changes. With
  [`skip_intermediate_results`](/merge-queue/batches/failures#skipping-a-flaky-failure), a pass
  also merges the batches ahead, which that diff never read: diff from the base branch for a check
  that must cover them.

## See also

- [Run CI on a Batch](/merge-queue/batches/ci)
- [When a Batch Fails](/merge-queue/batches/failures)
- [Fail First](/test-engine/fail-first)
