Verwalten einer Mergewarteschlange

Informationen zu Mergewarteschlangen

Eine Mergewarteschlange hilft dabei, die Geschwindigkeit zu erhöhen, indem Pull Request-Merges in einem ausgelasteten Branch automatisiert werden und sichergestellt wird, dass der Branch nie durch inkompatible Änderungen unterbrochen wird.

Die Mergewarteschlange bietet die gleichen Vorteile wie der Branchschutz Aktualität von Branches vor dem Mergen erfordern. Es ist jedoch nicht erforderlich, dass Pull Request-Ersteller*innen ihren Pull Request-Branch aktualisieren und auf den Abschluss der Statusüberprüfungen warten, bevor der Merge versucht wird.

Die Verwendung einer Mergewarteschlange ist besonders nützlich für Branches mit einer relativ hohen Anzahl von Pull Requests, die täglich von vielen verschiedenen Benutzer*innen zusammengeführt werden.

Sobald ein Pull Request alle erforderlichen Prüfungen zum Schutz der Branches bestanden hat, kann eine Benutzerin mit Schreibzugriff auf das Repository diesen Pull Request der Warteschlange hinzufügen. Die Mergewarteschlange stellt sicher, dass die Pull Request-Änderungen alle erforderlichen Statusüberprüfungen bestehen, wenn sie auf die neueste Version des Zielbranch und alle Pull Requests angewendet werden, die sich bereits in der Warteschlange befinden.

Eine Mergewarteschlange kann GitHub Actions oder einen eigenen CI-Anbieter verwenden, um erforderliche Überprüfungen für Pull Requests in einer Mergewarteschlange auszuführen. Weitere Informationen findest du unter Dokumentation zu GitHub Actions.

Weitere Informationen zum Mergen eines Pull Requests mithilfe einer Mergewarteschlange findest du unter Zusammenführen eines Pull Requests mit einer Mergewarteschlange.

Konfigurieren von CI-Workflows (Continuous Integration) für Mergewarteschlangen

Auslösen von Mergegruppenüberprüfungen mit GitHub Actions

Du musst das merge_group-Ereignis verwenden, um deinen GitHub Actions-Workflow auszulösen, wenn ein Pull Request einer Mergewarteschlange hinzugefügt wird.

Ein Workflow, der eine vom Schutz des Zielbranch verlangte Überprüfung meldet, sieht wie folgt aus:

on:
  pull_request:
  merge_group:

Weitere Informationen zum merge_group-Ereignis findest du unter Ereignisse zum Auslösen von Workflows.

Auslösen von Mergegruppenüberprüfungen bei CI-Drittanbietern

Bei CI-Drittanbietern musst du möglicherweise deine CI-Konfiguration aktualisieren, damit sie ausgeführt wird, wenn ein Push für den mit dem speziellen Präfix gh-readonly-queue/{base_branch} beginnenden Branch ausgeführt wird. Dies sind die temporären Branches, die in deinem Namen von einer Mergewarteschlange erstellt werden und ein anderes sha-Element als der Pull Request enthalten.

Verwalten einer Mergewarteschlange

Repositoryadministratoren können eine Mergewarteschlange anfordern, indem sie die Branchschutzeinstellung „Mergewarteschlange anfordern“ in den Schutzregeln für den Basisbranch aktivieren. Weitere Informationen findest du unter Verwalten einer Branchschutzregel.

Nachdem du die Einstellung „Mergewarteschlange erfordern“ aktiviert hast, kannst du auch auf die folgenden Einstellungen zugreifen:

• Mergemethode: Wähle aus, welche Methode du beim Mergen von Pull Requests in der Warteschlange verwenden möchtest: mergen, Rebase ausführen oder squashen.

• Buildparallelität: Die maximale Anzahl der zu sendenden merge_group-Webhooks (zwischen 1 und 100), die die Gesamtanzahl gleichzeitiger CI-Buildvorgänge drosselt. Dies wirkt sich auf die Geschwindigkeit von Merges aus, die eine Mergewarteschlange abschließen kann.

• Nur Pull Requests ohne Fehler mergen: Diese Einstellung bestimmt, wie eine Mergewarteschlange Gruppen zu mergender Pull Requests bildet.

  Aktiviert?	BESCHREIBUNG
  Ja	Alle Pull Requests müssen die erforderlichen Überprüfungen bestehen, damit sie zusammengeführt werden können.
  Nein	Pull Requests, bei denen die erforderlichen Überprüfungen nicht bestanden wurden, können einer Gruppe hinzugefügt werden, solange der letzte Pull Request in der Gruppe die erforderlichen Überprüfungen bestanden hat. Wenn der letzte Pull Request in der Gruppe die erforderlichen Überprüfungen bestanden hat, bedeutet dies, dass die Überprüfungen für die kombinierten Änderungen in der Mergegruppe bestanden wurden. Es kann hilfreich sein, dieses Kontrollkästchen nicht zu aktivieren, wenn zeitweilige Testfehler auftreten, die Warteschlange jedoch nicht durch falsch negative Ergebnisse aufgehalten werden soll.

• Statusüberprüfungstimeout: Wähle aus, wie lange die Warteschlange auf eine CI-Antwort warten soll, bevor sie davon ausgeht, dass die Überprüfungen nicht bestanden wurden.

• Mergegrenzwerte: Wähle die minimale und maximale Anzahl von Pull Requests, die in einer einzelnen Gruppe gemergt werden sollen (zwischen 1 und 100), sowie ein Timeout aus, nach dem die Warteschlange nicht mehr auf Einträge warten und mit weniger als der minimalen Anzahl von Pull Requests mergen soll. Wie viele PRs in einer Gruppe genau enthalten sind, hängt von den Einstellungen einer Mergewarteschlange ab:

  Mergegrenzwert	Anwendungsfall
  Maximale Anzahl der zu mergenden Pull Requests	Du kannst eine maximale Gruppengröße angeben. Dies ist nützlich, wenn Merges mit deinem Basisbranch eine Bereitstellung auslösen und du sicherstellen möchtest, dass nicht zu viele Änderungen gleichzeitig bereitgestellt werden.
  Minimale Anzahl der zu mergenden Pull Requests	Du kannst eine minimale Gruppengröße angeben. Dies ist nützlich, wenn Merges mit deinem Basisbranch einen langwierigen CI-Buildprozess oder -Bereitstellungsprozess auslösen und die folgenden Einträge in der Warteschlange nicht verzögert werden sollen.
  Wartezeit	Du kannst ein Timeout für das Erreichen der minimalen Gruppengröße angeben. Dadurch können kleinere Gruppen zusammengeführt werden, wenn innerhalb des angegebenen Zeitlimits keine PRs mehr in die Warteschlange eingereiht werden.

Funktionsweise von Mergewarteschlangen

Wenn Pull Requests der Mergewarteschlange hinzugefügt werden, stellt die Mergewarteschlange sicher, dass sie in der FIFO-Reihenfolge (First In, First Out) zusammengeführt werden, bei der die erforderlichen Überprüfungen immer bestanden werden.

Mit einer Mergewarteschlange werden temporäre Branches mit einem speziellen Präfix erstellt, um Änderungen in Pull Requests zu überprüfen. Wenn der Mergewarteschlange ein Pull Request hinzugefügt wird, werden die Änderungen im Pull Request in merge_group mit der neuesten Version von base_branch sowie Änderungen von Pull Requests gruppiert, die sich vor ihm in der Warteschlange befinden. GitHub mergt alle diese Änderungen in base_branch, nachdem die für den Branchschutz erforderlichen Überprüfungen von base_branch bestanden wurden.

Weitere Informationen zu Mergemethoden findest du unter Informationen zum Zusammenführen von Pull Requests.

Erfolgreiche CI

Wenn der Mergewarteschlange mehrere Pull Requests hinzugefügt werden und die temporären merge_group-Branches erfolgreiche CI-Ergebnisse aufweisen, werden beide zusammengeführt. Im folgenden Szenario werden der Warteschlange erfolgreich zwei Pull Requests hinzugefügt und mit dem Zielbranch zusammengeführt.

1. Der Benutzer bzw. die Benutzerin fügt der Mergewarteschlange Pull Request 1 hinzu.
2. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-1, der Codeänderungen aus dem Zielbranch und Pull Request 1 enthält. Ein merge_group-Webhookereignis vom Typ checks_requested wird gesendet, und die Mergewarteschlange wartet auf eine Antwort von deinem CI-Anbieter.
3. Der Benutzer bzw. die Benutzerin fügt der Mergewarteschlange Pull Request 2 hinzu.
4. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-2, der Codeänderungen aus dem Zielbranch, Pull Request 1 und Pull Request 2 enthält und Webhooks sendet.
5. Wenn die GitHub-API erfolgreiche CI-Antworten für die merge_group-Branches main/pr-1 und main/pr-2 empfängt, wird der temporäre Branch main/pr-2 mit dem Zielbranch zusammengeführt. Der Zielbranch enthält jetzt beide Änderungen aus Pull Request 1 und 2.

Fehler bei der CI

Wenn ein Pull Request mit der neuesten Version des Zielbranch und den vorhergehenden Änderungen in der Warteschlange gruppiert wurde und die erforderlichen Statusprüfungen fehlgeschlagen sind oder Konflikte mit dem Basisbranch bestehen, wird der Pull Request aus der Warteschlange entfernt. In der Zeitachse des Pull Requests wird angezeigt, warum der Pull Request aus der Warteschlange entfernt wurde.

Im folgenden Szenario wird beschrieben, was geschieht, wenn eine CI einen fehlerhaften Status zu einem Pull Request meldet.

1. Der Benutzer bzw. die Benutzerin fügt der Mergewarteschlange Pull Request 1 hinzu.
2. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-1, der Codeänderungen aus dem Zielbranch und Pull Request 1 enthält. Ein merge_group-Webhookereignis vom Typ checks_requested wird gesendet, und die Mergewarteschlange wartet auf eine Antwort von deinem CI-Anbieter.
3. Der Benutzer bzw. die Benutzerin fügt der Mergewarteschlange Pull Request 2 hinzu.
4. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-2, der Codeänderungen aus dem Zielbranch, Pull Request 1 und Pull Request 2 enthält und Webhooks sendet.
5. Wenn die GitHub-API einen fehlerhaften Status für main/pr-1 empfängt, entfernt die Mergewarteschlange den Pull Request 1 automatisch aus der Mergewarteschlange.
6. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-2, der nur Änderungen aus dem Zielbranch und Pull Request 2 enthält.
7. Wenn die GitHub-API erfolgreiche CI-Antworten für den merge_group-Branch main/pr-2 empfängt, wird der temporäre Branch main/pr-2 mit dem Zielbranch ohne Pull Request 1 zusammengeführt.

Es gibt eine Reihe von Gründen, warum ein Pull Request aus einer Mergewarteschlange entfernt wird:

• Der konfigurierte CI-Dienst meldet Testfehler für eine Mergegruppe.
• Beim Warten auf ein erfolgreiches CI-Ergebnis ist basierend auf der konfigurierten Timeouteinstellung ein Timeout aufgetreten.
• Eine Benutzerin fordert eine Entfernung über die API oder die Schnittstelle der Mergewarteschlange an.
• Fehler beim Branchschutz, der nicht automatisch behoben werden konnte

Springen an den Anfang der Warteschlange

Wenn du einer Mergewarteschlange einen Pull Request hinzufügst, gibt es eine Option, den Pull Request an den Anfang der Warteschlange zu verschieben.

Im folgenden Szenario wird beschrieben, was passiert, wenn Benutzer*innen an den Anfang der Warteschlange springen.

1. Der Benutzer bzw. die Benutzerin fügt der Mergewarteschlange Pull Request 1 hinzu.
2. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-1, der Codeänderungen aus dem Zielbranch und Pull Request 1 enthält. Ein merge_group-Webhookereignis vom Typ checks_requested wird gesendet, und die Mergewarteschlange wartet auf eine Antwort von deinem CI-Anbieter.
3. Der Benutzer bzw. die Benutzerin fügt der Mergewarteschlange Pull Request 2 hinzu.
4. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-2, der Codeänderungen aus dem Zielbranch, Pull Request 1 und Pull Request 2 enthält und Webhooks sendet.
5. Der Benutzer bzw. die Benutzerin fügt Pull Request 3 der Mergewarteschlange mit der Option zum Verschieben an den Anfang hinzu, die zu einer Unterbrechung im Commitdiagramm führt.
6. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-3, der Codeänderungen aus dem Zielbranch und Pull Request 3 enthält und Webhooks sendet.
7. Die Mergewarteschlange erstellt einen temporären Branch mit dem Präfix main/pr-1 und main/pr-2, der Codeänderungen aus Pull Request 3 enthält und Webhooks sendet.

Weiterführende Themen

• Zusammenführen eines Pull Requests mit einer Mergewarteschlange
• Informationen zu geschützten Branches