---
title: Setup
description: Install Mergify CLI and configure your repository for stacked PRs.
---

## 1. Install the Mergify CLI

See the [CLI installation guide](/cli/usage) for full instructions.

Quick install:

<CliInstall />

## 2. Install skills for your AI coding agent

Mergify ships [Agent Skills](/cli/agents) 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:**

```text
/plugin install mergify@claude-plugins-official
```

**Codex, Cursor, and any other [skills.sh](https://skills.sh) agent:**

```bash
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](/cli/agents) for what each skill does and which token it needs.

:::tip
  Prefer to hand a single URL to your agent? Point it at
  [docs.mergify.com/stacks/agents](/stacks/agents). That page walks the agent
  through installing the CLI and the Stacks skill itself.
:::

## 3. Configure GitHub

Stacks needs access to create PRs. Set the `GITHUB_TOKEN` environment
variable, or install the [GitHub CLI](https://cli.github.com/) and run
`gh auth login`.

Enable "[Automatically delete head branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches)"
in your GitHub repository settings (Settings > General > Pull Requests). When
a stacked PR merges, this cleans up its remote branch automatically so the
next PR in the chain can rebase onto `main` cleanly.

<Image src={deleteHeadBranches} alt="GitHub setting: Automatically delete head branches" style={{ maxWidth: '66%' }} />

## 4. Initialize your repository

Run the setup command in your Git repository:

```bash
mergify stack setup
```

This installs:

- A `commit-msg` Git hook that automatically generates a
  [Change-Id](/stacks/concepts#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`.

## Verify It Works

Create a test commit to confirm the hook is active:

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

Check the commit message:

```bash
git log -1
```

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

```text
test: verify stack setup

Change-Id: Ia1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
```

:::tip
  If you already have commits without Change-Ids, run
  `git rebase -i <base-branch>` and choose **reword** for each commit. The hook
  will add the Change-Id automatically when you save the message.
:::

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

```bash
git reset HEAD~1
```

## Configuration

These optional Git config settings let you customize Stacks behavior:

| Setting | Default | Description |
|---------|---------|-------------|
| `mergify-cli.stack-branch-prefix` | `stack/{username}` | Prefix for remote branch names |
| `mergify-cli.stack-create-as-draft` | `false` | Create PRs as drafts by default |
| `mergify-cli.stack-github-native` | `false` | Also 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:

```bash
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.

:::note
  `mergify-cli.stack-github-native` is experimental. On top of the usual push,
  it registers the stack with GitHub's own stacking API, so GitHub shows the
  pull requests as a stack of its own.
:::

## Next Steps

Head to [Creating Stacks](/stacks/creating) to push your first stack.