stacking-prs

Create and manage GitHub native stacked PRs with the gh stack CLI.

713|118|Updated Aug 11, 2020
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill stacking-prs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: stacking-prs
Source: https://github.com/PostHog/posthog-foss/tree/main/.agents/skills/stacking-prs
Command: npx skills add https://github.com/PostHog/posthog-foss --skill stacking-prs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Splitting a large change into reviewable pieces is painful when each PR depends on the previous one: rebases cascade, CI costs multiply, and merges can bypass required review paths. This Skill provides the operational workflow for creating, syncing, and landing GitHub native stacked PRs in the PostHog repo without breaking branch protections or the Trunk merge queue.

Core Features & Use Cases

  • Stack creation and publishing: Initialize stacks with gh stack init, add layers with gh stack add, adopt existing branches or link existing PRs, and publish everything as draft PRs with gh stack submit --auto.
  • Iteration and sync: Cascade-rebase layers with gh stack sync, resolve rebase conflicts safely, handle force-with-lease refusals when bots push commits, and prune merged branches.
  • Queue-safe merging: Land stacks through the Trunk merge queue via /trunk merge on the top PR or bottom-first through /merging-prs, never with gh stack merge.
  • Cloud sandbox workflow: In cloud task environments where git push is blocked, build stacks with git_signed_commit and link them through the gh_stack MCP tool.
  • Use Case: You have a large feature touching database, backend, and frontend. Use this Skill to split it into three stacked PRs, publish them as drafts, keep them rebased on master, and land the whole stack atomically through the merge queue.

Quick Start

Ask the agent to split your current branch into a stacked PR chain using gh stack and submit the layers as draft PRs.

Frequently Asked Questions about stacking-prs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create stacked PRs on GitHub with the gh CLI?

Install the gh-stack extension with `gh extension install github/gh-stack`, then run `gh stack init` for the bottom branch and `gh stack add` for each layer above it. Publish the whole chain with `gh stack submit --auto`, which pushes branches and creates draft PRs with correct base branches.

How do I split a large pull request into a stack?

Slice the change by reviewable unit, such as migration, backend, and frontend layers, keeping the stack shallow at two to four layers. Each layer must make sense to review and merge alone, with a conventional-commit title and a filled PR template.

Can I merge a stacked PR with gh stack merge?

No. In this repo `gh stack merge` is forbidden because it merges the chain through GitHub's API and bypasses the Trunk merge queue. Instead comment `/trunk merge` on the top PR after explicit user approval, or land layers bottom-first via the standard merge process.

Why does gh stack sync refuse to push my branch?

Sync pushes with `--force-with-lease`, so it refuses when the remote branch moved, usually because a bot like ReviewHog pushed fix commits. Treat the refusal as a signal to fetch and read the new commits, never as a reason to force-push.

What are the limitations of GitHub stacked PRs?

All branches must live in the same repository with no cross-fork stacks, and the chain must be strictly linear with no branching structures. Rule bypass and auto-merge are unsupported, GitHub Desktop has no stack support, and every layer needs its own approval and green checks.