Stacked pull requests#

A stack is an ordered set of open pull requests in one repository. Each pull request targets the previous one's source branch; the bottom pull request targets the landing base, such as main. Use a stack when a change depends on another change that has not yet merged.

You need repository read access to view a stack and write access to change it. A pull request can belong to only one active stack and cannot be closed while it remains in that stack.

View or create a stack#

Open /<owner>/<repo>/stacks for the list, or /<owner>/<repo>/stacks/<stackNumber> for one stack. A member pull request also shows its stack in the sidebar.

From a local repository with the Cafe CLI signed in, you can link existing pull requests in bottom-to-top order:

Replace the example numbers with your own. You need at least two open pull requests forming a linear chain: pull 13 must target pull 12's branch, and pull 14 must target pull 13's branch. Linking does not publish local commits.

To publish local commits and later extend the same stack, reuse its submission name and base:

The existing members must be an exact prefix of the planned stack. New members are appended in order with revision checks; a changed or divergent stack stops submission. If a reply is lost, the CLI inspects the exact stack before continuing. Submission is not atomic: published branches and created pull requests remain after a later failure. Inspect them and rerun with the same name to resume; do not create a replacement stack to bypass a conflict.

An active GitHub App mirror with pull-request synchronization can import GitHub stacks and synchronize local creation, appending and unstacking. Changes reach GitHub asynchronously; check synchronization status before assuming both sides agree.

Landing#

Landing merges from the bottom through a selected member. As members merge, they leave the active stack and the next member targets the landing base. The stack is completed after its last member lands; its completed results remain readable.

Native repositories#

For a repository hosted directly in GitCafe, use the CLI from its local checkout:

The preview shows recorded readiness; permissions, branch state and merge requirements are checked again when the merge runs. Replace 14 with the last pull request you intend to land. --stack <number> instead selects the whole stack.

Only the merge strategy can land multiple members in one request. Rebase can land a single member; a multiple-member request returns STACK_MEMBER_NEEDS_RESTACK. Native stack landing does not support squash.

If the result is pending or you lose the response, inspect the existing operation:

Replace 7 with your stack number. If the operation requires fresh authorization (awaiting_credential), use its explicit operation ID to resume after the pending member settles:

Resume with the same account and delegation that started it. Do not start a new merge to recover a pending one. The browser also recovers the relevant unfinished landing when you reload its pull request. If fresh authorization is required, it offers Resume landing only after any admitted child merge has settled. Resume continues the original operation and scope using the stack's current revision; it does not create a replacement operation. If a child is still reconciling, the page keeps checking it and offers Resume landing when it settles. A reloaded native operation that stopped before admitting its next child can also be resumed with the same operation ID after its coordinator lease expires. If the coordinator is still active, Resume leaves it in control.

GitHub mirrors#

GitHub stack landing requires an active App mirror with pull-request sync and GitCafe writeback enabled. GitHub performs the merge and supports merge, squash and rebase. Check its operation until GitHub confirms the outcome. The CLI can read the latest result with --operation latest, but its explicit operation-ID option and --resume support native operations only. If a GitHub operation needs attention, check its status before attempting another merge.

Unstacking#

Unstacking dissolves a stack without closing its pull requests. A stack cannot be arbitrarily reordered, and individual members cannot be removed.

Restack#

Restacking updates dependent branches onto their current bases and rewrites their commits. Use Restack in a member's sidebar to start at that member, or cafe stack restack --stack <number> to start with the whole stack. It requires restack support on the instance and repository write access.

Server restacking has a significant limit: when a lower member is rewritten, it cannot automatically rebase the upper members while excluding the old lower commits. It stops with RESTACK_UPSTREAM_REBASE_UNAVAILABLE; following members report STACK_RESTACK_BLOCKED_BY_PREDECESSOR. Review the completed steps, then rebase the remaining layers locally and push them. Do not assume a failed stack operation means none of its branches changed.

If an operation reports reconciliation_required, its outcome is uncertain. Inspect it with cafe stack restack --stack <number> --operation latest. A caller with repository write access can ask the API to reconcile the exact operation with POST .../restacks/<operation>/reconcile and the stack's expectedRevision. A committed native publication is finalized without another rebase or branch update, but only after its durable authority projection is ready. Missing, unavailable, malformed, incomplete, or unknown status remains held. A native definite non-commit has no projection fields and fails and releases the operation. A push observed after the uncertain restack is never overwritten; that conflict remains held for manual resolution. Reading status alone does not reconcile or repeat the restack. Legacy operations without a prepared publish identity and failures before publication was prepared cannot yet be released automatically. The endpoint returns 202 while the outcome is held and 200 for a terminal operation. Recovery may finalize the published step but mark the operation failed because untouched successors need a fresh restack. Re-read the stack before starting that new operation; do not assume failed means no branch moved.