Stacked Pull Requests

A stacked pull request is a pull request whose base branch is the head branch of another open pull request. Stacking lets you split a large change into a chain of small, reviewable pull requests that build on each other. Starting with Gitea Enterprise v27.3.8, Gitea detects such chains automatically and shows the whole stack on every pull request in it. A valid license is required to show the stack.

Create a stack

1. Create a branch feature-part-1 from main and open a pull request from it into main.
2. Create a branch feature-part-2 from feature-part-1 and open a pull request from it with feature-part-1 as the base branch.
3. Repeat for the next part, always basing it on the head branch of the previous pull request.

When the second pull request is opened, Gitea looks for an open pull request in the same repository whose head branch is the new base branch. If there is exactly one, the two are linked into a stack and a stack is created when the parent was not part of one yet. Nothing has to be configured.

Gitea does not link the pull request when:

• the parent pull request comes from a fork, because stacks across forks are not considered
• more than one open pull request uses that head branch, because the parent is then ambiguous
• the parent was not created in the regular branch flow (for example it was opened with AGit)

A stack is a chain, not a tree: each pull request has one parent and one child.

Stack panel

Every pull request in a stack shows a Pull request stack panel. It lists all pull requests of the stack from the top to the base, shows the position of the current one (for example Stack 2 / 3), highlights the current pull request, and marks pull requests that are merged or closed. An entry can also be flagged Conflicted or Outdated. Select an entry to open that pull request.

Review and merge a stack

• Review each pull request on its own. The diff of a stacked pull request only contains its own change, because its base is the head of its parent.
• Merge from the bottom of the stack: first the pull request that targets the real base branch, then the next ones. When a parent is merged and its branch is deleted, change the base of the next pull request to the target branch.
• The stack panel keeps showing merged and closed members, so the history of the change stays visible.

Agents

Agents use the same mechanism for delivery plans: a plan step that depends on an earlier step is based on that step’s branch, and the pull requests appear as a stack (“PR 2 of 3 in stack”).