Setup

See the CLI installation guide for full instructions.

Quick install:

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

Mergify ships Agent Skills that teach AI coding agents how to work with Stacks, so they run mergify stack push instead of git push, amend commits instead of creating fixups, and follow stack conventions automatically.

Claude Code:

/plugin install mergify@claude-plugins-official

Codex, Cursor, and any other skills.sh agent:

npx skills add Mergifyio/mergify-cli

Either command installs the whole bundle, which also covers the merge queue, CI Insights, config validation, and scheduled freezes. See Agent Skills for what each skill does and which token it needs.

Stacks needs access to create PRs. Set the MERGIFY_TOKEN or GITHUB_TOKEN environment variable, or install the GitHub CLI and run gh auth login. The CLI tries them in that order. See Authentication for where each token comes from.

Enable “Automatically delete head branches” in your GitHub repository settings (Settings > General > Pull Requests). When a stacked PR merges, this cleans up its remote branch automatically, which is also what lets GitHub retarget the next PR in the chain onto main. See Merging Stacked PRs.

Run the setup command in your Git repository:

mergify stack setup

This installs:

• A commit-msg Git hook that automatically generates a Change-Id for every new commit. The Change-Id is how Stacks tracks the relationship between your local commits and their GitHub pull requests.

• A pre-push hook that warns you if you accidentally use git push instead of mergify stack push.

Create a test commit to confirm the hook is active:

echo "test" >> test.txt
git add test.txt
git commit -m "test: verify stack setup"

Check the commit message:

git log -1

You should see a Change-Id trailer at the bottom of the message:

test: verify stack setup

Change-Id: Ia1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Clean up the test commit if you don’t need it:

git reset HEAD~1

These optional Git config settings let you customize Stacks behavior:

Example:

git config mergify-cli.stack-create-as-draft true

mergify stack push has a flag for each of these (--branch-prefix, --draft, --github-native, --keep-pull-request-title-and-body and --no-revision-history) to override the setting for a single push.

--branch-prefix is also accepted by mergify stack list, mergify stack open and mergify stack sync, which have to look for the same branches. Setting the Git config once covers all four.

Head to Creating Stacks to push your first stack.