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

## 1. Install the Mergify CLI

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

Quick install:

```bash
uv tool install mergify-cli
```

## 2. Install skills for your AI coding agent

Mergify ships 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:**

```text
/plugin marketplace add Mergifyio/mergify-cli
/plugin install mergify-stack@mergify
/reload-plugins
```

Or run `/plugin` on its own and use the **Marketplaces** tab to add
`Mergifyio/mergify-cli`, then pick `mergify-stack` from **Discover**.

**Any agent supporting [skills.sh](https://skills.sh)** (Cursor, Cline, and
others):

```bash
npx skills add Mergifyio/mergify-cli
```

:::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.
:::

:::tip
  The same marketplace ships plugins for other Mergify features: merge queue,
  CI insights, config validation, and scheduled freezes. Open `/plugin` and
  browse **Discover** to pick the ones you want.
:::

:::tip
  Third-party marketplaces don't auto-update by default. Open `/plugin`, go to
  **Marketplaces**, select **mergify**, and choose **Enable auto-update** to
  receive new skills and fixes as we ship them.
:::

## 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-keep-pr-title-body` | `false` | Don't overwrite PR title/body on updates |

Example:

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

## Next Steps

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