Informationen zu geschützten Branches

Informationen zu Branchschutzregeln

Durch das Erstellen von Branchschutzregeln kannst du bestimmte Workflows oder Anforderungen erzwingen, bevor eine Projektmitarbeiterin Änderungen an einen Branch in deinem Repository pushen kann (einschließlich des Mergens eines Pull Requests in den Branch). Akteure können nur Umgehungslisten hinzugefügt werden, wenn das Repository zu einer Organisation gehört.

Standardmäßig deaktiviert jede Branchschutzregel erzwungene Pushes an die übereinstimmenden Branches und verhindert, dass die übereinstimmenden Branches gelöscht werden. Du kannst diese Einschränkungen optional deaktivieren und zusätzliche Branchschutzeinstellungen aktivieren.

Standardmäßig gelten die Einschränkungen einer Branchschutzregel nicht für Personen mit Administratorrechten für das Repository oder für benutzerdefinierte Rollen mit der Berechtigung "Branchschutz umgehen". Optional kannst du die Einschränkungen auch auf Administratoren und Rollen mit der Berechtigung zum Umgehen des Branchschutzes anwenden. Weitere Informationen findest du unter Verwalten benutzerdefinierter Repositoryrollen für eine Organisation.

Du kannst eine Branchschutzregel in einem Repository für einen bestimmten Branch, für alle Branches oder für solche Branches erstellen, die mit einem Namensmuster übereinstimmen, das du mithilfe der fnmatch-Syntax angibst. Um beispielsweise alle Branches zu schützen, die das Wort release enthalten, kannst du eine Branchregel für *release* erstellen. Weitere Informationen zu Branchnamensmustern findest du unter Verwalten einer Branchschutzregel.

Du kannst einen Pull Request konfigurieren, um automatisch zusammenzuführen, wenn alle Zusammenführungsanforderungen erfüllt sind. Weitere Informationen findest du unter Automatisches Zusammenführen eines Pull Requests.

Informationen zu Branchschutzeinstellungen

Für jede Branchschutzregel kannst du die folgenden Einstellungen aktivieren oder deaktivieren.

• Erfordern von Pull-Request-Reviews vor dem Mergen
• Erfordern von Statusüberprüfungen vor dem Mergen
• Erfordern der Klärung von Konversationen vor dem Mergen
• Erfordern signierter Commits
• Erfordern eines linearen Verlaufs
• Erzwingen von Mergewarteschlangen
• Anfordern erfolgreicher Bereitstellungen vor dem Mergen
• Branch sperren
• Umgehung der oben genannten Einstellungen nicht zulassen
• Einschränken der Berechtigungen zum Pushen an übereinstimmende Branches
• Erlauben erzwungener Pushes
• Zulassen von Löschvorgängen

Weitere Informationen zum Einrichten des Branchschutzes findest du unter Verwalten einer Branchschutzregel.

Erfordern von Pull-Request-Reviews vor dem Mergen

Repositoryadministrator*innen oder benutzerdefinierte Rollen mit der Berechtigung „Repositoryregeln bearbeiten“ können verlangen, dass alle Pull Requests eine bestimmte Anzahl genehmigender Reviews erhalten sollen, bevor jemand den Pull Request in einem geschützten Branch zusammenführt. Du kannst die Genehmigung von Bewertungen von Personen mit Schreibberechtigungen im Repository oder von einem bestimmten Codebesitzer anfordern.

Wenn du erforderliche Reviews aktivierst, können Projektmitarbeiterinnen Änderungen nur an einen geschützten Branch über einen Pull Request pushen, der von der erforderlichen Anzahl von Reviewerinnen mit Schreibberechtigungen genehmigt wurde.

Wenn eine Person mit Administratorberechtigungen bei einem Review auf die Option Änderungen anfordern klickt, muss diese Person den Pull Request genehmigen, bevor der Pull Request gemergt werden kann. Wenn Reviewerinnen, die Änderungen an einem Pull Request anfordern, der nicht verfügbar ist, können alle Benutzerinnen mit Schreibberechtigungen für das Repository den blockierenden Review verwerfen.

Selbst nachdem alle erforderlichen Reviewer einen Pull Request genehmigt haben, können Mitarbeiter den Pull Request nicht mergen, wenn andere offene Pull Requests mit einem HEAD-Branch vorhanden sind, der auf denselben Commit mit ausstehenden oder abgelehnten Reviews verweist. Zuerst muss eine Person mit Schreibberechtigungen den blockierenden Review für den anderen Pull Request genehmigen oder schließen.

Wenn eine Projektmitarbeiterin versucht, einen Pull Request mit ausstehenden oder abgelehnten Reviews in den geschützten Branch zu mergen, wird eine Fehlermeldung ausgegeben.

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Changes have been requested.

Optional kannst du veraltete Pull Request-Genehmigungen verwerfen, wenn Commits gepusht werden, die sich auf den diff (Unterschied) im Pull Request auswirken. GitHub zeichnet den Status des diff zu dem Zeitpunkt auf, zu dem ein Pull Request genehmigt wird. Dieser Zustand stellt die Änderungen dar, die der Reviewer genehmigt hat. Wenn sich der diff von diesem Zustand ändert (z. B. weil eine Mitwirkender neue Änderungen an den Pull Request-Branch pusht oder auf Branch aktualisieren klickt oder weil ein verwandter Pull Request im Zielbranch zusammengeführt wird), wird die genehmigende Überprüfung als veraltet geschlossen, und der Pull Request kann erst zusammengeführt werden, wenn jemand die Arbeit erneut genehmigt. Weitere Informationen zum Basisbranch findest du unter Informationen zu Pull Requests.

Optional kannst du die Berechtigung zum Verwerfen von Pull-Request-Reviews für bestimmte Personen oder Teams einschränken. Weitere Informationen findest du unter Einen Pull-Request-Review ablehnen.

Optional kannst du Reviews von Codebesitzerinnen anfordern. In diesem Fall muss jeder Pull Request, der sich auf Code mit Codebesitzerinnen auswirkt, von diesen Codebesitzer*innen genehmigt werden, bevor der Pull Request in den geschützten Branch gemergt werden kann.

Optional kannst du anfordern, dass der letzte überprüfbare Push von einer anderen Person als der Person genehmigt werden muss, die ihn gepusht hat. Dies bedeutet, dass mindestens eine anderer autorisierter Reviewerin Änderungen genehmigt hat. Beispielsweise kann der bzw. die „letzte Reviewer*in“ überprüfen, ob die zuletzt vorgenommenen Änderungen Feedback aus anderen Reviews enthalten, und fügt keine neuen, nicht überprüften Inhalte hinzu.

Bei komplexen Pull Requests, die viele Reviews erfordern, kann die Anforderung einer Genehmigung von einer anderen Person als der letzten Person, die für den Push verantwortlich war, ein Kompromiss sein, der es nicht notwendig macht, alle veralteten Reviews zu verwerfen. Mit dieser Option werden „veraltete“ Reviews nicht verworfen, und der Pull Request verbleibt im genehmigten Status, bis eine andere Person als die Person, die die letzten Änderungen durchgeführt hat, ihn genehmigt. Benutzer, die einen Pull Request bereits überprüft haben, können ihn nach dem letzten Push erneut genehmigen, um diese Anforderung zu erfüllen. Wenn du Bedenken hast, dass Pull Request „gekapert“ werden (also nicht genehmigter Inhalt zu genehmigten Pull Requests hinzugefügt wird), ist es sicherer, die veralteten Reviews zu verwerfen.

Erfordern von Statusüberprüfungen vor dem Mergen

Mithilfe von erforderlichen Statuschecks wird sichergestellt, dass alle erforderlichen CI-Tests bestanden oder übersprungen werden, bevor Projektmitarbeiter Änderungen an einem geschützten Branch vornehmen können. Bei erforderlichen Statuschecks kann es sich um Überprüfungen oder Status handeln. Weitere Informationen findest du unter Informationen zu Statuschecks.

Du kannst die Commitstatus-API verwenden, um externen Diensten das Markieren von Commits mit einem geeigneten Status zu ermöglichen. Weitere Informationen findest du unter REST-API-Endpunkte für Commitstatus.

Nach der Aktivierung erforderlicher Statusüberprüfungen müssen alle erforderlichen Statusüberprüfungen durchlaufen werden, bevor Projektmitarbeiter*innen Änderungen in den geschützten Branch mergen können. Nachdem alle erforderlichen Statuschecks durchlaufen sind, müssen alle Commits entweder in einen anderen Branch übertragen und dann zusammengeführt oder direkt in den geschützten Branch übertragen werden.

Jede Person oder Integration mit Schreibberechtigungen für ein Repository kann den Status einer Statusüberprüfung im Repository festlegen, aber in manchen Fällen solltest du vielleicht nur eine Statusüberprüfung durch eine bestimmte GitHub App zulassen. Wenn du eine erforderliche Statusüberprüfung hinzufügst, kannst du eine App auswählen, die diese Überprüfung kürzlich als erwartete Quelle von Statusupdates festgelegt hat. Wenn der Status von einer anderen Person oder Integration festgelegt wird, ist das Mergen nicht zulässig. Wenn du „Beliebige Quelle“ auswählst, kannst du die Autor*innen jedes Status weiterhin manuell überprüfen (im Mergefeld aufgeführt).

Du kannst die erforderlichen Statusprüfungen entweder als "loose" (locker) oder als "strict" (streng) einrichten. Die Art der erforderlichen Statuschecks bestimmt, ob dein Branch vor dem Zusammenführen auf dem aktuellen Stand mit dem Basisbranch sein muss.

Art des erforderlichen Statuschecks	Einstellung	Merge-Anforderungen	Überlegungen
Strict	Das Kontrollkästchen Aktualität von Branches vor dem Mergen erfordern ist aktiviert.	Der Branch muss vor dem Mergen auf dem Stand des Basisbranchs sein.	Dies ist das Standardverhalten für erforderliche Statuschecks. Weitere Builds können erforderlich sein, da du den Hauptbranch auf den neuesten Stand bringen musst, nachdem andere Projektmitarbeiter*innen den Zielbranch aktualisiert haben.
Locker	Das Kontrollkästchen Aktualität von Branches vor dem Mergen erfordern ist nicht aktiviert.	Der Branch muss vor dem Mergen nicht auf dem Stand des Basisbranchs sein.	Es sind weniger Builds erforderlich, da du den Head-Branch nicht auf den neuesten Stand bringen musst, nachdem andere Mitarbeiter Pull Requests überführt haben. Statuschecks schlagen nach dem Zusammenführen deines Branches möglicherweise fehl, wenn inkompatible Änderungen am Basisbranch vorliegen.
Deaktiviert	Das Kontrollkästchen Durchlaufen von Statusüberprüfungen vor dem Mergen erfordern ist nicht aktiviert.	Für den Branch gelten keine Merge-Einschränkungen.	Wenn die erforderlichen Statuschecks nicht aktiviert sind, können Mitarbeiter den Branch unabhängig von seinem Stand gegenüber dem Basisbranch jederzeit zusammenführen. Die Wahrscheinlich inkompatibler Änderungen erhöht sich dadurch jedoch.

Informationen zur Problembehandlung findest du unter Fehlerbehebung von erforderlichen Statuschecks.

Erfordern der Klärung von Konversationen vor dem Mergen

Alle Kommentare zum Pull Request müssen geklärt sein, bevor dieser in einen geschützten Branch gemergt werden kann. Auf diese Weise wird sichergestellt, dass vor dem Mergen alle Kommentare geklärt oder berücksichtigt wurden.

Erfordern signierter Commits

Wenn du die erforderliche Commitsignierung für einen Branch aktivierst, können Mitwirkende und Bots nur Commits pushen, die für den Branch signiert und verifiziert wurden. Weitere Informationen findest du unter Informationen zur Verifizierung einer Commit-Signatur.

Du kannst jederzeit lokale Commits zum Branch übertragen, wenn die Commits signiert und verifiziert sind. Du kannst signierte und verifizierte Commits auch mithilfe eines Pull Requests auf GitHub in den Branch mergen. Du kannst jedoch keinen Pull Request in den Branch auf GitHub squashen und mergen, es sei denn, du bist Autor*in des Pull Requests. Du kannst Pull Requests lokal squashen und mergen. Weitere Informationen findest du unter Pull Requests lokal auschecken.

Weitere Informationen zu Mergemethoden findest du unter Informationen zu Merge-Methoden auf GitHub.

Erfordern eines linearen Verlaufs

Durch das Erzwingen eines linearen Commitverlaufs wird verhindert, dass Projektmitarbeiter*innen Mergecommits an den Branch pushen. Dies bedeutet, dass alle Pull Requests, die in den geschützten Branch zusammengeführt sind, einen Squash-Merge oder einen Rebase-Merge verwenden müssen. Ein streng linearer Commitverlauf kann Teams dabei helfen, Änderungen einfacher rückgängig zu machen. Weitere Informationen zu Mergemethoden findest du unter Informationen zum Zusammenführen von Pull Requests.

Bevor du einen linearen Commit-Verlauf verlangen kannst, muss dein Repository Squash-Merge oder Rebase-Merge erlauben. Weitere Informationen findest du unter Pull-Request-Merges konfigurieren.

Erfordern von 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 GitHub Actions-Dokumentation.

GitHub mergt den Pull Request gemäß der im Branchschutz konfigurierten Mergestrategie, sobald alle erforderlichen CI-Überprüfungen mit Erfolg durchgeführt wurden. Weitere Informationen zu Mergewarteschlangen findest du unter Verwalten einer Mergewarteschlange.

Erfordern erfolgreicher Bereitstellungen vor dem Mergen

Du kannst festlegen, dass Änderungen erfolgreich in bestimmten Umgebungen bereitgestellt werden müssen, bevor ein Branch gemergt werden kann. Du kannst diese Regel beispielsweise verwenden, um sicherzustellen, dass Änderungen erfolgreich in einer Stagingumgebung bereitgestellt werden, bevor die Änderungen in deinen Standardbranch gemergt werden.

Sperren eines Branches

Durch das Sperren eines Branches wird dieser schreibgeschützt, sodass keine Commits an den Branch durchgeführt werden können. Gesperrte Branches können auch nicht gelöscht werden.

Standardmäßig unterstützt ein geforktes Repository keine Synchronisierung mit dem vorgelagerten Repository. Du kannst Forksynchronisierung zulassen aktivieren, um Änderungen aus dem vorgelagerten Repository abzurufen und gleichzeitig andere Beiträge zur Kopie des Branches zu verhindern.

Umgehung der oben genannten Einstellungen nicht zulassen

Standardmäßig gelten die Einschränkungen einer Branchschutzregel nicht für Personen mit Administratorrechten für das Repository oder für benutzerdefinierte Rollen mit der Berechtigung zum Umgehen des Branchschutzes in einem Repository.

Du kannst diese Einstellung aktivieren, um die Einschränkungen auch auf Administratoren und Rollen mit der Berechtigung zum Umgehen des Branchschutzes anzuwenden. Weitere Informationen findest du unter Verwalten benutzerdefinierter Repositoryrollen für eine Organisation.

Einschränken der Berechtigungen zum Pushen an übereinstimmende Branches

Du kannst Brancheinschränkungen in öffentlichen Repositorys im Besitz einer GitHub Free-Organisation sowie in allen Repositorys im Besitz einer Organisation mit GitHub Team oder GitHub Enterprise Cloud aktivieren.

Wenn du Brancheinschränkungen aktivierst, können nur Benutzerinnen, Teams oder Apps mit den erforderlichen Berechtigungen an den geschützten Branch pushen. Du kannst die Benutzerinnen, Teams oder Apps mit Pushzugriff auf einen geschützten Branch in den Einstellungen für den geschützten Branch anzeigen und bearbeiten. Wenn Statusüberprüfungen erforderlich sind, werden die Personen, Teams und Apps, die die Berechtigung haben, in einen geschützten Branch zu pushen, trotzdem am Mergen in diesen Branch gehindert, wenn die erforderlichen Überprüfungen fehlschlagen. Personen, Teams und Apps, die über die Berechtigung zum Pushen an einen geschützten Branch verfügen, müssen weiterhin einen Pull Request erstellen, wenn Pull Requests erforderlich sind.

Optional kannst du die gleichen Einschränkungen auch auf die Erstellung von Branches anwenden, die der Regel entsprechen. Wenn du z. B. eine Regel erstellst, die es nur einem bestimmten Team erlaubt, in Branches zu pushen, die das Wort release enthalten, können nur Mitglieder dieses Teams einen neuen Branch erstellen, der das Wort release enthält.

Du kannst nur Benutzern, Teams oder installierten GitHub Apps mit Schreibzugriff auf ein Repository den Pushzugriff auf einen geschützten Branch oder die Berechtigung zum Erstellen eines entsprechenden Branches erteilen. Personen und Apps mit Administratorberechtigungen in einem Repository können immer Pushs in einen geschützten Branch ausführen oder einen entsprechenden Branch erstellen.

Erlauben erzwungener Pushes

GitHub blockiert standardmäßig erzwungene Pushes an alle geschützten Branches. Wenn du erzwungene Pushes an einen geschützten Branch aktivierst, kannst du eine von zwei Gruppen auswählen, die Pushes erzwingen können:

1. Jedem, der mindestens über Schreibberechtigungen für das Repository verfügt, das erzwungene Pushen an den Branch erlauben (einschließlich Benutzer*innen mit Administratorberechtigungen)
2. Nur bestimmten Personen oder Teams das erzwungene Pushen an den Branch erlauben

Wenn jemand Pushvorgänge auf einen Branch erzwingt, bedeutet der erzwungene Push möglicherweise, dass Commits, auf denen andere Mitarbeiterinnen ihre Arbeit aufgebaut haben, aus dem Verlauf des Branchs entfernt werden. Bei Benutzerinnen können Mergekonflikte oder beschädigte Pull Requests auftreten. Ein erzwungener Push kann auch zum Löschen von Branchs oder zum Verweisen eines Branchs auf Commits verwendet werden, die in einem Pull Request nicht genehmigt wurden.

Das Aktivieren erzwungener Pushes wird keine anderen Branch-Schutzregeln überschreiben. Wenn ein Branch beispielsweise einen linearen Commit-Verlauf verlangt, kannst du keine Merge-Commit-Pushes zu diesem Branch erzwingen.

Zulassen von Löschvorgängen

Standardmäßig kannst du einen geschützten Branch nicht löschen. Wenn du das Löschen eines geschützten Branchs aktivierst, können alle Benutzer*innen den Branch löschen, die mindestens über Schreibberechtigungen für das Repository verfügen.