View as Markdown

Setup

Install Mergify CLI and configure your repository for stacked PRs.


See the CLI installation guide for full instructions.

Quick install:

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

2. Install skills for your AI coding agent

Section titled 2. Install skills for your AI coding agent

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:

Terminal windowbash
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 creates and updates pull requests through the GitHub API, so it needs a GitHub token. Neither a Mergify application key nor mergify auth login helps here: those authenticate to the Mergify API, which Stacks never calls.

The simplest option is the GitHub CLI. Install it, run gh auth login, and Stacks picks up its token on its own. To manage the token yourself instead, export it as GITHUB_TOKEN. See GitHub token for Stacks for the order Stacks tries them in.

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. For a stack pushed with --no-github-native, that deletion is also what makes GitHub retarget the next PR in the chain onto main. GitHub does that itself for a stack registered with its stacking API. See Merging Stacked PRs.

GitHub setting: Automatically delete head branches

Run the setup command in your Git repository:

Terminal windowbash
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 prepare-commit-msg hook that keeps the Change-Id when you amend with git commit --amend -m or -F. A new message passed that way would otherwise replace the old one, trailer included.

  • A post-commit hook that adds a Change-Id to a commit that still has none, in case the commit-msg hook did not run.

  • A pre-push hook that stops you if you accidentally use git push instead of mergify stack push on a stack branch. Run git push --no-verify to push anyway.

The command also sets the local Git config values notes.displayRef and notes.rewriteRef, so git log shows the notes you attach with mergify stack note, and a note stays with its commit when you amend or rebase it.

When it runs on a terminal, the command also asks whether to turn on git rerere in the repository. A stack rebases often, so the same conflict tends to come back, and rerere makes Git remember how you resolved it and replay that resolution. Answer yes and it sets rerere.enabled to true locally; answer no and it remembers the answer so it only asks once. You can turn it on later yourself:

Terminal windowbash
git config rerere.enabled true

The question is skipped when rerere.enabled is already set either way, and when there is no terminal to ask on, so mergify stack setup stays non-interactive in a script or a CI job.

mergify stack hooks reports whether the hooks are installed and up to date. To watch one work, create a test commit:

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

Check the commit message:

Terminal windowbash
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:

Terminal windowbash
git reset HEAD~1

These optional Git config settings let you customize Stacks behavior:

Setting Default Description
mergify-cli.github-server https://api.github.com Point Stacks at a GitHub Enterprise Server
mergify-cli.stack-branch-prefix stack/{username} Set the prefix for remote branch names
mergify-cli.stack-create-as-draft false Create PRs as drafts by default
mergify-cli.stack-github-native true Register the stack with GitHub’s stacking API
mergify-cli.stack-keep-pr-title-body false Don’t overwrite PR title/body on updates
mergify-cli.stack-revision-history true Keep a revision-history comment on each PR

Example:

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

mergify stack push has a flag for each of the stack- settings (--branch-prefix, --draft, --no-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.

mergify-cli.github-server has no flag, and a repository on GitHub Enterprise Server needs it: Stacks calls api.github.com until you point it elsewhere. Set it to your server’s URL. Stacks reaches any host other than api.github.com over HTTPS at /api/v3:

Terminal windowbash
git config mergify-cli.github-server https://github.example.com

The stack CLI reference lists every command in the group with its full set of flags and defaults.

Head to Creating Stacks to push your first stack.

Was this page helpful?