mergify-ci

Mergify CI Commands

Overview

The mergify ci command group provides tools for CI pipelines: uploading JUnit test results to Mergify CI Insights, detecting git references for diff-based operations, managing CI scopes for selective testing, and retrieving merge queue batch metadata.

Commands

mergify ci junit-process FILES...         # Upload JUnit XML + evaluate quarantine (primary command)
mergify ci junit-upload FILES...          # (Deprecated) Use junit-process instead
mergify ci git-refs                       # Detect base/head git references for the current PR
mergify ci scopes --config PATH           # Detect scopes impacted by changed files
mergify ci scopes-send -s SCOPE           # Send scopes tied to a pull request to Mergify
mergify ci queue-info                     # Output merge queue batch metadata from the current PR event

JUnit Processing (junit-process)

The primary CI command. Parses JUnit XML reports, checks quarantine status for failing tests, uploads results to Mergify CI Insights, and determines the final CI exit code.

mergify ci junit-process \
  --token "$MERGIFY_TOKEN" \
  --repository owner/repo \
  --tests-target-branch main \
  path/to/junit-results.xml

FILES can be individual paths or quoted glob patterns (e.g. 'reports/**/*.xml'). Always quote the pattern so Mergify expands it rather than the shell — this is the recommended approach for large, sharded test suites.

Key options:

• --token / -t (env: MERGIFY_TOKEN) -- CI Insights application key
• --repository / -r -- Repository full name (auto-detected in GitHub Actions)
• --tests-target-branch / -ttb -- Branch used for quarantine evaluation. Auto-detected per CI provider: GitHub Actions (GITHUB_BASE_REF → GITHUB_HEAD_REF → GITHUB_REF_NAME → GITHUB_REF), Buildkite (BUILDKITE_PULL_REQUEST_BASE_BRANCH → BUILDKITE_BRANCH), CircleCI (CIRCLE_BRANCH), Jenkins (CHANGE_TARGET → GIT_BRANCH).
• --api-url / -u (env: MERGIFY_API_URL) -- Mergify API URL (default: https://api.mergify.com)
• --test-framework -- Test framework name (optional metadata)
• --test-language -- Test language (optional metadata)
• --test-exit-code / -e (env: MERGIFY_TEST_EXIT_CODE) -- Exit code of the test runner, used to detect silent failures where the runner crashed but the JUnit report appears clean

Behavior:

1. Parses JUnit XML files into test spans
2. Checks quarantine status for failing tests against the Mergify API
3. Uploads all test spans to Mergify CI Insights
4. Prints a summary: tests run, failures, quarantined vs blocking
5. Exits with code 0 if all failures are quarantined, code 1 if any are blocking
6. If --test-exit-code is non-zero but no test failures are found, exits with code 1 (silent failure detection)

GitHub Actions example:

- name: Run tests
  id: tests
  run: pytest --junitxml=results.xml || echo "exit_code=$?" >> "$GITHUB_OUTPUT"

- name: Process test results
  if: always()
  run: |
    mergify ci junit-process \
      --test-exit-code ${{ steps.tests.outputs.exit_code || 0 }} \
      results.xml
  env:
    MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}

Git References (git-refs)

Detects the base and head git references for the current pull request context. Writes results to GITHUB_OUTPUT when running in GitHub Actions, and to Buildkite meta-data (mergify-ci.base, mergify-ci.head, mergify-ci.source) when running in Buildkite.

mergify ci git-refs
# Output:
# Base: abc1234
# Head: def5678

Output formats (--format):

• text (default) — human-readable Base: / Head: lines
• shell — MERGIFY_GIT_REFS_{BASE,HEAD,SOURCE}=... lines suitable for eval, with POSIX-safe shell quoting. When base can't be detected, MERGIFY_GIT_REFS_BASE=''.
• json — single-line JSON object with base, head, source keys. base may be null when it can't be detected (e.g., workflow_dispatch events); use jq -r '.base // ""' to coalesce to empty string.

# Consume values in a shell script without parsing:
eval "$(mergify ci git-refs --format=shell)"
nx show projects --affected \
  --base="$MERGIFY_GIT_REFS_BASE" \
  --head="$MERGIFY_GIT_REFS_HEAD"

# Or with jq:
BASE=$(mergify ci git-refs --format=json | jq -r '.base // ""')

Sources detected (in priority order): merge queue context, GitHub pull request event, GitHub push event, fallback to last commit.

Scopes (scopes)

Detects which CI scopes are impacted by changed files, based on a Mergify configuration file. Used for selective/targeted CI -- only run tests for scopes that have changed files.

# Detect scopes from changed files
mergify ci scopes --config .mergify.yml

# Detect scopes with explicit base/head
mergify ci scopes --config .mergify.yml --base origin/main --head HEAD

# Write detected scopes to a file
mergify ci scopes --config .mergify.yml --write scopes.json

Key options:

• --config (env: MERGIFY_CONFIG_PATH) -- Path to the Mergify YAML config file (auto-detected)
• --base -- Base git reference (auto-detected)
• --head -- Head git reference (default: HEAD)
• --write / -w -- Write detected scopes to a JSON file

The config file defines scopes with file patterns. When files change between base and head, matching scopes are identified and written to GITHUB_OUTPUT (on GitHub Actions) or to Buildkite meta-data under mergify-ci.scopes (on Buildkite), as a JSON map of scope names to "true"/"false".

Scopes Send (scopes-send)

Sends scopes tied to a pull request to the Mergify API. Used when scopes are determined manually or from a file rather than auto-detected.

# Send specific scopes
mergify ci scopes-send -s frontend -s backend -p 123

# Send scopes from a JSON file (produced by `mergify ci scopes --write`)
mergify ci scopes-send --scopes-json scopes.json -p 123

# Send scopes from a plain-text file (one scope per line)
mergify ci scopes-send --scopes-file scopes.txt -p 123

Key options:

• --token / -t (env: MERGIFY_TOKEN) -- Mergify key
• --repository / -r -- Repository full name (auto-detected)
• --pull-request / -p -- Pull request number (auto-detected in GitHub Actions)
• --scope / -s -- Scope name (repeatable)
• --scopes-json -- JSON file containing scopes (output of mergify ci scopes --write)
• --scopes-file -- Plain-text file with one scope per line

Queue Info (queue-info)

Outputs merge queue batch metadata from the current pull request event. Only works on merge queue draft pull requests. Writes output to GITHUB_OUTPUT when running in GitHub Actions.

mergify ci queue-info
# Output: JSON with batch metadata

This command is useful in CI workflows that need to know whether the current run is part of a merge queue batch and what other PRs are in the batch.

Common Patterns

Full CI pipeline with quarantine

jobs:
  test:
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: pytest --junitxml=results.xml
      - name: Upload and evaluate
        if: always()
        run: mergify ci junit-process results.xml
        env:
          MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}

Selective testing with scopes

jobs:
  detect:
    outputs:
      scopes: ${{ steps.scopes.outputs.scopes }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: scopes
        run: mergify ci scopes --config .mergify.yml

  backend:
    needs: detect
    if: fromJSON(needs.detect.outputs.scopes).backend == 'true'
    steps:
      - run: pytest backend/