Zum Inhalt springen

GitHub Merge Queue: Einrichtung, Workflows und Fallstricke

Zuletzt aktualisiert am

Wenn den ganzen Tag viele Personen in main mergen, kann ein PR, der gestern gegen das damalige main erfolgreich in der CI getestet wurde, heute alles brechen. Eine Merge-Queue verhindert das: Sie testet jeden PR zusammen mit den davor eingereihten PRs und merged nur, wenn dieses kombinierte Ergebnis erfolgreich ist. Dieser Leitfaden erklärt die Funktionsweise, die Einrichtung und die nötigen CI-Anpassungen.

Das Problem, das sie löst

Branch-Schutzregeln können verlangen, dass PRs vor dem Merge "aktuell" sind. Das ist sicher, zwingt aber alle, ihren Branch zu aktualisieren und die CI bei jedem Merge eines anderen Teammitglieds erneut auszuführen, ein Wettlauf, der mit der Teamgröße zunimmt. Ohne diese Regel können zwei PRs, die jeweils für sich allein bestehen, zusammen main brechen, etwa zwei Änderungen an derselben Funktionssignatur in verschiedenen Dateien.

So funktioniert die Queue

  1. Eine Entwicklerin oder ein Entwickler klickt auf "Merge when ready" (oder fügt den PR der Queue hinzu).
  2. GitHub erstellt einen temporären Branch, der den Basis-Branch, die davor eingereihten PRs und diesen PR enthält. Branch-Namen sehen so aus: gh-readonly-queue/main/pr-123-<sha>.
  3. Ihre Workflows werden über das merge_group-Ereignis auf diesem Branch ausgelöst.
  4. Wenn die erforderlichen Prüfungen bestehen, wird der PR gemergt. Schlagen sie fehl, wird der PR aus der Queue entfernt und die dahinterliegenden PRs werden ohne ihn neu aufgebaut.

Entwickler führen die PR-Prüfungen wie bisher aus. Die Queue ergänzt eine zweite, abschließende Prüfung des kombinierten Ergebnisses.

Verfügbarkeit: Laut GitHub-Dokumentation sind Merge-Queues für öffentliche Repositories verfügbar, die einer Organisation gehören, sowie für private Repositories in GitHub Enterprise Cloud. Prüfen Sie die aktuellen Anforderungen an den Tarif in der Dokumentation, bevor Sie Ihre Planung darauf aufbauen.

Schritt 1: Workflows auf merge_group ausführen lassen

Dieser Schritt wird am häufigsten übersehen. Erforderliche Status-Checks in einer Queue werden nur gemeldet, wenn der Workflow auf merge_group auslöst. Tut er das nicht, wartet der eingereihte PR auf Prüfungen, die nie laufen.

on:
  pull_request:
  merge_group:
    types: [checks_requested]

Jeder Workflow, der einen erforderlichen Check bereitstellt, braucht diesen Trigger, auch die schlanken Varianten wie Lint oder ein tests-passed-Zusammenfassungsjob. Seien Sie vorsichtig mit paths-Filtern: Wird ein erforderlicher Check durch einen Pfadfilter übersprungen, wartet die Queue trotzdem auf dessen Meldung. Testen Sie das daher zuerst auf einem Branch mit wenig Aktivität.

Prüfen Sie außerdem actions/checkout. Bei einem merge_group-Lauf ist github.sha der Merge-Commit des temporären Branches, daher holt der Standard-Checkout den richtigen Code. Vermeiden Sie Schritte, die von der Existenz von github.event.pull_request ausgehen; bei merge_group gibt es ihn nicht. Für diffbasierte Logik, etwa betroffene Builds, vergleichen Sie stattdessen mit github.event.merge_group.base_sha.

Schritt 2: In einem Regelsatz oder Branch-Schutz aktivieren

Aktivieren Sie in den Repository-Einstellungen unter Rules (Regelsätze) oder Branches (Branch-Schutz) die Option "Require merge queue" für Ihren Standard-Branch und wählen Sie diese Optionen:

EinstellungWas sie bewirktTypische Wahl
Merge-MethodeMerge, Squash oder Rebase für eingereihte PRsSquash, passend zu Ihrer Historie
Build-ParallelitätWie viele Queue-Einträge gleichzeitig getestet werden3 bis 5
Minimale GruppengrößeKleinste Charge, die gemeinsam gemergt wird1
Maximale GruppengrößeGrößte Charge, die in einem Durchgang gemergt wird3 bis 5 für stark genutzte Repositories
Wartezeit bis zur MindestgrößeWie lange auf das Füllen einer Gruppe gewartet wird5 Minuten oder weniger
Zeitlimit für Status-ChecksEin Queue-Eintrag schlägt fehl, wenn Prüfungen zu lange dauernEtwa das Doppelte Ihrer CI-Laufzeit
Nur nicht fehlschlagende PRs mergenOb ein fehlschlagender PR in einer Gruppe andere blockiertAktivieren

Die Standardwerte sind konservativ. Die Build-Parallelität steuert den Durchsatz: Bei 5 gleichzeitigen Einträgen und einer 10-minütigen CI kann die Queue deutlich schneller mergen als nacheinander, da jeder Eintrag spekulativ auf den vorherigen aufbauend getestet wird.

Schritt 3: Erforderliche Checks abgleichen

Fügen Sie die Checks, die in der Queue durchgesetzt werden sollen, im selben Ruleset als erforderliche Status-Checks für den Queue-Branch hinzu. Verwenden Sie stabile Namen, denn eine Matrix erzeugt Namen, die sich ändern, sobald sich die Matrix ändert. Ein einzelner Zusammenfassungs-Job löst das; siehe Matrix-Builds richtig umsetzen.

Entscheiden Sie, welche Checks Sie doppelt ausführen. Das übliche Muster: Schnelle Checks (Lint, Unit-Tests) laufen sowohl für PRs als auch für die Queue; langsame Checks (vollständige End-to-End-Tests, Multi-OS) laufen nur in der Queue, damit nicht jeder PR deren Kosten trägt. Die Queue wird so zum Ort, an dem sich die Kosten konzentrieren, und das Feedback zu PRs bleibt schnell.

Auswirkungen auf Kosten und Geschwindigkeit

Merge-Queues erzeugen zusätzliche Runs: Jeder eingereihte PR läuft mindestens einmal mehr durch die CI. Mit spekulativen Builds bricht ein Fehler bei einem früheren Eintrag die späteren ab und startet sie neu. Richtwerte:

  • Zusätzliche Minuten pro zusammengeführtem PR entsprechen etwa einem vollständigen CI-Lauf der in der Queue geforderten Checks.
  • Treten Fehler häufig auf, vervielfachen Neustarts diesen Aufwand. Instabile Tests sind die Hauptursache; siehe Umgang mit instabilen Tests.
  • Größere Gruppen (Batching) reduzieren die Anzahl der Runs: Bei einer maximalen Gruppengröße von 5 können sich fünf PRs einen CI-Lauf teilen, allerdings mit schwierigerer Fehlerdiagnose, wenn er fehlschlägt.

Modellieren Sie das mit dem CI-Minuten-Prognosetool: PRs pro Tag x CI-Minuten der Queue x Rate. Wägen Sie dann gegen die Kosten eines defekten main ab, das in der Regel alle blockiert.

Fallstricke

  • Checks starten nie: der merge_group-Trigger fehlt.
  • Übersprungene erforderliche Checks: Ein durch if: übersprungener Job kann als übersprungen gemeldet werden, was in manchen Konfigurationen für erforderliche Checks als bestanden zählt. Verwenden Sie das Zusammenfassungs-Job-Muster mit if: always().
  • Secrets und Berechtigungen: merge_group läuft im Kontext des Repositorys mit normalem Zugriff; prüfen Sie, auf welche Secrets diese Workflows zugreifen.
  • Bots und Abhängigkeitsupdates: Dependabot-PRs funktionieren mit der Queue; aktivieren Sie dafür Auto-Merge, statt manuell zusammenzuführen. Siehe Dependabot einrichten.
  • Erforderliche Reviews und CODEOWNERS gelten weiterhin, bevor ein PR in die Queue aufgenommen werden kann. Siehe CODEOWNERS und Branch-Schutz.
  • Notfall-Fixes: Administratoren können je nach Ruleset die Queue umgehen oder überspringen; legen Sie die Richtlinie vorab fest.

Alternativen

Wenn Sie die Merge-Queue von GitHub nicht nutzen können, bieten Drittanbieter-Tools ein ähnliches Verhalten: Mergify, Aviator, die Queue von Graphite und Bors-artige Bots. Sie arbeiten, indem sie denselben Typ temporärer kombinierter Branches erzeugen. Die oben genannten Punkte, Trigger-Einrichtung und Kosten, gelten für alle.

FAQ

Muss ich die Queue aktivieren, um Auto-Merge zu nutzen?

Nein. Auto-Merge führt zusammen, sobald die Anforderungen erfüllt sind. Ist eine Queue aktiviert, reiht Auto-Merge den PR stattdessen in die Queue ein.

Rebased die Queue meinen PR?

Sie führt den PR auf den temporären Branch zusammen; die endgültige Methode richtet sich nach Ihrer Einstellung für die Merge-Methode. Ihr PR-Branch wird nicht aktualisiert.

Was, wenn die Checks beim PR bestehen, in der Queue aber fehlschlagen?

Der PR wird aus der Queue entfernt. Das bedeutet, dass die Kombination mit anderen Änderungen etwas kaputt gemacht hat, wofür die Queue ja da ist. Aktualisieren Sie den Branch, beheben Sie den Fehler und reihen Sie den PR erneut ein.

Funktioniert das mit erforderlichen Deployments?

Umgebungen können Teil der erforderlichen Checks sein, testen Sie dies jedoch auf einem Branch mit wenig Verkehr, bevor Sie sich darauf verlassen.

Den Effekt messen

Erfassen Sie die Zeit von „bereit zum Zusammenführen“ bis zum Merge sowie die Anzahl der Vorfälle mit defektem main vor und nach der Umstellung. Wenn die CI der Queue der Engpass ist, verkürzt ein schnellerer Runner die Wartezeit für alle: Der Vergleichsmodus von compiler.dev erlaubt es, Ihren Queue-Workflow auf schnelleren Maschinen zu testen und die Kosten pro Lauf zu vergleichen.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen