Pull-Anfragegenehmigungen mit CODEOWNERS verwalten

In diesem Leitfaden werden die Struktur, die Syntax und die Implementierung der Funktion CODEOWNERS beschrieben, mit der Sie die Anforderungen für die Genehmigung von Pull Requests (PRs) flexibel steuern können.

Einführung

Mit der Secure Source Manager-Funktion CODEOWNERS werden Dateien in Ihrer Codebasis verwendet, um Genehmiger auf Dateiebene festzulegen. Das bietet eine detailliertere Steuerung als andere Branch-Regeln, da Sie bestimmten Dateien bestimmte Inhaber zuweisen und unabhängige Gruppen von Genehmigern definieren können.

Die Funktion CODEOWNERS bietet die folgenden Möglichkeiten:

  • Definieren Sie Nutzer, die Pull-Anfragen für Dateien, Verzeichnisse und Zweige genehmigen können.
  • Sie können verschiedene Gruppen von Code-Inhabern konfigurieren, um verschiedene Zweige zu schützen.
  • Sorgen Sie dafür, dass Änderungen an Dateien von den entsprechenden Eigentümern überprüft werden.

Code Owner-Überprüfung aktivieren

Um CODEOWNERS-Regeln zu aktivieren und zu erzwingen, müssen Administratoren für den Branch-Schutz die Branchregeln in den Repository-Einstellungen auf Code Owner Review für Pull-Anfragen erforderlich aktualisieren. Wählen Sie diese Option in den Einstellungen für die Branch-Regel aus. Wenn diese Einstellung deaktiviert ist, ignoriert das System CODEOWNERS-Dateien für Zusammenführungen in den Zielbranch. Wenn Sie diese Option auswählen, werden Push- und Merge-Vorgänge für den Branch blockiert, bis Code-Eigentümer die Pull-Anfragen überprüfen und genehmigen.

Speicherort und Vorrang der CODEOWNERS-Datei

Secure Source Manager unterstützt zwei Optionen zum Definieren von CODEOWNERS-Dateien:

  1. Geschachtelte Dateien: CODEOWNERS-Dateien in einem beliebigen Verzeichnis außer im Verzeichnis .securesourcemanager. Verschachtelte CODEOWNERS-Dateien wirken sich nur auf das eigene Verzeichnis (einschließlich Unterverzeichnisse) aus. Dateipfade darin müssen relativ zum Verzeichnis angegeben werden, in dem sich die CODEOWNERS-Datei befindet. Dies ist der empfohlene Ansatz für die meisten Anwendungsfälle.

  2. Einzelne dedizierte Datei: Wenn Sie die CODEOWNERS-Datei von Secure Source Manager von anderen CODEOWNERS-Dateien unterscheiden müssen, die von anderen Tools verwendet werden (z. B. .gitlab/CODEOWNERS), können Sie eine einzelne Datei verwenden, die sich im Stammverzeichnis Ihres Repositorys unter .securesourcemanager/CODEOWNERS befindet. Wenn diese Datei vorhanden ist, ignoriert Secure Source Manager alle anderen CODEOWNERS-Dateien im selben Branch, einschließlich verschachtelter Dateien. Das Verzeichnis .securesourcemanager wird nur im Stammverzeichnis des Repositorys erkannt.

Interaktion mit Pull-Anfragen und Genehmigungen

Wenn eine Pull-Anfrage erstellt wird oder ihr Quellzweig mit neuen Commits aktualisiert wird, verwendet das System nur CODEOWNERS-Dateien aus dem Basiszweig (dem Zweig, in den Sie zusammenführen), um die Genehmigungsanforderungen zu ermitteln. Das System ignoriert Änderungen an CODEOWNERS-Dateien im Push-Code für diese Überprüfung.

CODEOWNERS-Syntax und -Struktur

Eine CODEOWNERS-Datei besteht aus Kommentaren, Regelzeilen und Abschnittsmarkierungen. Kommentare beginnen mit # und werden vom System ignoriert.

Format der Trennlinie

Das Standardformat für eine Regelzeile lautet:

[BRANCH_GLOB] PATH_GLOB [OWNERS...]

Wobei:

  • BRANCH_GLOB: Ein optionales Glob-Muster, das angibt, auf welche Zweige die Regel angewendet wird. Wenn Sie keinen Branch-Glob angeben, gilt die Regel für jeden Branch, in den die Datei CODEOWNERS eingecheckt wird (sofern CODEOWNERS in den Branchregeln des jeweiligen Branches aktiviert ist). Beispiel:

    • main stimmt nur mit dem Zweig main überein.
    • dev-* entspricht Branches, die mit dev- beginnen.
    • *-glob entspricht Branches, die mit -glob enden.
    • my-*-glob stimmt mit Zweigen wie my-feat-glob überein.

  • PATH_GLOB: Ein erforderliches Glob-Muster, das angibt, auf welche Dateipfade die Regel angewendet wird. Die Syntax von Secure Source Manager basiert auf gitignore-Mustern.

    • Wenn ein Muster kein / enthält oder nur als letztes Zeichen, ist es ein Glob, der in jedem Verzeichnis übereinstimmt./
      • *.js stimmt mit JavaScript-Dateien an beliebigen Stellen überein.
      • build/ führt zu Übereinstimmungen mit Verzeichnissen, die build heißen.
    • Wenn ein Muster / an einer anderen Stelle als am Ende enthält, wird es als Pfad relativ zum Speicherort der Datei CODEOWNERS behandelt.
      • docs/* stimmt mit Dateien unter docs/ relativ zur Datei CODEOWNERS überein.
      • /*.js entspricht JavaScript-Dateien im selben Verzeichnis wie die CODEOWNERS-Datei, aber nicht verschachtelten JavaScript-Dateien.
    • Ein Muster, das mit / endet, entspricht nur Verzeichnissen und deren Inhalten rekursiv. Beispiel: build-*/ stimmt mit Verzeichnissen wie build-app/ und build-tool/ überein.
    • Wenn Sie .securesourcemanager/CODEOWNERS verwenden, sind Pfade relativ zum Stammverzeichnis des Repositorys.

  • OWNERS: Eine optionale Liste von E-Mail-Adressen der Inhaber, durch Leerzeichen getrennt. Wenn diese Option nicht angegeben wird, fungiert die Regel als Pfadausschluss.

Filialspezifische Inhaberschaft

Mit dem optionalen Feld BRANCH_GLOB am Anfang einer Regelzeile können Sie branchenspezifische Codeinhaberkontrollen implementieren.

  • Wenn Sie am Anfang der Regel keine BRANCH_GLOB angeben, gilt die Regel für alle Zweige.
  • Das System ignoriert alle Zeilen mit einem Branch-Glob, der nicht mit dem aktuellen Branch übereinstimmt.

Grundlagen der Syntax

  • Feldinterpretation: Felder sind durch Leerzeichen getrennt.
    • Felder mit @ werden als E-Mail-Adressen des Inhabers identifiziert.
    • Wenn einem Feld ohne @ E-Mail-Adressen des Eigentümers vorangestellt sind, wird es als PATH_GLOB behandelt. In *.js user@example.com ist *.js beispielsweise die PATH_GLOB.
    • Wenn zwei Felder ohne @ vor den E‑Mail-Adressen des Eigentümers stehen, ist das erste BRANCH_GLOB und das zweite PATH_GLOB. In main *.js user@example.com ist main beispielsweise BRANCH_GLOB und *.js ist PATH_GLOB.
    • Dasselbe gilt, wenn keine Inhaber angegeben sind: Ein Feld ist PATH_GLOB und zwei Felder sind BRANCH_GLOB PATH_GLOB.
  • Glob-Stil-Syntax: Secure Source Manager verwendet die Standard-Glob-Stil-Syntax (.gitignore-Stil) für Pfadausdrücke.
  • Details zu Platzhalterzeichen:
    • ** entspricht einer beliebigen Zeichenfolge, einschließlich /.
    • * entspricht einer beliebigen Zeichenfolge, mit Ausnahme von /.
    • ? entspricht jedem einzelnen Zeichen, mit Ausnahme von /.
  • Groß-/Kleinschreibung: Bei CODEOWNERS-Dateien wird zwischen Groß- und Kleinschreibung unterschieden.
  • Inhaberidentifizierung: Das System identifiziert Inhaber anhand der E‑Mail-Adresse. Das Zeichen @ kennzeichnet Inhaberfelder.
  • Bei E-Mail-Adressen des Eigentümers müssen nur space und backslash maskiert werden.
  • Reservierte Zeichen: Die folgenden Zeichen sind für das System reserviert. Sie müssen sie in Branch- und Pfadausdrücken mit einem umgekehrten Schrägstrich (\) maskieren: [, ], , @, *, ?, \, {, } und !.
  • Wenn ** mit anderen Zeichen als Schrägstrichen kombiniert wird, wird es vom System als regulärer Platzhalter behandelt. Beispiel: /**/*.py stimmt mit jeder Python-Datei überein, unabhängig von der Tiefe. /**.py wird wie /*.py behandelt und stimmt nur mit Dateien im Stammverzeichnis überein.

Abschnitte für mehrere Genehmigungssätze

Mit [Section]-Zeilen werden Regeln in unabhängige erforderliche Genehmigungen gruppiert. Das ist nützlich, wenn Sie beispielsweise Überprüfungen durch verschiedene Teams wie Sicherheit oder Qualitätssicherung benötigen.

  • Abschnittsdefinition: Verwenden Sie eine Zeile im Format [Section Name] (verwenden Sie einen beliebigen Namen in natürlicher Sprache).
  • Anzahl der Genehmigungen: Ein Abschnitt kann ein optionales Suffix [<approverCount>] enthalten, um eine andere Anzahl von Genehmigungen als 1 anzugeben. Eine Anzahl von 0 bedeutet, dass die Inhaber optional sind. So können Sie beispielsweise Experten für bestimmte Dateien zu Informationszwecken anzeigen, ohne dass eine Überprüfung durch sie erforderlich ist.
  • Abschnittsende: Ein Abschnitt gilt für alle Regeln, die ihm folgen, bis zum Beginn des nächsten Abschnitts.
  • Regeln ohne Abschnitt: Regeln, die vor einer [Section]-Definition stehen, werden vom System als ein einziger Abschnitt behandelt, für den standardmäßig eine Genehmigung erforderlich ist.
  • Konsolidierung: Abschnitte mit demselben Namen (unabhängig von der Groß-/Kleinschreibung) werden vom System als ein einziger einheitlicher Abschnitt behandelt, auch wenn sie in mehreren verschachtelten CODEOWNERS-Dateien enthalten sind. Dabei gelten die standardmäßigen Vorrangregeln.

Pfadausschluss

Wenn Sie bestimmte Pfade aus einer früheren, umfassenderen Klausel ausschließen möchten, legen Sie für den Pfad keine Inhaber fest. Wenn Sie eine Regel ohne Inhaber definieren, entfernt das System alle Inhaber für diesen Pfad, die durch vorherige Regeln festgelegt wurden. Für den Pfad sind dann keine Inhaber genehmigungen erforderlich.

Verzeichnisübereinstimmungen funktionieren nur, wenn sie mit / enden oder der letzte Teil keine Platzhalter enthält.

Beispiel: *.py stimmt nicht mit dem verborgenen Verzeichnis .py/ überein, *.py/ hingegen schon.

Konfliktlösung und Vorrang

Wenn eine .securesourcemanager/CODEOWNERS-Datei vorhanden ist, werden alle anderen CODEOWNERS-Dateien ignoriert. Wenn ein Pfad mit zwei verschiedenen Zeilen im selben Abschnitt übereinstimmt, wird nur die letzte Zeile angewendet. Wenn sich die Zeilen in verschiedenen Abschnitten befinden, werden beide angewendet.

Das System verwendet eine standortbasierte Vorrangregel für verschachtelte Dateien:

  • Regeln in einer tiefer verschachtelten (lokaleren) CODEOWNERS-Datei überschreiben übereinstimmende Regeln in einer weniger tief verschachtelten Datei.
  • Die Datei CODEOWNERS im Stammverzeichnis hat immer die niedrigste Priorität.

Beispiel für eine CODEOWNERS-Datei

Hier sehen Sie eine CODEOWNERS-Beispieldatei, in der die CODEOWNERS-Syntax veranschaulicht wird:

# Un-sectioned rules; 1 approve required from any of owners of last matching line.
# Format: [BRANCH_GLOB] PATH_GLOB [OWNERS...]

# Make repo-admin the owner of all files of the current branch.
*   repo-admin@example.com      # No slash prefix; matches in sub-dirs too.
/**/* repo-admin@example.com      # Slash-prefix equivalent of prior line.

# Match all py files (including sub-dirs). Note repo-admin must be re-added.
*.py  repo-admin@example.com python-owner@example.com

# With repo-admin not included here, repo-admin no longer owns README.
/README.md readme-owner@example.com

/scratchpad.txt             # Can also override a path to have zero owners (path exclusion).

# Branch-specific syntax.
# Note that since un-sectioned rules are independent of sectioned rules,
# the above [Section] rules will still apply to this branch if they
# aren't modified to add e.g. `main ` as a prefix.
dev-* *             # Remove all owners reqs on dev branches.
dev-* /experimental/ exp-owner@example.com   # dev-specific owners.

# Make repo admin own all CODEOWNERS files, regardless of any prior rules.
CODEOWNERS repo-admin@example.com

# Section; 1 approval required *in addition* to owners outside this section.
[Security Team]
/secure-directory/ security-expert@example.com security-reviewer@example.com
/**/*secure\ me* security-expert@example.com security-reviewer@example.com

# Section w/ req approval count of 2 instead of 1.
[Doc Team][2]
/docs doc-expert@example.com doc-reviewer@example.com
*.md doc-expert@example.com doc-reviewer@example.com

Kompatibilität mit anderen Quellcode-Managern

Secure Source Manager bietet eine Syntax, die mit anderen Quellcode-Managern vertraut und portierbar ist. Die CODEOWNERS-Syntax von Secure Source Manager ist mit der CODEOWNERS-Syntax von GitHub und teilweise mit der CODEOWNERS-Syntax von GitLab kompatibel, einschließlich der Anzahl der Genehmigungen für Abschnitte wie [Section Name][2].

Die Secure Source Manager-Implementierung von CODEOWNERS unterstützt die GitLab-Syntax !path für die Pfadnegation nicht. Informationen zur Pfadnegation in Secure Source Manager finden Sie unter Pfadausschluss. Secure Source Manager unterstützt auch keine Standardinhaber in Abschnittsüberschriften, z. B. [Section Name] @owner1 @owner2.

Validierung und Fehlerbehandlung

Wenn Sie eine CODEOWNERS-Datei aufrufen, wird in der Benutzeroberfläche ihr Status angezeigt sowie Warnungen oder Informationen auf Zeilenebene, z. B. Zeilen, die nicht mit diesem Zweig übereinstimmen. Wenn Sie den Mauszeiger auf hervorgehobene Zeilennummern oder Zeilen bewegen, werden zusätzliche Details angezeigt.

Erzwingung

Eine Presubmit-Sicherheitsmaßnahme erzwingt die Syntaxfehlerprüfung für alle Branches, in denen Sie die Branch-Regel für Code-Inhaber aktivieren. So wird verhindert, dass Sie versehentlich fehlerhafte CODEOWNERS-Dateien einchecken.

Syntaxfehlerbehandlung

Vorab-Checks werden nur für Branches ausgeführt, in denen Require Code Owner Review on Pull Requests (Code-Inhaber-Überprüfung für Pull-Anfragen erforderlich) aktiviert ist. Wenn eine syntaktisch ungültige CODEOWNERS-Datei in einen Branch eingecheckt wird und die Code-Eigentümerüberprüfung später für diesen Branch aktiviert wird, werden Fehler vom System ordnungsgemäß behandelt:

  • Zeilen, die nicht in eine Abschnittsdefinition, eine Regelzeile oder ein Kommentarformat geparst werden können, werden vom System ignoriert.
  • Wenn die Anzahl der Genehmigungen negativ ist, wird sie vom System als 0 behandelt.
  • Das System parst und wendet weiterhin alle gültigen Zeilen wie gewohnt an.

Nächste Schritte