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.

To branch from something other than main (a release branch, for example):

mergify stack new feat/my-feature --base origin/release-v2

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.