Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
Support

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.

  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.

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 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. Gitea retargets the next pull request for you, see Merge retargeting.
  • The stack panel keeps showing merged and closed members, so the history of the change stays visible.

When a pull request of a stack is merged, Gitea changes the base branch of the pull request stacked on it to the base branch of the merged one. The next pull request then targets the real base branch right away, even if the head branch of the merged pull request is kept.

  • Only the pull requests stacked on the merged one are moved. Other pull requests that happen to use the same base branch are left alone.
  • If the head branch of a merged pull request is deleted, the pull requests based on it are retargeted to the base branch of that merged pull request. When that branch no longer exists, they are retargeted to the default branch.
  • It only applies to pull requests within one repository, and it follows the instance setting RETARGET_CHILDREN_ON_MERGE of the [repository.pull-request] section, which is on by default.
  • The stack panel marks the merged entry as merged and keeps the rest of the stack.

If you change the base branch of a pull request yourself, Gitea recomputes its position: the pull request and the ones stacked on it move together to the pull request whose head branch is the new base, or stay in their own stack. A pull request that is inserted in the middle of a stack, for example by retargeting the next pull request onto it, stays in the same stack instead of splitting it.

If a pull request is deleted for good, it is removed from its stack.

Automatic linking is on by default. A repository administrator can turn it off in Repository > Settings > Pull request stack by clearing Automatically link pull requests targeting another pull request’s head branch. Only pull requests within the repository can be linked automatically. With the setting off, new pull requests are not added to a stack, and the pull requests that are already in a stack still follow base branch changes.

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”).