CLI

The Mergify CLI lets you interact with Test Insights data from the terminal. It’s handy when you want to triage a failing test quickly, or when an AI coding agent needs to decide whether to retry, fix, or ignore a failure.

Search the Test Insights catalog by test name and print health, ratios, and the most recent failure context for each match.

mergify tests show -r owner/repo "tests/auth/test_login.py::test_login_timeout"

Names accept glob patterns (*, ?), and several can be passed in one call. Add --json for a machine-readable payload. Run mergify tests show --help for the full list of flags, and see the API reference for the underlying endpoints and response schemas.

The exit code reflects the worst health observed across the matched tests, so callers can branch without parsing output:

Exit code 2 is reserved for CLI argument errors.

Add a test to quarantine so its failures stop blocking merges and no longer mark the pipeline as failed. The test keeps running, and its results keep flowing into Test Insights.

mergify tests quarantine -r owner/repo \
  --reason "flaky — tracked in MRGFY-1234" \
  "tests/auth/test_login.py::test_login_timeout"

Pass the fully qualified test name and a --reason (both required). The quarantine applies to every branch by default; scope it to one branch or pattern with --branch (-b). The command prints a quarantine ID you can pass to unquarantine. Add --json for a machine-readable payload, and run mergify tests quarantine --help for the full list of flags.

The command exits 0 on success and 6 on a Mergify API error, for example when the test is already quarantined.

Remove a test from quarantine, addressed either by its fully qualified name or by the quarantine ID that quarantine printed.

# By test name.
mergify tests unquarantine -r owner/repo \
  "tests/auth/test_login.py::test_login_timeout"

# By quarantine ID.
mergify tests unquarantine -r owner/repo \
  12345678-1234-5678-1234-567812345678

A UUID-shaped argument is treated as the quarantine ID and removed directly; anything else is looked up by name. Add --json for a machine-readable payload, and run mergify tests unquarantine --help for the full list of flags.

The command exits 0 on success and 6 on a Mergify API error, for example when the test is not quarantined.

The exit-code contract is designed to be chained from agents that ran a test, saw it fail, and need to decide what to do next.

if mergify tests show -r owner/repo "$FAILED_TEST" --json > /tmp/health.json; then
  status=0
else
  status=$?
fi

case $status in
  0) echo "Healthy or unknown: investigate as a real regression." ;;
  1) echo "Known flaky: retry before touching code." ;;
  6) echo "Broken: fix is required; skip the retry loop." ;;
esac

Add a skill or a prompt snippet that points the agent at the CLI:

When a test fails locally or in CI, before attempting a fix, run:

  mergify tests show -r OWNER/REPO --json "<failed-test-name>"

Then branch on the exit code:
- 0, non-empty payload → healthy in Mergify; investigate as a real
  regression.
- 0, empty payload → unknown to Mergify; treat as a new test or one on
  a non-default branch.
- 1 → known flaky. Rerun once; only investigate if it fails again.
- 6 → known broken (pre-existing). Surface to the user instead of
  attempting a fix.

In Cursor, add the same guidance to a project rule (.cursor/rules/test-triage.mdc) so it auto-loads in agent sessions.