Stacked Pull Requests: Stapel auf GitHub anlegen und prüfen

Was ein Stapel ist und was er bringt

Wenn Sie ein großes Feature in einem einzigen Pull Request öffnen, sieht der Reviewer Hunderte Zeilen auf einmal. Stacked Pull Requests (gestapelte Pull Requests) teilen dieselbe Arbeit in eine Folge kleiner Pull Requests auf. Diese Folge heißt Stapel (Stack), jeder Pull Request darin Ebene (Layer).

Nach GitHubs Definition besteht ein Stapel aus zwei oder mehr Pull Requests im selben Repository. Der unterste zielt auf den Hauptbranch des Stapels (Trunk); meist ist das main, es kann aber auch ein Release-Branch sein. Jeder weitere Pull Request zielt auf den Branch des Pull Requests darunter. Den Branch, auf den ein Pull Request zielt, nennt man seine Basis (Base).

Jeder Pull Request zeigt nur den Diff seiner Ebene: den Unterschied zwischen seinem Branch und dem Branch darunter. Für die Reihenfolge gilt eine Regel: Code, auf den eine Ebene angewiesen ist, steht im selben oder in einem tieferen Branch. Gemeinsame Typen und das Datenbankschema kommen nach unten, die API-Endpunkte und die Oberfläche, die sie nutzen, nach oben.

Das bringt zwei Vorteile. Laut GitHubs Dokumentation wird ein kleiner Pull Request schneller geprüft; er wird seltener nur überflogen, veraltet nicht so schnell und gerät seltener in Konflikte. Außerdem müssen Sie nicht warten, wenn Ihre nächste Änderung auf Arbeit aufbaut, die noch nicht gemergt ist: Sie setzen einfach einen neuen Pull Request darauf. Schreibt ein KI-Agent den Code, ergibt sich die Reihenfolge von selbst: eine Ebene pro Aufgabe.

Branches von Hand zu verketten ist nicht neu; neu ist, dass GitHub die Kette erkennt. Die Funktion kam am 30. Juli 2026 in die öffentliche Vorschau und wurde am 6. Oktober 2026 allgemein verfügbar; laut Ankündigung gibt es sie in allen Plänen von github.com.

Was die Funktion leistet, geben wir so wieder, wie es am 14. Oktober 2026 in GitHubs eigener Dokumentation stand. Wir entwickeln diffox, ein Tool, das Pull Requests prüft; bevor es die eingebaute Unterstützung gab, haben wir in unserem eigenen Repository einen Stapel von Hand gebaut. Was wir dabei gelernt haben, steht weiter unten in einem eigenen Abschnitt.

Einen Stapel auf GitHub anlegen

Für die Kommandozeile gibt es die Erweiterung gh stack der GitHub CLI. Sie legt die Branches in der richtigen Reihenfolge an, führt die Rebases aus, pusht, öffnet die Pull Requests und verknüpft sie zu einem Stapel. Ein Stapel mit drei Ebenen entsteht so:

gh extension install github/gh-stack

gh stack init auth-layer       # erster Branch, auf dem Hauptbranch
git add .
git commit -m "Authentifizierungsebene"

gh stack add api-endpoints     # zweiter Branch, auf dem ersten
git add .
git commit -m "API-Endpunkte"

gh stack add frontend          # dritter Branch
git add .
git commit -m "Oberfläche"

gh stack submit                # pusht, öffnet die Pull Requests, verknüpft sie zum Stapel
gh stack view                  # zeigt Branches, Pull Requests und ihren Status

gh stack submit öffnet jeden Pull Request mit der richtigen Basis: Der erste Branch zielt auf main, jeder weitere auf den darunter. Ist Ihr Hauptbranch nicht main, schreiben Sie gh stack init --base release auth-layer. Die Erweiterung brauchen Sie aber nicht unbedingt; denselben Stapel können Sie auch anders anlegen:

• Weboberfläche. Öffnen Sie den ersten Pull Request wie gewohnt. Geben Sie dem zweiten den Branch des ersten als Basis und wählen Sie die Option „Create stack“. Haben Sie schon offene Pull Requests, deren Basen eine Kette bilden, erkennt GitHub das und schlägt in einem Banner vor, sie in einen Stapel umzuwandeln.
• Coding-Agent. gh skill install github/gh-stack installiert den Skill, der einem Agenten die Arbeit mit gh stack beibringt; als Beispiel nennt GitHub Copilot.
• Andere Tools. Wer seine Branches mit Jujutsu, Sapling oder git-town verwaltet, öffnet dieselben Branches mit dem Befehl gh stack link als Stapel auf GitHub.

Auf der Seite eines Pull Requests, der zu einem Stapel gehört, erscheint die Stapelübersicht (Stack Map). Sie zeigt jeden Pull Request im Stapel und seinen Status und bringt Sie mit einem Klick zu jeder Ebene; der Hauptbranch steht ganz unten.

Branch-Schutzregeln und CI im Stapel

Die Schwachstelle der von Hand gebauten Kette waren die Regeln. Die oberen Ebenen zielen nicht auf main, sondern auf einen Feature-Branch; auch GitHubs Dokumentation schreibt, dass Branch-Schutzregeln und CI-Checks ohne eingebaute Unterstützung oft nur beim untersten Pull Request ausgelöst werden.

Im eingebauten Stapel wird jeder Pull Request nach den Regeln des Hauptbranches bewertet, egal auf welchen Branch er direkt zielt. Die Referenzseite nennt vier Regeln: erforderliche Review-Freigaben, erforderliche Statuschecks, CODEOWNERS und Code Scanning.

GitHub Actions folgt derselben Logik. Ein Workflow, der auf das pull_request-Ereignis für main reagiert, läuft für jeden Pull Request im Stapel; die Workflow-Datei müssen Sie nicht ändern.

Achten Sie aber auf den CI-Verbrauch: Weil ein Workflow einmal pro Pull Request läuft, vervielfacht ein großer Stapel den Verbrauch. Damit Sie teure Jobs auf bestimmte Ebenen beschränken können, stehen die Angaben zum Stapel laut Dokumentation in Workflow-Ausdrücken bereit: Unter github.event.pull_request.stack finden Sie die Größe des Stapels (size) und die Position des Pull Requests (position). Sind beide gleich, sind Sie auf der obersten Ebene.

Einen Stapel mergen

Ein Stapel wird von unten nach oben gemergt. Sie können mehrere Pull Requests auf einmal mergen, solange sie lückenlos beim untersten noch nicht gemergten Pull Request beginnen. Ein Pull Request in der Mitte lässt sich nicht allein mergen; die darunter werden mit ihm gemergt.

Laut Dokumentation muss ein Pull Request drei Bedingungen erfüllen, damit er gemergt werden kann: Er erfüllt alle Schutzanforderungen des Hauptbranches, jeder Pull Request darunter erfüllt sie ebenfalls, und die Historie zwischen den Branches ist linear. Kommt ein neuer Commit auf einen der unteren Branches oder ist der Hauptbranch weitergezogen, ist die Historie nicht mehr linear. Dann erscheint in der Merge-Box die Schaltfläche „Rebase stack“; auf der Kommandozeile entspricht ihr gh stack rebase, danach gh stack push.

Alle drei Merge-Methoden werden unterstützt: Merge-Commit, Squash und Rebase. Bei Squash wird jeder Pull Request zu einem Commit im Hauptbranch; drei Pull Requests, drei Commits. Nach dem Merge wird der nächste Pull Request automatisch rebased und zielt direkt auf den Hauptbranch. Ihre lokalen Branches aktualisiert gh stack sync --prune: Es spult den Hauptbranch vor, setzt die übrigen Branches darauf und löscht gemergte lokale Branches.

In Repositories mit Merge Queue (Merge-Warteschlange) kommen die Pull Requests eines Stapels in der richtigen Reihenfolge in die Warteschlange. Wird einer daraus entfernt, fallen auch die darüber heraus.

Als wir den Stapel von Hand bauten, hakte es an drei Stellen

Bevor es die eingebaute Unterstützung gab, haben wir im August 2026 in unserem eigenen Repository einen Stapel mit zwei Ebenen von Hand gebaut. Unser Repository mergt per Squash. Nachdem der untere Pull Request gemergt war, mussten wir für den oberen drei Dinge von Hand erledigen.

Das Erste war der Rebase. Squash macht aus den Commits des unteren Branches einen einzigen neuen Commit; die alten Commits stehen nicht in der Historie des Hauptbranches. Weil der obere Branch diese Commits noch mitbrachte, gab ein einfacher Merge mit dem Hauptbranch Konflikte. Gelöst hat es git rebase --onto, das nur die eigenen Commits des oberen Pull Requests überträgt. Das Zweite war die Basis: Der obere Pull Request zielte weiter auf den unteren Branch, wir haben ihn von Hand auf den Hauptbranch umgestellt.

Das Dritte geschah lautlos. Weder der Force-Push noch der Wechsel der Basis startete CI für die neue Spitze nach dem Rebase. Die grünen Haken auf der Seite gehörten zu Checks, die auf der vorherigen Spitze gelaufen waren. Gestartet hat CI erst das Schließen und Wiederöffnen des Pull Requests.

# der untere Pull Request wurde per Squash gemergt; Sie sind auf dem oberen Branch
git fetch origin
git rebase --onto origin/main <alte-spitze-des-unteren-branches>
git push --force-with-lease

# die Basis des oberen Pull Requests auf den Hauptbranch umstellen
gh pr edit 123 --base main

# ist der Commit, auf dem die Checks liefen, die Spitze des Branches?
gh pr view 123 --json headRefOid
gh run list --branch api-endpoints --json headSha,workflowName,conclusion

Auf eine ähnliche Falle stießen wir in einem anderen Pull Request. Als der Pull Request mit seiner Basis in Konflikt stand, erzeugte GitHub den Merge-Commit nicht, auf dem die Workflows laufen, und zehn von elf Checks starteten nie. Die Seite zeigte trotzdem „All checks have passed · 1 successful check“, denn der einzige Check, der lief, brauchte diesen Commit nicht. Die Regel steht in GitHubs Dokumentation: In einem Pull Request mit Konflikt laufen keine pull_request-Workflows.

Was GitHub Ihnen jetzt abnimmt

Legt man GitHubs Dokumentation neben diese Schritte, ergibt sich folgendes Bild.

Spalte „Von Hand gebaute Branch-Kette“: Rebase, Basis und Checks sind unsere eigene Erfahrung, die Zeile zu den Regeln stammt aus GitHubs Dokumentation. Spalte „GitHubs eingebauter Stapel“: GitHubs Dokumentation, 14. Oktober 2026.

Laut Dokumentation sind Rebase und Basis jetzt Sache von GitHub. Zum Squash beschreibt die Dokumentation von gh stack selbst, was wir erlebt haben: Nach einem Squash stehen die alten Commits nicht in der Historie des Hauptbranches; gh stack sync erkennt das und führt den Rebase mit --onto aus.

Zu den Checks nennt die Dokumentation zwei Fälle ausdrücklich: Nach der Schaltfläche „Rebase stack“ und nach gh stack push wird CI neu ausgelöst. Für den automatischen Rebase nach einem teilweisen Merge fanden wir am 14. Oktober 2026 keinen solchen Satz in der Dokumentation. Deshalb lohnt es sich, vor dem Merge einer oberen Ebene diese vier Dinge anzusehen.

Einen Stapel prüfen

Im Stapel prüfen Sie nicht einen großen Diff, sondern mehrere kleine, jeden gegen die Ebene darunter. Für Reviewer heißt das dreierlei.

• Fangen Sie unten an. GitHub empfiehlt, Reviews von unten nach oben anzufordern, wenn die Ebenen eng zusammenhängen: Ein Fehler unten wandert in jeden Branch darüber. Prüfen verschiedene Personen die Ebenen, geht es auch parallel.
• Suchen Sie im Diff einer oberen Ebene nicht den Code der unteren. Ist eine Funktion, die die dritte Ebene aufruft, in der ersten definiert, erscheint sie nicht im Diff und steht auch noch nicht in main. Die Definition liegt im Branch, den Sie gerade prüfen; die Stapelübersicht führt zum Pull Request dieser Ebene.
• Schreiben Sie die Feststellung in die Ebene, zu der sie gehört. Laut Dokumentation wird die Korrektur in dem Branch gemacht, dem die Änderung gehört; danach werden die Branches darüber rebased. Ändert sich der Diff nicht, bleiben bestehende Freigaben beim Rebase erhalten.

gh stack checkout auth-layer   # die Ebene, zu der die Korrektur gehört
git add .
git commit -m "Abgelaufenes Token behandeln"
gh stack rebase --upstack      # setzt die Branches darüber auf diesen Commit
gh stack push                  # pusht die Branches mit --force-with-lease

Diese Regeln gelten für Menschen wie für ein KI-Review-Tool: Beide lesen den Diff der Ebene. Eine Ebene freizugeben heißt nicht, die darunter freizugeben; jeder Pull Request trägt seine eigenen erforderlichen Freigaben und Checks.

Nicht jede Änderung braucht einen Stapel

Ein Stapel ist für Arbeit gedacht, die aufeinander aufbaut und zu groß ist, um sie in einer Sitzung zu prüfen. In diesen Fällen passt ein einzelner Pull Request oder mehrere voneinander unabhängige besser:

• Die Änderung ist klein. Einen Diff zu teilen, der sich in einer Sitzung lesen lässt, beschert dem Reviewer nur zusätzliche Seiten.
• Die Arbeiten bauen nicht aufeinander auf. Ein Stapel ist eine einzige lineare Kette: Jeder Branch hat einen darunter und höchstens einen darüber. Eine unabhängige Korrektur ist ein eigener Pull Request.
• Der Beitrag kommt aus einem Fork. Alle Branches müssen im selben Repository liegen; Stapel über Forks hinweg werden nicht unterstützt.
• CI ist teuer. Jede Ebene lässt ihre eigenen Checks laufen; beschränken Sie teure Jobs zuerst auf bestimmte Ebenen.

In der Dokumentation, die wir am 14. Oktober 2026 gelesen haben, stehen drei weitere Grenzen. GitHub Desktop unterstützt Stapel nicht. Tools, die über die API mergen, müssen auf die asynchrone Merge-API umsteigen. Zu Auto-Merge sagen zwei Seiten Verschiedenes: Die Merge-Dokumentation schreibt, dass es für Stapel nicht unterstützt wird, die Ankündigung vom 6. Oktober, dass es in den kommenden Wochen freigeschaltet wird.

diffox prüft den Diff des Pull Requests, den es bekommt. Weil im Stapel jede Ebene ein eigener Pull Request ist, wird jede einzeln geprüft, und die Feststellungen landen im Pull Request dieser Ebene.