skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
mergifyio/mergify-cli79 installs

mergify-ci

Use Mergify CI commands to upload JUnit test results, detect git references, manage CI scopes, retrieve merge queue metadata, and write the OIDC trust policies that let GitHub Actions jobs reach Mergify without a key. ALWAYS use this skill when running `mergify ci`, `mergify tests` or `mergify oidc` commands, uploading test results to Mergify, managing Mergify test quarantines, detecting Mergify CI scopes, reading Mergify merge queue CI context, or finding out why a job's ID token was refused. Triggers on mergify ci, mergify tests, mergify oidc, junit-process, Mergify Test Engine, CI Insights, Mergify quarantine, Mergify scopes, scopes-send, git-refs, queue-info, trust policy, OIDC, id-token.

How do I install this agent skill?

npx skills add https://github.com/mergifyio/mergify-cli --skill mergify-ci
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides instructions for the Mergify CLI tool used in CI/CD pipelines. It is authored by the official vendor and adheres to security best practices, such as recommending the use of environment variables for secrets and advising against automated interactive logins. It identifies a standard surface for indirect prompt injection common to tools that process external test reports.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Mergify CI Commands

Overview

The mergify ci command group provides tools for CI pipelines: uploading JUnit test results to Mergify Test Engine, detecting git references for diff-based operations, managing CI scopes for selective testing, and retrieving merge queue batch metadata. mergify oidc writes the trust policies that let a GitHub Actions job reach Mergify with its ID token instead of a key, and reads why a job was refused.

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           # Report scopes against the pull request's head commit
mergify ci queue-info                     # Output the current build's merge queue batch metadata (from the git note)
mergify tests show NAME...                # Look up tests by name and print health, ratios, last failure
mergify tests runs                        # List a commit's test runs, by the job they arrived under
mergify tests quarantines add NAME        # Add a test to the Test Engine quarantine
mergify tests quarantines remove NAME     # Remove a test from the Test Engine quarantine
mergify tests quarantines get NAME        # Print a single quarantine by test name or id
mergify tests quarantines list            # List the tests currently in the Test Engine quarantine
mergify oidc trust-policies list          # List the organization's OIDC trust policies
mergify oidc trust-policies create        # Write a trust policy (show, update, delete too)
mergify oidc exchanges list               # List the latest ID token exchanges, and why one was refused
mergify oidc exchanges show ID            # Show the exchange a refused job's log names

Authentication

Two classes of Mergify application key, both minted in the dashboard. Each reaches its own list of endpoints, not a subset of the other's: of what this CLI calls, the two lists share only the quarantine list.

KeyReaches
ciWhat a CI job does: trace upload, scopes-send, quarantine evaluation (junit-process) and the quarantine list.
adminReading test health, the quarantine list, and mutating the quarantine. Not trace upload, not scopes-send.

Trace upload and scopes-send take only a ci key, or on GitHub Actions the job's ID token (below): an admin key or a user credential gets a 403. Every other endpoint below that refuses a ci key accepts a user credential (mergify auth login, which your user runs: see below) instead. GITHUB_TOKEN inside GitHub Actions is not a Mergify credential at all, so do not reach for it to clear one of these 403s.

The split follows the endpoint each command calls: reads of test health and writes to the quarantine are a person inspecting or overriding a repository, not something a pipeline does, so they are outside what a ci key carries; trace upload and scope reports are what a pipeline sends, so they are outside what an admin key carries. Per command:

Commandci keyadmin key
ci junit-process, ci junit-uploadyesquarantine evaluation only — the upload gets a 403, reported as a rejected upload (the exit code is unaffected)
ci scopes-sendyesno — 403
tests runsyesyes (and mergify auth login)
tests quarantines list, tests quarantines getyes — both read the quarantine listyes
tests showno — 403yes
tests quarantines add, tests quarantines removeno — 403yes

ci git-refs, ci scopes and ci queue-info are evaluated locally and need no token at all.

GitHub Actions jobs need no key (OIDC)

On GitHub Actions, a job granted id-token: write with no MERGIFY_TOKEN trades its GitHub ID token for a short-lived token that does what a ci key does, on its own repository only, when a trust policy of the organization matches the job: ci junit-process, ci scopes-send and the test framework plugins (2026.11.2 or later) do it themselves. A MERGIFY_TOKEN that is set always wins. Writing a trust policy needs an organization admin or CI Admin: see OIDC Trust Policies. Fork pull requests get no ID token, as they get no secret. Jobs outside GitHub Actions keep a ci key.

JUnit Processing (junit-process)

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

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

On GitHub Actions, a job granted id-token: write needs no key (see GitHub Actions jobs need no key). On any other CI, the key is read from MERGIFY_TOKEN: set it in the job's environment from a secret rather than passing --token, which would put it in the process list.

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 from the CI provider, then the git remote)
  • --tests-target-branch / -b -- Branch used for quarantine evaluation. Auto-detected per CI provider: GitHub Actions (GITHUB_BASE_REF → GITHUB_HEAD_REF → GITHUB_REF_NAME), Buildkite (BUILDKITE_PULL_REQUEST_BASE_BRANCH → BUILDKITE_BRANCH), CircleCI (the base of the open pull request whose head is CIRCLE_SHA1, as Mergify knows it, unless CIRCLE_BRANCH is the repository's default branch → CIRCLE_BRANCH), Jenkins (CHANGE_TARGET → GIT_BRANCH), then the checked-out branch. On a branch of GitHub's merge queue (gh-readonly-queue/<base>/pr-…), whatever the provider, the branch it merges into. Without one, quarantine is off for the run: the results are still uploaded, and every failure blocks.
  • --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
  • MERGIFY_TRACEPARENT (env only) -- A W3C traceparent to put the uploaded test session inside a trace the caller already started; a malformed value is ignored and the session starts its own trace

Behavior:

  1. Parses JUnit XML files into test spans
  2. Checks quarantine status for failing tests against the Mergify API
  3. Checks the spans against the schema Mergify publishes of what it can ingest (https://docs.mergify.com/mergify-ci-traces-schema.json), then uploads them to Mergify Test Engine. An upload Mergify would drop (for example one without a branch, vcs.ref.head.name) is not sent: the report lists what is missing, and the run is reported as a rejected upload. When the schema cannot be fetched, the spans are uploaded unchecked
  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)
  7. Upload failures never affect the exit code (Mergify-side trouble must not break CI), but they are surfaced: on GitHub Actions the command emits an ::error:: annotation when the upload is rejected (refused by the schema check, or HTTP 4xx except 408/429, e.g. a token without access to the repository, or Test Engine turned off for it: the annotation then gives Mergify's reason) or a ::warning:: annotation for transient errors (5xx, 408, 429, network), and appends test_results_upload=success|rejected|failed to $GITHUB_OUTPUT so workflows can detect dead ingest programmatically
  8. With no MERGIFY_TOKEN, a job whose ID token Mergify refuses (no trust policy matches it yet) or does not exchange carries on without Mergify: nothing is uploaded and no test is quarantined, so it exits as points 5 and 6 say with every failure blocking. The report says MERGIFY_TOKEN is not set, skipping the test results upload and the quarantine check., followed by Mergify's reason when it refused, and so does a ::warning:: annotation on GitHub Actions; $GITHUB_OUTPUT gets test_results_upload=rejected. A Mergify that cannot answer the exchange is an outage instead, reported as in point 7

GitHub Actions example:

jobs:
  test:
    permissions:
      id-token: write
      contents: read
    steps:
      # ...
      - name: Run tests
        id: tests
        run: pytest --junitxml=results.xml || echo "exit_code=$?" >> "$GITHUB_OUTPUT"

      - name: Process test results
        if: always() && (!github.event.pull_request || github.event.pull_request.head.repo.full_name == github.repository)
        run: |
          mergify ci junit-process \
            --test-exit-code ${{ steps.tests.outputs.exit_code || 0 }} \
            results.xml

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 (a failure inside
# `eval "$(...)"` would go unnoticed):
refs=$(mergify ci git-refs --format=shell) || exit 1
eval "$refs"
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, Jenkins change request, fallback to last commit.

On a Jenkins change request build (CHANGE_ID set by a multibranch pipeline) that is not a merge queue draft (below), the base is the branch the pull request targets (CHANGE_TARGET), printed as the commit origin/<branch> names, and the head is HEAD. Jenkins fetches origin/<branch> when it merges the pull request into its target, and checks out the pull request alone otherwise: git-refs then fetches the target branch from origin, with the history it shares with HEAD, and fails when it cannot. That git fetch needs the repository's credentials in the step.

The merge queue context is the git note Mergify writes on the merge queue branch head (refs/notes/mergify/<branch>). It is read on pull request builds, on GitHub push builds of the branch, and on Buildkite and Jenkins builds of the branch, so a merge queue batch a CI builds as a branch, by a push trigger or a branch job, rather than as its draft pull request, gets the batch's checking base too. On a Jenkins branch build, the branch is GIT_BRANCH, or BRANCH_NAME in a scripted pipeline, which does not export GIT_BRANCH, and the head is HEAD. On a Jenkins change request, the branch is the one it comes from (CHANGE_BRANCH), unless that is a fork's (CHANGE_FORK), and the head is the commit the note is on: the commit Jenkins checked out (GIT_COMMIT, else HEAD), or its first parent when Jenkins merged a target that moved on since into the draft. The base, the commit the batch was built on, is fetched from origin when a shallow clone lacks it, and git-refs fails when it cannot. The note's git fetch needs the repository's credentials in the step; without them the build is read as any other change request or branch build. A push that creates a branch has no previous commit, so its base is the default branch.

On a GitHub push that did not fast-forward (the event's forced), such as a push back to an earlier commit, the head is a commit git-refs makes in the local clone: the pushed commit's files, with the base, the commit the push replaced, as its only parent. Its merge base with the base is the base, so the nx show projects --affected --base --head call above, git diff base...head and the other tools that compare from the merge base see every file the push changed, a rollback's included. git-refs fetches the base by its SHA when the clone lacks it, and prints the pushed commit with a warning when it cannot, or out of a clone. No ref names that head and no other clone has it: run mergify ci git-refs in the clone that compares, where it makes the same commit, rather than passing its head to another job.

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".

When the base is the before commit detected from a GitHub push event, the changed files are the ones that differ between it and the pushed commit, compared directly rather than from their merge base: a push back to an earlier commit selects the scopes of the files it reverts. Every other base, an explicit --base included, counts what head adds on top of it, from their merge base.

On a merge queue batch build (a draft pull request, or a push build of the merge queue branch), scopes are not computed from changed files: the command reads the engine's git note for the batch and returns the scopes the merge queue decided (the batch's scopes plus each batched pull request's scopes, including scopes a pull request's CI reported), plus the merge queue scope. A batch the note marks as a barrier (all_scopes: true) selects every scope. This also works with a manual scopes source. Without a note, or with a note that has no scopes list, it falls back to diffing files.

A renamed file counts against both of its paths, same as the engine: git mv critical/guard.txt ignored/guard.txt touches critical and ignored.

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.

The report is addressed by the pull request's head SHA, so it says which revision it was computed for and a result computed for an older head cannot be taken for the current one. The head is detected from the CI environment (GitHub Actions event payload, BUILDKITE_COMMIT, CIRCLE_SHA1, or a Jenkins pull request build's checkout); pass --head-sha to name it explicitly wherever it is not detected: a GitHub Actions event with no pull_request payload (push, workflow_run, ...), any other CI. A Jenkins multibranch pull request build needs no flag: the number comes from CHANGE_ID, and the head is the commit checked out (GIT_COMMIT, else HEAD) or, when the GitHub Branch Source plugin merges the pull request into its target branch, the first parent of the merge Jenkins made. No head is detected where git cannot read the checkout, such as a container without its .git, nor on an agent that merges with JGit, whose merge Jenkins does not make under its own name: pass --head-sha with the pull request's head there, or switch the source's strategy to "The current pull request revision". When no head SHA can be resolved, the command reports against the pull request number alone and warns: that route is deprecated and will be removed. A Mergify deployment that predates the commit endpoint (on-premise before 8.18.0) gets the same pull request route without a warning.

Needs a ci key, or on GitHub Actions the job's ID token; an admin key or a user credential gets a 403. See Authentication.

# 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

# Declare the PR impacts every scope (merge-queue barrier),
# e.g. a build-system or CI-workflow change
mergify ci scopes-send -s build-system --all -p 123

# Name the revision explicitly wherever it is not detected (the pull
# request head, not the revision a `pull_request` job or a Jenkins
# merge build checked out)
mergify ci scopes-send -s frontend -p 123 --head-sha "$PR_HEAD_SHA"

Key options:

  • --token / -t (env: MERGIFY_TOKEN) -- Mergify ci application key
  • --repository / -r -- Repository full name (auto-detected)
  • --pull-request / -p -- Pull request number (auto-detected under GitHub Actions pull request events, Buildkite and Jenkins)
  • --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
  • --head-sha -- Head SHA the scopes were computed for, 40 hexadecimal characters (auto-detected under GitHub Actions pull request events, Buildkite, CircleCI and Jenkins pull request builds)
  • --all -- Declare the pull request impacts every scope. The merge queue treats it as a barrier: never batched or run in parallel with other pull requests. The concrete scopes are still sent alongside the flag.

Tests Show (tests show)

Looks up tests by name on the repository's default branch and prints their health, success/failure ratios, and last failure context. The search is a batch API: pass one or more names (globs supported) and one block per match is rendered. It is read-only: it exits 0 once it has rendered the matches, whatever their health. Gate on health by consuming --json, not the exit code.

Needs an admin key or a user credential (mergify auth login) — a ci key gets a 403. See Authentication.

# Single test.
mergify tests show -r owner/repo \
  'ApplicationKeys.spec.ts.Permissions › Should not see keys table if not admin'

# Batch with glob, narrowed to one pipeline, JSON for jq.
mergify tests show -r owner/repo \
  --pipeline-name e2e --json \
  '*test_login*' '*test_logout*' \
  | jq '.tests[] | {test_name, health_status}'

Key options:

  • --repository / -r -- Repository full name (owner/repo); auto-detected from the CI environment or the local git remote when omitted.
  • --token / -t (env: MERGIFY_TOKEN) -- Mergify credential. Falls back to the credential mergify auth login stored. The CLI no longer falls back to GITHUB_TOKEN or gh auth token.
  • --api-url / -u (env: MERGIFY_API_URL) -- API base URL.
  • --pipeline-name, --pipeline-name-exclude -- Restrict / exclude by pipeline.
  • --job-name, --job-name-exclude -- Restrict / exclude by job.
  • --per-page -- Cap the search result count (1–100, server default 10).
  • --json -- Emit a single JSON document {"tests": [...]} to stdout.

Exit codes:

  • 0 -- Tests rendered, or no match at all. Health does not affect it.
  • 6 -- Mergify API error, including the 403 a ci key gets here.

Tests Runs (tests runs)

A test result upload that fails leaves the job green: the plugin exits 0 when Mergify refuses the upload, and results sent under the wrong job name pass unnoticed. mergify tests runs lists the test runs Mergify received for a commit (the Test run ID: … a plugin prints in the CI log), one line per job name they arrived under (MERGIFY_TEST_JOB_NAME, else the CI's job name — on GitHub Actions the job id, not its displayed name): how many runs, how many arrived whole, framework, plugin or converted report and the client's version, test counts. Only a run that did not arrive whole gets a line of its own.

mergify tests runs                 # The commit under test (in CI, the one results are uploaded for; else HEAD)
mergify tests runs --pr 123        # A pull request's head commit, as the origin remote has it
mergify tests runs --branch main   # A branch's commit on the origin remote
mergify tests runs --sha <SHA>     # A full commit SHA
mergify tests runs --json          # The API response as is, for jq or an agent

Each job name reads in one of these states (test_results in --json):

StateMeaning
results_receivedEvery run received so far arrived whole.
upload_errorA run arrived incomplete or unreadable (results left out, a missing part).
ingestingPart of a run is still waiting to be ingested: check again shortly.

It reads what Test Engine received and nothing else, the same on every CI provider. So to check a setup, compare the jobs you configured to upload with the job names listed: a name missing means nothing from that job reached Mergify — open the job in your CI to see whether it ran, and read its upload output (a plugin that failed before sending, or a refused upload, shows there). A name you did not expect, or several jobs under one name, means the job name sent is not the one you meant: set MERGIFY_TEST_JOB_NAME. A repository that refuses every upload (Test Engine turned off for it) says so above the list (test_results_ingestion in --json).

Each job reads from its latest CI run: a commit run on push and on its pull request reads from the later one. A re-run within it shows beside the run it repeats, counted as a re-run, each run with its attempt. The command exits 0 whatever the states: gate on --json if you need to.

Tests Quarantines Add (tests quarantines add)

Adds a test to the repository's Test Engine quarantine, so its failures stop blocking the CI verdict. Takes a single fully qualified test name; a --reason is required.

A quarantined test keeps running but stops failing CI, so nothing reminds anyone to fix it. When you quarantine a test, link the issue tracking its fix with --issue-url: file the issue first (or find the existing one), then pass its URL. Mergify shows the link on the quarantine.

Needs an admin key or a user credential (mergify auth login) — a ci key gets a 403. See Authentication.

# Quarantine on all branches, linked to the issue tracking the fix.
mergify tests quarantines add -r owner/repo \
  --reason 'flaky: login times out under load' \
  --issue-url 'https://linear.app/acme/issue/ACME-1234' \
  'test_login'

# Scope the quarantine to one branch, JSON output.
mergify tests quarantines add -r owner/repo \
  --reason 'broken on release branch' --branch-name release/1.0 --json \
  'test_logout'

# Scope it to the one job where the test is flaky, on main.
mergify tests quarantines add -r owner/repo \
  --reason 'flaky on the macOS runner' \
  --branch-name main --pipeline-name ci --job-name 'tests (macos)' \
  --issue-url 'https://github.com/owner/repo/issues/42' \
  'test_upload'

A quarantine's scope is a branch, a pipeline and a job; each one omitted means all of them. Scope it as narrowly as the failure: a test flaky in one job stays blocking in the others, so real failures there still show. A test can hold one quarantine per scope; then remove and get by name refuse to pick one and list the ids: pass the id of the one to target.

Key options:

  • --repository / -r -- Repository full name (owner/repo); auto-detected from the CI environment or the local git remote when omitted.
  • --reason -- Reason recorded for the quarantine; required.
  • --branch-name -- Branch to scope to. Omit for all branches.
  • --pipeline-name -- Pipeline to scope to. Omit for all pipelines.
  • --job-name -- Job to scope to. Omit for all jobs.
  • --issue-url -- Link to the issue tracking the fix, in any issue tracker. Must be an http or https URL; the API refuses anything else.
  • --token / -t (env: MERGIFY_TOKEN) -- Mergify credential. Falls back to the credential mergify auth login stored. The CLI no longer falls back to GITHUB_TOKEN or gh auth token.
  • --api-url / -u (env: MERGIFY_API_URL) -- API base URL.
  • --json -- Emit {"id", "test_name", "reason", "branch_name", "issue_url", "pipeline_name", "job_name"} to stdout.

Exit codes:

  • 0 -- Test quarantined.
  • 6 -- Mergify API error (e.g. the test is already quarantined).

Tests Quarantines Remove (tests quarantines remove)

Removes a test from the quarantine. Accepts either the fully qualified test name (resolved to its quarantine id via the list endpoint) or the quarantine id directly (as printed by tests quarantines add). A UUID-shaped argument is treated as the id and deleted without a lookup.

Needs an admin key or a user credential (mergify auth login) — a ci key gets a 403. See Authentication.

# By test name.
mergify tests quarantines remove -r owner/repo 'test_login'

# By quarantine id (the value `tests quarantines add` printed).
mergify tests quarantines remove -r owner/repo 12345678-1234-5678-1234-567812345678

Key options:

  • --repository / -r -- Repository full name (owner/repo); auto-detected from the CI environment or the local git remote when omitted.
  • --token / -t (env: MERGIFY_TOKEN) -- Mergify credential. Falls back to the credential mergify auth login stored. The CLI no longer falls back to GITHUB_TOKEN or gh auth token.
  • --api-url / -u (env: MERGIFY_API_URL) -- API base URL.
  • --json -- Emit {"id", "test_name"} to stdout (test_name is null when addressed by id).

Exit codes:

  • 0 -- Test unquarantined.
  • 6 -- Mergify API error (e.g. the test is not quarantined).
  • 7 -- The test name matches several quarantines; pass an id.

Tests Quarantines Get (tests quarantines get)

Prints a single quarantine, addressed by the fully qualified test name or the quarantine id (a UUID-shaped argument is matched against the id). The output mirrors one record of tests quarantines list.

# By test name.
mergify tests quarantines get -r owner/repo 'test_login'

# By quarantine id, JSON output.
mergify tests quarantines get -r owner/repo --json \
  12345678-1234-5678-1234-567812345678

Key options:

  • --repository / -r -- Repository full name (owner/repo); auto-detected from the CI environment or the local git remote when omitted.
  • --token / -t (env: MERGIFY_TOKEN) -- Mergify credential. Falls back to the credential mergify auth login stored. The CLI no longer falls back to GITHUB_TOKEN or gh auth token.
  • --api-url / -u (env: MERGIFY_API_URL) -- API base URL.
  • --json -- Emit the record (id, test_name, reason, branch_name, issue_url, pipeline_name, job_name, created_at, source, is_recovered) to stdout.

Exit codes:

  • 0 -- Quarantine found and printed.
  • 6 -- Mergify API error (e.g. no matching quarantine).
  • 7 -- The test name matches several quarantines; pass an id.

Tests Quarantines List (tests quarantines list)

Lists every test currently in the repository's Test Engine quarantine. Takes no test argument -- it prints the whole quarantine. Human output is one indented block per record -- the test name on its own line (never wrapped mid-name), then its id (the value delete accepts), branch, pipeline, job, source, recovered, issue (only when one is linked), and reason. --json emits the full records.

# Human output (one block per record).
mergify tests quarantines list -r owner/repo

# JSON for jq -- e.g. names of quarantines an auto-recover run flagged.
mergify tests quarantines list -r owner/repo --json \
  | jq -r '.quarantined_tests[] | select(.is_recovered) | .test_name'

A null branch_name, pipeline_name or job_name renders as * (the quarantine applies to all branches, pipelines or jobs). source is manual (added by a user) or auto (added by flaky detection). is_recovered flags quarantines whose recent runs suggest they can be removed. A null issue_url means no issue tracks the fix.

Key options:

  • --repository / -r -- Repository full name (owner/repo); auto-detected from the CI environment or the local git remote when omitted.
  • --token / -t (env: MERGIFY_TOKEN) -- Mergify credential. Falls back to the credential mergify auth login stored. The CLI no longer falls back to GITHUB_TOKEN or gh auth token.
  • --api-url / -u (env: MERGIFY_API_URL) -- API base URL.
  • --json -- Emit {"quarantined_tests": [...]} to stdout, each record carrying id, test_name, reason, branch_name, issue_url, pipeline_name, job_name, created_at, source, is_recovered.

Exit codes:

  • 0 -- Always, including an empty quarantine ("No quarantined tests found.").

OIDC Trust Policies (mergify oidc)

A GitHub Actions job gets a Mergify token for its ID token when one trust policy of its organization matches it, and a policy matches when each of its lines does: repositories, workflows, events and environments. Policies only allow, with no order and no deny, so a narrow one cannot hold back a broad one. OIDC is in Preview, open to every organization: it may still change.

Every mergify oidc command takes the organization with --org, else the owner of the current repository, and the credential of one of its admins or CI Admins (mergify auth login), or an application key with the OIDC trust policies permission, and the repositories one to name repositories (an admin key has both); a ci key gets a 403. Every command takes --json, which prints what Mergify answered; exchanges list --json puts the exchanges under exchanges, beside since and truncated (true when --limit left some out).

# Every policy, line by line.
mergify oidc trust-policies list --org acme

# The narrowest useful policy: one repository's CI jobs, on the CI events
# (push, pull_request, merge_group, schedule, workflow_dispatch), any
# workflow, any environment.
mergify oidc trust-policies create --org acme --name "api CI" --repository api

# Deploys only: one workflow, on push, in the production environment.
mergify oidc trust-policies create --org acme --name "api deploys" \
  --repository api --workflow .github/workflows/deploy.yml \
  --event push --environment production

# Change only the lines named; the others keep their values. A policy's ID
# is the UUID `list` shows before its name.
mergify oidc trust-policies update 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57 --org acme \
  --repository api --repository web

mergify oidc trust-policies delete 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57 --org acme

A line no flag names is the default on create: every repository, any workflow, the CI events, any environment. --name alone therefore trusts every CI job of the organization: ask the user before writing a policy, it decides which jobs get a token.

Lines:

  • --repository NAME (repeatable) -- only these repositories; --except-repository NAME -- every repository but these; --all-repositories. NAME or OWNER/NAME, of the organization's repositories Mergify's GitHub App can access.
  • --workflow PATH (repeatable) -- the workflow file of the job's own repository its run started from, .github/workflows/ci.yml, at any ref; --reusable-workflow OWNER/REPOSITORY/PATH[@REF] -- a reusable workflow the job runs, even one of its own repository (uses: ./.github/workflows/...), optionally pinned to a full ref (refs/heads/main) or a commit sha; --any-workflow.
  • --event EVENT (repeatable) -- replaces the CI events; --any-event. pull_request_target, workflow_run and issue_comment run with the repository's identity for people who cannot push to it: add them only when the user asks.
  • --environment NAME (repeatable) -- a job in no environment does not match; --any-environment.

Why a job was refused. The job's log prints Mergify's reason, which names the exchange: The exchange report lists it as exchange 5e0c9a7d-2b14-4f3e-8a61-c9d07b2e4f83. Read it:

mergify oidc exchanges show 5e0c9a7d-2b14-4f3e-8a61-c9d07b2e4f83 --org acme
mergify oidc exchanges list --org acme --result refused --repository api --since 1d

A refused exchange lists, per policy, the first line the job did not match (policy <NAME> (<ID>) events: pull_request_target is not one of its events): widen that policy, or write another, with the user's go. exchanges list reads the last 7 days by default (--since, up to the 90 days the report keeps), latest first, 20 at most (--limit). The refusal reasons:

ReasonWhat to do
no_policyThe organization has no trust policy: write one.
no_matching_policyNo policy matches the job: see each policy's line above.
repository_not_installedMergify's GitHub App cannot access the repository: the user adds it to the app's installation. --repository cannot name such a repository: list without it.
audience_mismatchThe job asked for a token for another Mergify: check MERGIFY_API_URL.

Queue Info (queue-info)

Outputs the current build's merge queue batch metadata as JSON. Reads the refs/notes/mergify/<branch> git note Mergify writes on the merge queue branch head the build is for; exits INVALID_STATE (7) when no note is found (i.e. not a merge queue batch build, or a pull request from a fork). Takes no arguments and needs no GitHub token.

It reads the note ci git-refs reads, fetching that branch's notes ref alone. On a pull request build it reads no other:

  • On a GitHub Actions pull request event (pull_request, pull_request_target, a review), the note for the pull request's branch on its head (pull_request.head), so the default actions/checkout of a pull_request event, GitHub's merge of the draft into its base, is fine. A pull request from a fork gets none.
  • On a Jenkins change request (CHANGE_ID set), the note for the branch the change request comes from (CHANGE_BRANCH), on the commit Jenkins checked out (GIT_COMMIT, else HEAD), or on the first parent of a merge, as when Jenkins merged a target that moved on since into the draft. A fork's change request (CHANGE_FORK) gets none.

On a branch build it reads the note for the branch built, on the commit built: the pushed branch on GitHub Actions push, BUILDKITE_BRANCH on BUILDKITE_COMMIT on Buildkite, GIT_BRANCH (else BRANCH_NAME) on HEAD on a Jenkins branch build. Without that note, it reads the note on HEAD, as on any other build.

The note's full payload is emitted verbatim (every field Mergify wrote, e.g. checking_base_sha, pull_requests with per-PR scopes, previous_failed_batches, top-level scopes). New fields appear automatically without a CLI update, so don't assume a fixed schema.

# In CI, on a merge queue batch build. Works in any CI (GitHub Actions,
# GitLab, CircleCI, Jenkins, ...) with plain git. When GITHUB_OUTPUT is
# set (GitHub Actions runner) it also writes the metadata there.
mergify ci queue-info

Mergify attaches the batch metadata as a git note to the MQ branch head commit, so reading it needs only git, no PR body and no GitHub token. To read the note on HEAD (GitLab, CircleCI, another GitHub Actions event, a branch build without its branch's note, ...), the command runs git fetch origin "refs/notes/mergify/*" itself (notes aren't fetched by default), then returns the note attached to HEAD. Requirements: the origin remote is reachable and, off a pull request build, the checkout is at the MQ branch head commit, which is the normal state inside a merge-queue CI run. A detached HEAD is fine.

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:
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Run tests
        run: pytest --junitxml=results.xml
      - name: Upload and evaluate
        if: always() && (!github.event.pull_request || github.event.pull_request.head.repo.full_name == github.repository)
        run: mergify ci junit-process results.xml

Selective testing with scopes

jobs:
  detect:
    outputs:
      scopes: ${{ steps.scopes.outputs.scopes }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        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/

When a command says there is no Mergify credential

On your user's machine, no Mergify credential found from tests show, tests runs, tests quarantines or oidc means neither --token, MERGIFY_TOKEN nor a stored login gave the CLI a credential. Stop and ask your user to log in:

  • Don't run mergify auth login yourself. It prints a URL and a code, then waits until a person approves it in a browser: you cannot finish it, and the tool call hangs.
  • In Claude Code, ask them to type ! mergify auth login at the prompt. Elsewhere, ask them to run mergify auth login in their own terminal.
  • Wait until they say it's done, then run the same command again.
  • Don't read another source instead (CI logs, the GitHub API) without asking them first.

ci junit-process and ci scopes-send say something else when they find no credential: they need an application key in MERGIFY_TOKEN (or OIDC on GitHub Actions), which logging in does not provide.

When a command or flag is missing

If mergify rejects a command or flag this skill names, the CLI is probably older than the skill: follow the mergify-cli-upgrade skill.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/mergifyio/mergify-cli/mergify-ci">View mergify-ci on skillZs</a>