A pull request can contain a small diff and still depend on several unmerged changes. That distinction matters when reviewing GitHub stacked pull requests: approving one layer is not the same as approving everything that must land beneath it. Before merging, identify the dependency chain, the affected reviews and the actual merge scope.
GitHub’s October 6, 2026 announcement makes stacked pull requests generally available on all github.com plans. It says GitHub Enterprise Server support will arrive in an upcoming release, and stack auto-merge is rolling out over the following weeks. Do not assume those two capabilities are already available on your installation simply because the main feature is generally available.
Evidence boundary: CoreSecTech checked the linked official documentation on October 7, 2026. We did not run a repository pilot, benchmark review time or reproduce a merge. The branch example below is hypothetical; the featured image is a conceptual illustration, not GitHub UI. Recommendations are a review checklist, not a claim that stacks automatically improve productivity.
1. Decide whether the changes really form a stack
GitHub’s stack overview defines a chain in one repository: the bottom pull request targets the trunk, and each higher pull request targets the branch below it. The trunk is often main, but can be another branch. Cross-fork stacks and GitHub Desktop are not supported.
For a hypothetical export feature, one layer might define a file format, another add the export operation, and a third add a menu entry. Ask whether the menu needs the operation and whether that operation needs the format. If yes, the order carries meaning. If the same project also changes an unrelated help-page typo, putting it on top adds coordination without adding a dependency. CoreSecTech recommends keeping that independent change separate.
Write one sentence per layer explaining what it needs from the layer below. If the explanation is merely “these were written on the same day,” reconsider the grouping. A stack is a way to express dependencies, not a substitute for deciding where reviewable boundaries belong.
2. Record the branches before reading the diff
Use a private planning record like this. These names and changes are illustrative, not an existing repository or test result.
| Layer | Targets | Review question |
|---|---|---|
| Bottom: export-format | main | Is the format contract acceptable? |
| Middle: export-operation | export-format | Does the operation use that contract correctly? |
| Top: export-menu | export-operation | Does the menu expose the intended behavior? |
For each real pull request, record its branch, target, owner, acceptance question and required checks. Confirm the dependency order in GitHub’s stack display rather than assuming the numeric pull-request IDs show it. A later-created pull request is not necessarily the top layer after restructuring.
The overview says each layer shows its own diff. That makes a focused review possible, but it does not remove the need for context. A reviewer of the menu should know the agreed format and operation behavior without having to reapprove every line in those layers.
3. Check prerequisites without copying a mutation sequence blindly
GitHub’s current quickstart requires GitHub CLI 2.90.0 or later, Git 2.20 or later, authentication and a repository you can push to. Check installed versions first:
gh --version
git --versionThe documented extension installation command is:
gh extension install github/gh-stackThis installs software; it is not a read-only version check. Use the official extension and your team’s approval process. The quickstart then uses gh stack init, gh stack add BRANCH-NAME, gh stack push and gh stack submit for initialization, adding layers, pushing and submitting pull requests. Those commands change local or remote state. Follow the full official sequence in the intended repository rather than treating the list as a paste-and-run script.
Before starting, identify the repository, intended trunk and any uncommitted work. Keep a recoverable copy of work you cannot afford to lose. Stop if an authentication prompt points to an unexpected account. Stacking does not grant permission to push to a repository or bypass its contribution policy.
4. Fix feedback in the layer that owns the change
The official review guide directs authors to change the appropriate branch, commit the fix, cascade it with gh stack rebase, and push the updated stack. Higher layers then receive the update and their CI checks are re-triggered. The documented push uses --force-with-lease for rebased branches.
In the example, correcting the format belongs in the bottom layer, not as a hidden workaround in the menu. After the update, ask whether the operation and menu still make the same assumptions. This is a semantic review question: a clean rebase is not proof that the behavior remains correct.
Coordinate before rewriting shared branch history. If a rebase reports a conflict, stop and inspect it; do not blindly accept every “ours” or “theirs” version. Have the change owner resolve the conflict, then recheck the affected diff and tests. This guide does not prescribe a universal recovery command for an unknown repository state.
5. Confirm what a merge will actually include
GitHub’s merge instructions describe bottom-up merging. Selecting a higher pull request merges a contiguous group from the lowest unmerged layer through the selected one. A middle layer cannot merge in isolation while its prerequisites remain unmerged.
- Bottom only: review the format change and its requirements before landing it.
- Through the middle: treat the format and operation as the proposed merge scope.
- Through the top: inspect readiness for all three layers, not just the menu diff.
The merge guide requires passing checks and approvals below the selected layer, linear stack history, and the current pull request’s compliance with the trunk’s protection requirements. After a partial merge, the next unmerged layer is automatically rebased to target the trunk directly. Reinspect the displayed state afterwards rather than carrying an old branch diagram forward.
Rollout caveat: the merge guide still says stack auto-merge is unsupported, while the newer October 6 changelog announces a gradual rollout. Treat the dated announcement as the release update, but verify that the actual control is available before designing an unattended merge process. Neither source establishes that every repository already has it.
6. Preserve CI coverage before optimizing cost
GitHub’s CI guide says workflows run as if each layer targets the stack trunk. A pull_request workflow filtered to main can therefore run for every layer, not just the bottom. More layers can mean more workflow executions.
The guide exposes stack metadata at github.event.pull_request.stack, including size, position and base reference. It also distinguishes the original bottom position from the lowest currently unmerged layer. That distinction matters after a partial merge: a condition based only on original position 1 is not the same question as “which pull request now targets the trunk?”
CoreSecTech recommends observing the pilot’s actual runs before changing job conditions. For each expensive check, write down what behavior it protects, which layers can change that behavior, and whether the check blocks a merge. Only then consider reducing redundant work. Running a test only at the top is a deliberate coverage decision—not an automatic best practice for every project.
For organization rollout, GitHub’s administration guidance also warns that programmatic stack merges require the asynchronous merge API; legacy merge endpoints cannot merge a stack. Include your merge bot or ChatOps integration in the pilot. Do not discover an incompatible automation path during a production release.
FAQ
Does a small top-layer diff mean only that layer will merge?
No. Diff scope and merge scope are different. A higher selection includes its unmerged prerequisites. Inspect the stack and the merge box before confirming.
Do stacked pull requests prove better developer productivity?
No. GitHub publishes aggregate improvement claims in its announcement; CoreSecTech has not validated them or established causation. For a pilot, record review delays, rework, CI usage and release outcomes separately. More merged code is not, by itself, proof of better quality.
Should unrelated changes be stacked to reduce administration?
Not by default. First ask whether they depend on one another. Independent changes may be easier to review and release separately; use a stack when its explicit dependency chain solves a real coordination problem.
Pre-merge checklist
- Confirm repository, trunk and dependency order.
- Match each layer to an owner and an acceptance question.
- Put requested fixes in the layer that owns them.
- Inspect affected higher layers after rebasing.
- Confirm the entire proposed merge group meets its requirements.
- Verify CI coverage and any merge automation before relying on it.
- Record what actually landed and refresh the remaining stack’s state.
The useful outcome is not merely a tidier pull-request list. It is an explicit answer to three questions: what depends on what, what has been reviewed, and what will enter the trunk when you confirm the merge.