Skip to main content

Mergify CLI

CI Latest release Documentation

Drive Mergify from your terminal and CI pipelines: stacked pull requests, the merge queue, Test Engine, scheduled freezes, and configuration — all from a single self-contained binary that reuses your existing GitHub (gh) login.

mergify stack push          # turn your local commits into stacked PRs
mergify queue status        # inspect the merge queue
mergify ci junit-process report.xml   # upload test results to Test Engine
  • One static binary. No runtime, no dependencies — drop it on a developer laptop or a CI runner and go.
  • One command to sign in. mergify auth login approves the CLI in your browser and keeps the credential in your OS keychain; MERGIFY_TOKEN or --token for scripting. In a GitHub Actions job granted id-token: write, mergify ci needs neither: it exchanges the job's ID token.
  • Built for pipelines. Logs to stderr, structured --json output on read commands, and stable exit codes for scripts and runbooks.
  • Cross-platform. Linux (x86_64 + aarch64, glibc 2.28 or newer), macOS (aarch64; x86_64 as best effort, not tested before a release), and Windows.

Installation

brew install mergifyio/tap/mergify-cli

The fully-qualified name taps and installs in one step. Upgrade with brew upgrade mergify-cli — not mergify self-update, which overwrites the Homebrew-managed binary. See the tap for tap-trust and short-name details.

curl -fsSL https://raw.githubusercontent.com/Mergifyio/mergify-cli/main/install.sh | sh

Installs to ~/.local/bin/mergify. Override with MERGIFY_INSTALL_DIR=/usr/local/bin or pin a version with MERGIFY_VERSION=<version>. Upgrade with mergify self-update.

Manual download (Windows, or to bypass the script)

Grab the matching archive from the latest release:

  • Windows — download mergify-<version>-x86_64-pc-windows-msvc.zip, extract it, and put mergify.exe anywhere on your PATH.
  • Linux / macOS — download mergify-<version>-<target>.tar.gz (e.g. mergify-2026.10.1-aarch64-apple-darwin.tar.gz), extract with tar -xzf, and put the resulting mergify binary anywhere on your PATH.

Verify against SHA256SUMS from the same release if you care.

Authentication

Sign in once:

mergify auth login

It opens the approval page in your browser, and prints the URL and the code as well: pass --no-browser, or run it where there is no browser to open, and the printed pair is all you need. Once you approve, the credential lands in your OS keychain — or, on a machine with none (a container, an unattended agent, a headless box with no D-Bus session), in a restricted file under your configuration directory. mergify auth status says which account you are signed in as, and mergify auth logout asks the Mergify API to revoke the credential rather than only deleting the local copy.

The approval page labels the new token Mergify CLI on <hostname>. Pass --device-name "work laptop" to name the machine yourself, or --device-name= to keep the hostname from leaving the machine at all.

The commands that talk to the Mergify API resolve a credential in this order:

# Credential
1 --token / -t
2 MERGIFY_TOKEN
3 the credential stored by mergify auth login keyed by API URL

A GitHub token (GITHUB_TOKEN, gh auth token) is no longer a fallback: the Mergify API is dropping GitHub tokens, and a command with none of the credentials above fails and says how to get one. Run mergify auth login, or set MERGIFY_TOKEN in CI.

mergify ci skips step 3: its endpoints take a CI credential, and refuse the per-user one mergify auth login mints by design. In a GitHub Actions job granted id-token: write, with neither --token nor MERGIFY_TOKEN, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a short-lived Mergify OIDC CI token, once a trust policy of the organization allows the job (mergify oidc, below). On any other CI, MERGIFY_TOKEN holds an organization application key with the ci scope. With an application key in MERGIFY_TOKEN, mergify auth status names the key, its permissions and when it expires: a refused request never says which permission it lacked.

mergify stack also calls the GitHub API directly, and resolves that token separately (--token, MERGIFY_TOKEN, GITHUB_TOKEN, gh auth token). It is unaffected by the change above: stack needs a GitHub credential and Mergify never issues one. A Mergify-issued token (mut_…) is skipped there rather than sent to GitHub, which would only answer 401 Bad credentials — in MERGIFY_TOKEN, in GITHUB_TOKEN, and in what gh auth token returns, since it echoes GITHUB_TOKEN when that is set. Only an explicit --token is sent as given.

The repository and API URL resolve as before:

What --flag then env then
Repository --repository / -r GITHUB_REPOSITORY git remote (origin)
API URL --api-url / -u MERGIFY_API_URL https://api.mergify.com

Credentials are stored per API URL, so one machine can hold a credential for the hosted service and one for an on-premise install.

Mergify application keys come in two classes, each reaching its own set of endpoints rather than one being a subset of the other. A ci key is scoped to what a CI job does — trace upload, ci scopes-send, quarantine evaluation and the quarantine list. Trace upload and ci scopes-send take a ci key only, and answer an admin key or a user credential with 403 Forbidden. Reading test health (mergify tests show), changing the quarantine (mergify tests quarantines add / remove) and test retry (mergify tests retry) need an admin key or a user credential — the one mergify auth login stores — and answer a ci key with 403 Forbidden. GITHUB_TOKEN is not a Mergify credential and does not reach the Mergify API.

See the authentication guide for details.

Quick start

# Stacked pull requests — one PR per commit, kept in sync
mergify stack setup                # once per repo: install the git hooks the stack needs
mergify stack push                 # push commits and create/update their PRs
mergify stack list                 # show the stack and its PR status
mergify stack sync                 # rebase the stack onto its trunk

# Merge queue
mergify queue status               # current queue state for the repo
mergify queue status --json        # same, as machine-readable JSON
mergify queue add 123              # queue a pull request (number or URL)

# Test Engine — from inside your pipeline
mergify ci junit-process report.xml --test-language python

# Configuration
mergify config validate            # check .mergify.yml against the schema

Run mergify --help for the full command list and mergify <command> --help for any command's flags.

Commands

Every command group maps to a section of the CLI reference.

  • mergify auth — Sign in to Mergify and manage the stored credential (login, logout, status).
  • mergify stack — Create and maintain stacked pull requests. Docs
  • mergify queue — Inspect and control the merge queue. Docs
  • mergify events — Browse the events Mergify recorded for the repository or one pull request, as a timeline or JSON.
  • mergify ci — Send JUnit results and pull request scopes from any CI provider. Docs
  • mergify tests — Look up test health, manage the flaky-test quarantine, and turn test retry on or off. Docs
  • mergify oidc — Write the trust policies that let GitHub Actions jobs reach Mergify with their ID token instead of a stored key, and read why a job's exchange was refused. Takes the organization with --org, else the owner of the repository. Docs
  • mergify freeze — Schedule merge freezes for release windows and maintenance. Docs
  • mergify config — Validate your configuration and simulate actions before you merge. Docs
  • mergify self-update — Update the CLI to the latest release.
  • mergify completions <shell> — Print a shell completion script (see below).

Run mergify <command> --help for a group's subcommands and flags.

Shell completions

Generate a completion script for your shell — bash, zsh, fish, elvish, or powershell:

# zsh — write to a directory on your $fpath
mergify completions zsh > ~/.zfunc/_mergify

# bash — load in your current session (add to ~/.bashrc to persist)
source <(mergify completions bash)

# fish
mergify completions fish > ~/.config/fish/completions/mergify.fish

Global options

These are accepted on every command:

Flag Description
-v, --verbose Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays pipeable.
--debug Shorthand for at least debug-level logging (like -vv).
--color <auto|always|never> When to colorize terminal output.

Environment variables

Variable Effect
MERGIFY_TOKEN API token. Takes precedence over a stored mergify auth login credential. Unset in a GitHub Actions job granted id-token: write, mergify ci exchanges the job's ID token instead.
GITHUB_TOKEN Not a Mergify API credential. Still the GitHub token mergify stack uses.
GITHUB_REPOSITORY Default owner/repo when --repository is omitted.
MERGIFY_API_URL API base URL (default https://api.mergify.com).
RUST_LOG Fine-grained log filtering; overrides --verbose.
NO_COLOR Disable colored output. Must be set to a non-empty value; exported-but-empty counts as unset.
FORCE_COLOR, CLICOLOR_FORCE Force colored output when it would otherwise be off. Same non-empty rule, and NO_COLOR wins over both. All three apply to --color auto only.
MERGIFY_INSTALL_DIR, MERGIFY_VERSION Install-script target directory / pinned version.

Exit codes

Commands return stable exit codes so scripts and runbooks can branch on them:

Code Meaning
0 Success.
1 Unclassified runtime failure (I/O error, bug, or captured panic).
2 Argument parsing / usage error.
3 Stack, branch, or commit not found.
4 Rebase or merge conflict.
5 GitHub API request failed.
6 Mergify API request failed.
7 CLI invariant violated (e.g. run outside a valid context).
8 Configuration or credentials missing, unparseable, or failing validation (including "not logged in").

AI Agent Skills

Mergify CLI provides AI skills for managing stacked PRs and Git workflows, compatible with Claude Code, Cursor, and many other AI agents.

Install via npx (all agents):

npx skills add Mergifyio/mergify-cli

Install as a Claude Code plugin:

/plugin install mergify@claude-plugins-official

Documentation

Full reference and guides live at docs.mergify.com/cli.

Contributing

Bug reports and feature requests are welcome: open an issue. The CLI is developed by Mergify; this repository publishes it: the releases, the installer, the agent skills and this README, all updated with each release. Suggestions to install.sh, skills/ or the documentation are welcome as issues too. See AGENTS.md for what lives where.

License

Proprietary — see LICENSE. Use is governed by the Mergify Terms of Service.

Metadata

Release files for mergify-cli 2026.11.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for mergify-cli 2026.11.16
File Actions
mergify_cli-2026.11.16-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for mergify_cli-2026.11.16-py3-none-win_amd64.whl
mergify_cli-2026.11.16-py3-none-musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64 Details for mergify_cli-2026.11.16-py3-none-musllinux_1_2_x86_64.whl
mergify_cli-2026.11.16-py3-none-musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64 Details for mergify_cli-2026.11.16-py3-none-musllinux_1_2_aarch64.whl
mergify_cli-2026.11.16-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for mergify_cli-2026.11.16-py3-none-manylinux_2_28_x86_64.whl
mergify_cli-2026.11.16-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for mergify_cli-2026.11.16-py3-none-manylinux_2_28_aarch64.whl
mergify_cli-2026.11.16-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for mergify_cli-2026.11.16-py3-none-macosx_11_0_arm64.whl
mergify_cli-2026.11.16-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for mergify_cli-2026.11.16-py3-none-macosx_10_12_x86_64.whl

Total release size: 63.6 MB

Release files / mergify_cli-2026.11.16-py3-none-win_amd64.whl

Download URL mergify_cli-2026.11.16-py3-none-win_amd64.whl
Size 8.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
4e0bd22455e470b7521289414e650fece6c7ab17e1d19a803b2afefac700404e
BLAKE2b-256 checksum
How to use checksums
4085915abf1589cf2484b4f16d5a045b109311023d2b585dae147b7908b3e6a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mergify_cli-2026.11.16-py3-none-musllinux_1_2_x86_64.whl

Download URL mergify_cli-2026.11.16-py3-none-musllinux_1_2_x86_64.whl
Size 10.0 MB
Tags Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
3b766dac8197ecfacba3fe3852be0f79def18678102b556751c8d32eb86c7635
BLAKE2b-256 checksum
How to use checksums
2a4ad22fe8db1420dec7deedeb6117b7488c4ed7c5a5f5eb54fd221bd53c0b7c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mergify_cli-2026.11.16-py3-none-musllinux_1_2_aarch64.whl

Download URL mergify_cli-2026.11.16-py3-none-musllinux_1_2_aarch64.whl
Size 9.3 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
8350fc5a446d78d2e251799f1c7bec568511e0737bccfc72cd85a7a1a6b543f5
BLAKE2b-256 checksum
How to use checksums
6d002efcd98acad5d1c5ff0b90829c57fa218dfbbb2edbd8080ac0af59bc8c8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mergify_cli-2026.11.16-py3-none-manylinux_2_28_x86_64.whl

Download URL mergify_cli-2026.11.16-py3-none-manylinux_2_28_x86_64.whl
Size 9.9 MB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
33e6d95591d3411079c55817e75955cbe3d5a7778d8ce0f849f83035593d711d
BLAKE2b-256 checksum
How to use checksums
e7bd5562975f75167669da0aeb6f9254301d4412882c051a6a491c8e136ce17d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mergify_cli-2026.11.16-py3-none-manylinux_2_28_aarch64.whl

Download URL mergify_cli-2026.11.16-py3-none-manylinux_2_28_aarch64.whl
Size 9.3 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
c7175d32597e978a1d964db2ce454df4a0bc992568bf79d522d8c50bffbe6e5b
BLAKE2b-256 checksum
How to use checksums
aaf7faa451bd7e46c6029299dda95e761aee74824fc78b127e6bbe723211e0e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mergify_cli-2026.11.16-py3-none-macosx_11_0_arm64.whl

Download URL mergify_cli-2026.11.16-py3-none-macosx_11_0_arm64.whl
Size 8.1 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3b2dd1e82f3a1ea4d3b10121b5eab2eb12307529c16d8fea9e3a8ec0d0d2fb0f
BLAKE2b-256 checksum
How to use checksums
a94f23c35d9eca32c5d15575af84ac62ef70c358b62c4f60b8fb445f144e7fe2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mergify_cli-2026.11.16-py3-none-macosx_10_12_x86_64.whl

Download URL mergify_cli-2026.11.16-py3-none-macosx_10_12_x86_64.whl
Size 8.7 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
4cab42f0545752eaef3ec828b6ab084370a4165f2817275ef1601fc0f6ac822b
BLAKE2b-256 checksum
How to use checksums
81389c482988ab2ea8b6047422cf7adb585c0b50dc0a2c0ffe69db0729f5794b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for mergify-cli 2026.11.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for mergify_cli-2026.11.16-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.11.16 This release

7 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page