View as Markdown

Batch Metadata

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 descends from, and the commit it was built on. A CI job reads it to test only the scopes a batch touches.

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"
}
  • scopes: the scopes of the batch’s pull requests, empty without scopes.

  • all_scopes: true when the batch holds a barrier, 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.

  • 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, a pass also merges the batches ahead, which that diff never read: diff from the base branch for a check that must cover them.

Was this page helpful?