Zum Inhalt springen

Best Practices für CODEOWNERS und Branch Protection

Zuletzt aktualisiert am

CODEOWNERS legt fest, wer welche Dateien prüfen muss. Branch Protection (bzw. Rulesets) legt fest, was erfüllt sein muss, bevor Code in main gelangt. Zusammen sind sie die günstigsten Qualitäts- und Sicherheitskontrollen, die Ihnen zur Verfügung stehen, sofern sie so eingerichtet sind, dass niemand sie umgehen kann. Dieser Leitfaden behandelt die Syntax und die wichtigsten Einstellungen.

So funktioniert CODEOWNERS

Eine CODEOWNERS-Datei ordnet Pfadmuster Benutzern oder Teams zu. GitHub sucht sie in dieser Reihenfolge in .github/, im Repository-Stammverzeichnis und in docs/ und verwendet die erste gefundene Datei. Wenn ein Pull Request passende Dateien ändert, fordert GitHub automatisch eine Prüfung von den aufgeführten Ownern an. Wenn der Branch Schutz eine Prüfung durch Code Owner verlangt, kann der PR ohne Freigabe eines Owners nicht gemergt werden.

# Default owners for everything
*                       @acme/platform

# Frontend
/web/                   @acme/frontend
*.css                   @acme/frontend @acme/design

# Backend and database
/services/api/          @acme/backend
/db/migrations/         @acme/backend @acme/dba

# CI and security-sensitive files
/.github/               @acme/platform @acme/security
/infra/                 @acme/platform
Dockerfile              @acme/platform

Die Regeln laut GitHub-Dokumentation:

  • Das zuletzt passende Muster gewinnt. Ordnen Sie von allgemein zu speziell. Eine Datei, die zwei Zeilen entspricht, übernimmt nur die Owner der späteren Zeile, nicht beide.
  • Muster folgen den Regeln von .gitignore, mit Ausnahmen: Eine Negation mit ! ist nicht möglich, und Zeichenbereiche [ ] werden nicht unterstützt.
  • Owner sind @username, @org/team-name oder eine mit einem Konto verknüpfte E-Mail-Adresse.
  • Owner müssen Schreibzugriff auf das Repository haben, und ein Team muss sichtbar sein und Schreibzugriff besitzen. Andernfalls wird die Zeile ignoriert.
  • Eine Datei mit mehr als 3 MB wird nicht gelesen.
  • Ungültige Zeilen werden in der Fehlerliste der Dateiansicht markiert; prüfen Sie diese nach Änderungen.

Erstellen Sie mit dem CODEOWNERS-Generator eine Ausgangsdatei und lesen Sie sie anschließend so durch, wie es ein Reviewer tun würde.

Teams statt Einzelpersonen verwenden

Einzelpersonen verlassen das Unternehmen, sind im Urlaub und werden zu Engpässen. Weisen Sie Teams zu und lassen Sie GitHub in den Team-Einstellungen über die Review-Zuweisung einzelne Mitglieder auswählen (Round Robin oder Lastverteilung). Aktivieren Sie bei sehr großen Teams die "Automatische Zuweisung", damit nicht alle benachrichtigt werden.

Halten Sie die Zuständigkeiten breit genug, dass für jeden PR immer jemand verfügbar ist, und eng genug, dass sie etwas bedeuten. Eine Datei, für die jeder PR fünf Freigaben braucht, verleitet dazu, Änderungen ungeprüft abzunicken.

Pfade schützen, die Angreifer interessieren

Weisen Sie einem vertrauenswürdigen Team die Zuständigkeit für Folgendes zu:

  • /.github/ und insbesondere /.github/workflows/. Eine Workflow-Änderung kann auf Secrets zugreifen und deployen; siehe GitHub Actions absichern.
  • CODEOWNERS selbst, damit die Regeln nicht von jemandem geändert werden können, der keine Zuständigkeit besitzt.
  • Dependency-Manifeste und Lockfiles, sofern Ihnen die Prüfung der Lieferkette wichtig ist.
  • Infrastruktur-Code, Authentifizierungs- und Abrechnungslogik sowie Migrationen.

Branch Protection oder Rulesets?

Rulesets sind der neuere Mechanismus. Sie lassen sich schichten, über Muster auf viele Branches anwenden, organisationsweit einsetzen, und ihre Bypass-Listen werden protokolliert. Branch-Protection-Regeln sind älter, werden aber weiterhin unterstützt. Richten Sie in jedem Fall die folgenden Einstellungen für main und Release-Branches ein:

EinstellungEmpfehlungWarum
Pull Request vor dem Merge verlangenAktiviertKeine direkten Pushes
Erforderliche Freigaben1, bei sensiblen Repositories 2Review für jede Änderung
Veraltete Freigaben bei neuen Commits verwerfenAktiviertEine Freigabe soll den Code abdecken, der gemergt wird
Review durch Code Owner verlangenAktiviertMacht CODEOWNERS verbindlich
Freigabe des neuesten Pushes verlangenAktiviertDer Autor kann nach der Freigabe keine Commits mehr hinzufügen und sich nicht selbst mergen
Status Checks verlangenAktiviert, mit benannten Pflicht-ChecksCI muss erfolgreich sein
Branches auf aktuellen Stand verlangenAn, oder verwenden Sie eine Merge QueueVermeidet semantische Konflikte
Auflösung von Konversationen erforderlichAktiviertKommentare werden beantwortet
Signierte Commits erforderlichOptionalIn manchen Compliance-Vorgaben erforderlich
Lineare Historie erforderlichOptionalPasst zu Squash- oder Rebase-Merges
Force Pushes und Löschungen blockierenAktiviertHistorie schützen
Umgehung nicht zulassenFür alle aktiv, auch für Administratoren„Administratoren dürfen überschreiben“ wird erfahrungsgemäß im ungünstigsten Moment genutzt

Erforderliche Checks sollten wenige und stabile sein: Tests, Lint, Build und ein Sicherheitsscan. Benennen Sie sie über einen einzelnen Summary-Job, damit das Umbenennen von Matrix-Zellen die Regel nicht bricht; siehe Matrix-Builds richtig umgesetzt. Ein erforderlicher Check, der durch einen paths-Filter übersprungen wird, bleibt dauerhaft ausstehend. Behandeln Sie das daher im Workflow.

Häufige Fehlerquellen vermeiden

  • Code-Owner-Review in einem Repository mit nur einem Maintainer. Der Autor kann seinen eigenen PR nicht genehmigen, ein einzelner Owner ist also blockiert. Fügen Sie einen zweiten Owner hinzu oder verwenden Sie ein Team mit mindestens zwei Mitgliedern.
  • Owner nicht in der Schreibberechtigungsliste des Repositories. Die Zeile wird stillschweigend ignoriert.
  • ** catch-all with a huge team.* Everyone is requested on every PR, so nobody feels responsible.
  • Bots. Dependabot- und Renovate-PRs benötigen ebenfalls Owner, damit sie nicht hängen bleiben. Leiten Sie sie an ein rotierendes Team für Abhängigkeiten weiter und nutzen Sie Auto-Merge für risikoarme Updates. Siehe Dependabot-Einrichtung.
  • Instabile erforderliche Checks. Dann greifen Mitarbeitende zur Administrator-Umgehung. Beheben Sie die Flaky Tests; siehe Umgang mit instabilen Tests.
  • Wachsende Umgehungslisten. Überprüfen Sie sie jedes Quartal.

Dazu gehörende Review-Praktiken

  • Halten Sie PRs klein. Reviewer genehmigen große Diffs oft, ohne sie zu lesen.
  • Fügen Sie eine PR-Vorlage mit einer Checkliste für die riskanten Pfade hinzu.
  • Verfolgen Sie die Review-Dauer; langsame Reviews verlängern die Lead Time, eine der DORA-Metriken.
  • Verlangen Sie Reviews durch Owner für riskante Pfade und nutzen Sie einen schlankeren Prozess für Dokumentation. CODEOWNERS kann das abbilden: Weisen Sie Dokumentation einem breiten Team zu.

Testen

Öffnen Sie nach Regeländerungen einen Test-PR, der jeden geschützten Bereich berührt, und prüfen Sie, ob die richtigen Personen angefragt werden und der Merge-Button blockiert ist. In der Ansicht der CODEOWNERS-Datei zeigt GitHub Syntaxfehler an; beheben Sie diese zuerst.

FAQ

Wo sollte die CODEOWNERS-Datei liegen?

.github/CODEOWNERS ist die übliche Wahl. GitHub liest außerdem das Repository-Root und docs/.

Kann eine Datei mehrere Owner haben?

Ja. Listen Sie mehrere Owner in einer Zeile auf. Jeder von ihnen kann die Code-Owner-Anforderung erfüllen (nicht alle zusammen), sofern Sie mit Rulesets nicht separate Anforderungen anlegen.

Gelten Code Owner auch für den PR-Autor?

Ein Owner, der den PR erstellt hat, kann ihn nicht selbst genehmigen; das muss ein anderer Owner übernehmen.

Benötigt nur der Hauptbranch diesen Schutz?

Schützen Sie jeden Branch, der deployt wird, etwa release/* oder production. Ein Ruleset mit einem Branch-Muster erledigt das an einer Stelle.

Kombinieren Sie dies mit dem Dependabot-Leitfaden, damit Update-PRs einen Owner erhalten. Schnellere erforderliche Checks helfen zusätzlich, den Prozess einzuhalten: Der Vergleichsmodus von compiler.dev zeigt, wie viel schneller Ihre erforderlichen Checks auf schnelleren Runnern laufen.

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

Kostenlos testen