GitHub PR stacks

Use this skill for dependent pull requests. Read maintenance and recovery before changing an existing published stack or operating its CI/review queue. Use the pull-request skill for labels, signing, descriptions, and release documentation.

Discover the tool and the actual stack

Start with gh stack --help and the relevant subcommand's --help; commands and supported flags can change. If the extension is missing, identify github/gh-stack as the required extension (gh extension install github/gh-stack). Follow the environment's installation permissions; do not silently replace native stacks with an unregistered branch chain.

A feature branch based on another feature branch is only a dependency chain. GitHub's native stack is a separate object. Creating PRs with gh pr create --base <parent> alone does not register that object. Check both the configured base branches and native stack membership. A bottom PR may target main and still belong to a stack; also look for open PRs based on its head branch.

When native registration is requested or otherwise authorized, use gh stack link for existing PRs in the intended bottom-to-top order. Inspect current remote membership first, since linking changes the stack. Do not convert an ordinary chain into a native stack merely to inspect it. Verify the resulting object and ordering on GitHub, not just local branch ancestry. For example, after substituting the actual repository and PR number:

gh stack link <bottom-pr> <middle-pr> <top-pr>
gh api graphql -f query='{ repository(owner:"OWNER", name:"REPO") {
  pullRequest(number:123) { stack { number size entries(first:100) {
    nodes { position pullRequest { number } }
  } } }
} }'

Paginate if the returned entries do not cover the reported size. gh stack link can register remote PRs without initializing local tracking; a local gh stack view failure alone does not prove the remote stack is absent. Inspect the installed checkout/link help to reconcile local tracking.

If the user requests an independent PR, branch from its requested trunk, explicitly target that trunk, and do not link it into the active stack or import the stack's implementation commits.

Commands and side effects

The installed command help is authoritative. Current command roles are:

After an interrupted push/submit/sync, inspect which branches, PRs, bases, and native stack entries actually changed before resuming. Do not assume an error means nothing was published.

Choose propagation for the actual stack type

Native GitHub stacks require linear history between their branches before merging. When a lower branch or trunk update breaks that relationship, GitHub prescribes a cascading rebase. Do not use parent merge commits as a general substitute for this native-stack repair. A clean local merge, or a repository that permits merge commits, does not establish native merge eligibility. The method used to land the stack (merge, squash, or rebase) is a separate choice. See GitHub's linear-history requirement.

Batch confirmed fixes before a necessary rebase, then validate the affected branches once. Deferring propagation while collecting fixes can save CI and review quota; it does not waive the native linearity requirement. Inspect the installed gh stack rebase scope flags and the actual dependency boundary instead of automatically rewriting every branch after each finding. rebase and sync are mutations, never status commands. Follow the detailed native-stack repair procedure.

Before requesting reviews, verify that every dependent layer in the intended review block contains its current direct parent and has that parent as its sole merge base. Assess the bottom PR's trunk freshness separately; an unrelated trunk advance alone does not require rewriting or delaying reviews. Do not skip stale intermediate layers by merging a lower update directly into a higher PR. Deferred propagation is unfinished integration; hold reviews for affected heads until the batch is stable. See the parent-chain checks.

For an ordinary dependent PR chain outside native stacks, signed parent merges may be appropriate when repository policy and the user's history preferences permit them. Verify that classification first; do not unlink a native stack to avoid its requirements without user authorization.

GitHub documents retained approvals after a native stack rebase when the PR diff is unchanged, even with stale-approval dismissal enabled. Do not assume every rebase loses every approval, or that every approval will survive a conflict resolution. Check GitHub review applicability, CodeRabbit review evidence, and CI separately; a retained review can refer to an earlier commit. For non-bot PRs, Atmos's Quality Gate currently requires exact-head CodeRabbit approval; bot-authored PRs are exempt. Read the live review's commit ID: GitHub may associate a retained approval with the new head, satisfying that requirement without another review. Unchanged diffs or patch IDs do not guarantee retention. Before publication, report the affected approved PRs and contiguous prefix at risk. Verify the gate implementation and use incremental review for a confirmed gap; changed SHAs never automatically justify full CodeRabbit reviews. See approval and CI verification.

Publish normal updates with ordinary fast-forward pushes. If a push is rejected, fetch and inspect the remote changes; do not automatically retry with a force-push flag. An explicit lease is an exception for a specifically justified, authorized operation, not the default publication command.

Do not merge new trunk commits through every PR merely because trunk advanced. Check native linearity, conflicts, required freshness, and the combined result first. Explain the affected range and validation/review cost before a required rewrite. Honor explicit history restrictions and existing authorization; do not add a new permission round when the repair is already authorized.

Build approvals from the bottom

Prioritize a contiguous approved bottom block, not an increasing count of approvals scattered through the stack. Verify applicable reviews in native stack order, including retained approvals after a native rebase, and distinguish those from the repository's exact-head CodeRabbit gate. Identify the first gap under the requested approval criterion, and spend review quota on closing gaps in the intended bottom block before higher layers. Preserve already approved heads where possible; necessary changes require fresh evidence. Report the approved bottom prefix separately from total approvals and from the prefix with all merge requirements satisfied. Verify the actual boundary before proposing a split or partial merge; see review scheduling and reporting.

Keep each PR reviewable

Stay below the 150-file review boundary. The repository quality gate currently requires changedFiles < 150 (at most 149); see qualityFileCount in magefiles/qualitygate/quality.go. Apply the stricter of the user's budget, repository gate, and bot configuration, and verify those when they change. This is not a GitHub diff limit. Check it when planning layers, after moving files or rebasing/updating parents, and again after publication. Count against the PR's actual parent, not main for every layer:

git merge-base --all <actual-parent-sha> <candidate-head-sha>
git diff --name-only <actual-parent-sha>...<candidate-head-sha>
gh pr view <number> --json changedFiles,headRefOid,baseRefName,baseRefOid

Count the complete path list (use NUL-delimited output in automation); do not rely on a truncated API file listing or count only new edits. Multiple merge bases make the comparison ambiguous: repair the ancestry or investigate before accepting its count. Keep some room below the effective limit when splitting work. Prefer moving cohesive docs, examples, casts, or tests with their owning behavior to an appropriate existing subsequent PR when authorized; recheck both layers' independent validity, counts, and native stack membership. Do not create an extra PR contrary to the user's requested shape.

Worktree and ownership safeguards

• Use clean, isolated worktrees for independent layer fixes. Give parallel agents ownership of specific layers/files and keep one coordinator responsible for propagation, publication, and review requests. Do not let multiple workers push the same branch or spend the same review quota.
• Checkout does not clear staged or unstaged edits to files shared between branches. Before switching, inspect git status --short, git log -3 --oneline, and git diff --cached --stat. Preserve unfinished work; do not discard or stash it to get a clean checkout. Unstaging alone does not isolate edits.
• An affected-file hook can inspect inherited committed changes, while missing a staged-only path. Diagnose the owning layer before fixing a hook failure; a passing hook alone is not proof that all staged files were checked. Run applicable checks explicitly in isolated worktrees when needed.
• Fix confirmed findings at the earliest affected layer. During propagation, preserve later intentional behavior as well as the fix: later docs may correctly supersede an earlier rollout phase's wording. Resolve overlapping logic semantically; neither concatenating both sides nor taking one side wholesale is a general conflict-resolution strategy.
• Preserve signed commits and hooks. If signing fails (including a locked signing agent), retain the prepared work and report the blocker; do not bypass signing to publish.

Finish the requested scope

Use the maintenance reference to freeze candidate heads, publish safely, and coordinate final-head CI/coverage and applicable CodeRabbit approval evidence. Report those states separately. Default to incremental CodeRabbit requests (@coderabbitai review). Unattended queues must not request full reviews or automatically escalate to them; see the reference for handling missing approvals.

Merge only when explicitly authorized. When available and compatible with repository rules, gh stack merge can merge the selected bottom portion atomically, avoiding a repeated merge-one/rebase/review cycle. GitHub still enforces protection rules and native stack linearity; atomic merge is not a bypass. Approval to repair history is also separate from approval to land PRs. Verify the selected PRs, current heads, and merge method before invoking it. Do not treat approval to fix CI or request reviews as approval to merge or close PRs.

Label each PR separately

Per the pull-request skill's semver-label rule, the label is per-PR, not per-feature. If a five-layer stack adds one user-visible feature, only the final layer that wires it up gets minor/major; the foundation and plumbing layers underneath it get no-release. Do not give every layer the same label because they belong to one larger effort.

no-release classifies non-user-visible work for the PR policy and release-documentation checks; it does not suppress a version bump. The release-drafter resolver in .github/auto-release.yml currently maps this label to patch. Keep using the policy's label for foundation PRs; changing release publication or version resolution is a separate policy change.