gh-stackx

Use the gh-stackx gh extension to manage stacked pull requests on repositories that do not have the private-preview GitHub Stacked PRs API.

When to use

• You want to open a series of dependent PRs.
• gh stack submit fails with ⚠ Stacked PRs are not enabled for this repository.
• You need to keep PR bases correct as the stack is rebased or merged.
• You want to merge a stack from the top down without manually editing PR bases.

Security notice

gh-stackx is a convenience wrapper around the github/gh-stack gh CLI extension. It runs locally with the user's configured gh authentication. This skill does not collect, store, or forward GitHub credentials, and it does not install extensions or other skills automatically. Always review the source of any gh extension before installing it.

Prerequisites

• gh CLI installed and authenticated.
• github/gh-stack extension installed for local stack operations.
• gh-stackx extension installed.

Do not run gh extension install automatically. Installation must be explicit, and the source repositories (github/gh-stack and ThePlenkov/gh-stackx) should be reviewed before granting gh credentials. See the repository README for installation steps.

Core concepts

• Trunk — the base branch, usually main.
• Stack — an ordered list of branches where each branch builds on the previous one.
• Bottom — the branch closest to trunk.
• Top — the branch farthest from trunk.
• Base — the parent branch for a PR. The bottom layer uses trunk; every other layer uses the previous branch.

Workflow

Create a stack

git checkout main
git pull origin main

gh stackx init feature/auth
# work and commit

gh stackx add feature/api
# work and commit

gh stackx add feature/ui
# work and commit

Submit PRs

gh stackx submit       # drafts
gh stackx submit --open

submit pushes all branches and creates/updates PRs bottom-up with the correct --base and --head. Each PR body includes a ## Stack GFM table showing the full stack from top to trunk.

Sync after trunk or parent PR changes

gh stackx sync
gh stackx sync --remote upstream

sync runs gh stack sync and then updates every open PR base with gh pr edit --base.

Merge top-down

gh stackx merge
gh stackx merge --squash
gh stackx merge --rebase

merge starts at the top of the stack and merges each open PR with gh pr merge.

Local navigation

These pass through to github/gh-stack:

gh stackx view --json
gh stackx up
gh stackx down
gh stackx top
gh stackx bottom
gh stackx trunk

gh-stackx reports its own repo and version from manifest.yml:

gh stackx --version
gh stackx version
gh stackx -v

Important rules

• Keep the working tree clean before sync or merge; rebase operations fail on uncommitted changes.
• Create PRs bottom-up so each base exists before the child PR is opened.
• Merge top-down so dependent PRs are merged before their parents move.
• Do not commit .git/gh-stack. It is local metadata.

Troubleshooting

• gh stackx view fails: ensure github/gh-stack is installed.
• A PR has the wrong base: run gh stackx sync.
• submit or merge stops with errors: fix the underlying gh pr issue, then re-run.

Further reading

The full workflow is already inline above. For more, see the repository:

• Usage guide — practical walkthrough with examples.
• Stacked PR methodology — why and how stacked PRs work.
• Specification — full command and architecture specification.
• REVIEW.md — review policy for this repository.
• AGENTS.md — how to work on this repository.