Creating Stacks

This guide walks you through creating a stack from scratch, from starting a branch to having multiple chained PRs on GitHub.

Use the stack new command to create a branch that tracks your main branch:

mergify stack new feat/my-feature

This is equivalent to git checkout -b feat/my-feature --track origin/main. You can also create branches however you normally do. Stacks doesn’t require its own branch creation command.

Work normally. Each commit should represent one logical unit of work, something that makes sense to review on its own.

For example, building a new API feature:

# First commit: data model
git add src/models/user.py
git commit -m "feat: add user data model

Define the User schema with fields for auth."

# Second commit: API endpoint
git add src/api/users.py
git commit -m "feat: add user registration endpoint

POST /api/users creates a new user account."

# Third commit: tests
git add tests/test_users.py
git commit -m "test: add user registration tests

Cover happy path, duplicate email, and validation errors."

Each commit automatically gets a Change-Id trailer. You don’t need to do anything special.

Run:

mergify stack push

What happens behind the scenes:

1. Rebases your branch on the latest main
2. Creates a remote branch for each commit
3. Opens a PR for each commit, chained in dependency order
4. Posts a stack comment on every PR showing the full stack

The full flow, from setup to push:

The result on GitHub: three small, focused PRs instead of one large one. Each PR contains exactly one commit’s worth of changes.

Each PR includes a stack comment that shows where it sits in the chain:

To see the state of your stack at any time:

mergify stack list

This shows each PR, its CI and review status, and a link to GitHub:

To update a commit after code review, see Updating Stacks. For a reviewer’s perspective on navigating stacked PRs, see Reviewing Stacks.