mergify-stack

Mergify Stack Workflow

Stack Philosophy

A branch is a stack. Keep stacks short and focused:

• A stack should only contain commits that depend on each other
• Rationale: longer stacks take longer to merge

Proactive stack management:

• If an existing stack can be split into independent stacks, offer to do so
• When asked to do something new: if it can be done on a separate branch, either do so or ask if in doubt
• Default to creating a new branch for unrelated changes

Core Conventions

• Push: Use mergify stack push (never git push)
• Fixes: Use git commit --amend (never create new commits to fix issues)
• Amend notes: When amending a commit that already has a PR (i.e. has been pushed), attach a mergify stack note BEFORE mergify stack push to record why the commit was amended. The note appears in the PR's "Revision history" comment and JSON marker, so reviewers can see the reason without diffing.
• Mid-stack fixes: Stash any local changes first (git stash -u), then use mergify stack edit <SHA-or-Change-Id-prefix> to pause the rebase at the target commit. Amend it with git commit --amend, then git rebase --continue, then mergify stack push, then git stash pop. Non-interactive — never use git rebase -i for this. (Calling mergify stack edit with no argument falls back to a fully interactive git rebase -i and will hang in agent contexts — always pass a commit prefix.)
• Reordering: Stash any local changes first (git stash -u), then use mergify stack reorder (list all commits in desired order) or mergify stack move (move a single commit) instead of manual git rebase -i — non-interactive and avoids GIT_SEQUENCE_EDITOR quoting issues
• Fixup: Stash any local changes first (git stash -u), then use mergify stack fixup <SHA>... to fold a commit into its parent (drops the listed commit's message). Non-interactive — never use git rebase -i for this.
• Squash: Stash any local changes first (git stash -u), then use mergify stack squash SRC... into TARGET [-m "msg"] to combine multiple commits into one, with an optional custom message. Non-interactive — never use git rebase -i for this.
• Reword: Stash any local changes first (git stash -u), then use mergify stack reword <SHA> -m "new message" to change a commit's message in place. Non-interactive when -m is given — never use git rebase -i for this.
• Drop: Stash any local changes first (git stash -u), then use mergify stack drop <SHA>... to remove commits from the stack. Non-interactive — never use git rebase -i for this.
• Commit titles: Follow Conventional Commits (e.g., feat:, fix:, docs:)
• PR title & body: mergify stack copies the commit message title to the PR title and the commit message body to the PR body — so write commit messages as if they were PR descriptions. Everything that should appear in the PR (ticket references, context, test plans) MUST go in the commit message.
• Ticket references: Include ticket/issue references (e.g., MRGFY-1234, Fixes #123) in the commit message body, not added separately to the PR.
• PR lifecycle is fully managed by mergify stack: NEVER edit PR titles, bodies, or labels with gh pr edit or the GitHub MCP — they will be overwritten on the next push. NEVER close or merge PRs manually — mergify stack handles the entire PR lifecycle (creation, updates, and cleanup).
• Draft PRs: NEVER mark a PR as ready-for-review — all PRs stay as drafts. The user will manually move them out of draft after reviewing.
• Each commit must pass CI independently: Every commit in a stack becomes its own PR. Each PR runs CI separately, so every commit must be self-contained — it must compile, pass linters, and pass tests on its own without depending on later commits in the stack. When formatting or linting fixes are needed, they must be included in the commit that introduced the issue, not deferred to a later commit.