Gérer les approbations de demande d'extraction avec CODEOWNERS

Ce guide décrit la structure, la syntaxe et l'implémentation de la fonctionnalité CODEOWNERS, qui vous permet de contrôler de manière flexible les exigences d'approbation des demandes d'extraction (PR).

Introduction

La fonctionnalité CODEOWNERS de Secure Source Manager utilise les fichiers de votre codebase pour définir des approbateurs au niveau des fichiers. Cela vous permet de contrôler plus précisément les branches que les autres règles de branche, car vous pouvez attribuer des propriétaires spécifiques à des fichiers spécifiques et définir des ensembles d'approbateurs indépendants.

La fonctionnalité CODEOWNERS offre les possibilités suivantes :

  • Définissez les utilisateurs autorisés à approuver les demandes d'extraction pour les fichiers, les répertoires et les branches.
  • Configurez différents ensembles de propriétaires de code pour protéger différentes branches.
  • Assurez-vous que les modifications apportées aux fichiers sont examinées par les propriétaires désignés.

Activer l'examen par le propriétaire du code

Pour activer et appliquer les règles CODEOWNERS, les administrateurs de la protection des branches doivent mettre à jour les règles de branche dans les paramètres de votre dépôt sur Exiger l'examen du propriétaire du code pour les demandes de pull. Sélectionnez cette option dans les paramètres de la règle de branchement. Si ce paramètre est désactivé, le système ignore les fichiers CODEOWNERS pour les fusions dans la branche cible. Si vous sélectionnez cette option, le système bloque les transferts et les fusions vers la branche jusqu'à ce que les propriétaires du code examinent et approuvent les demandes d'extraction.

Emplacement et priorité du fichier CODEOWNERS

Secure Source Manager propose deux options pour définir les fichiers CODEOWNERS :

  1. Fichiers imbriqués : fichiers CODEOWNERS dans n'importe quel répertoire sauf le répertoire .securesourcemanager. Les fichiers CODEOWNERS imbriqués n'affectent que leur propre répertoire (y compris les sous-répertoires), et les chemins d'accès aux fichiers qu'ils contiennent doivent être spécifiés par rapport au répertoire dans lequel se trouve le fichier CODEOWNERS. Il s'agit de l'approche recommandée pour la plupart des cas d'utilisation.

  2. Fichier dédié unique : si vous devez distinguer le fichier CODEOWNERS de Secure Source Manager des autres fichiers CODEOWNERS utilisés par d'autres outils (par exemple, .gitlab/CODEOWNERS), vous pouvez utiliser un fichier unique situé à l'adresse .securesourcemanager/CODEOWNERS dans la racine de votre dépôt. Si ce fichier existe, Secure Source Manager ignore tous les autres fichiers CODEOWNERS de la même branche, y compris ceux imbriqués. Le répertoire .securesourcemanager n'est reconnu que dans la racine du dépôt.

Interaction avec les demandes d'extraction et les approbations

Lorsqu'une demande d'extraction est créée ou que sa branche source est mise à jour avec de nouveaux commits, le système n'utilise que les fichiers CODEOWNERS de la branche de base (celle dans laquelle vous effectuez la fusion) pour déterminer les exigences d'approbation. Le système ignore les modifications apportées aux fichiers CODEOWNERS dans le code d'envoi pour cette validation.

Syntaxe et structure de CODEOWNERS

Un fichier CODEOWNERS se compose de commentaires, de lignes de règles et de marqueurs de section. Les commentaires commencent par # et sont ignorés par le système.

Format de la ligne de règle

Le format standard d'une ligne de règle est le suivant :

[BRANCH_GLOB] PATH_GLOB [OWNERS...]

Où :

  • BRANCH_GLOB : modèle glob facultatif qui spécifie les branches auxquelles la règle s'applique. Si vous ne spécifiez pas de glob de branche, la règle s'applique à toute branche dans laquelle le fichier CODEOWNERS est enregistré (si la branche a activé CODEOWNERS dans ses règles de branche). Exemple :

    • main ne correspond qu'à la branche main.
    • dev-* correspond aux branches commençant par dev-.
    • *-glob correspond aux branches se terminant par -glob.
    • my-*-glob correspond à des branches telles que my-feat-glob.

  • PATH_GLOB : modèle glob obligatoire qui spécifie les chemins d'accès aux fichiers auxquels la règle s'applique. La syntaxe de Secure Source Manager est basée sur des modèles gitignore.

    • Si un modèle ne contient aucun / ou ne contient que / comme caractère de fin, il s'agit d'un glob qui correspond à n'importe quel répertoire.
      • *.js correspond aux fichiers JavaScript n'importe où.
      • build/ correspond aux répertoires nommés build n'importe où.
    • Si un format contient / ailleurs qu'à la fin, il est traité comme un chemin d'accès relatif à l'emplacement du fichier CODEOWNERS.
      • docs/* correspond aux fichiers sous docs/ par rapport au fichier CODEOWNERS.
      • /*.js correspond aux fichiers JavaScript du même répertoire que le fichier CODEOWNERS, mais pas aux fichiers JavaScript imbriqués.
    • Un modèle se terminant par / ne correspond qu'aux répertoires et à leur contenu de manière récursive. Par exemple, build-*/ correspond aux répertoires tels que build-app/ et build-tool/ n'importe où.
    • Si vous utilisez .securesourcemanager/CODEOWNERS, les chemins sont relatifs à la racine du dépôt.

  • OWNERS : liste facultative d'adresses e-mail de propriétaires, séparées par des espaces. Si elle est omise, cette règle agit comme une exclusion de chemin.

Propriété spécifique à une branche

Le champ BRANCH_GLOB facultatif au début d'une ligne de règle vous permet d'implémenter des contrôles des propriétaires de code spécifiques aux branches.

  • Si vous ne spécifiez pas de BRANCH_GLOB au début de la règle, celle-ci s'applique à toutes les branches.
  • Le système ignore toute ligne avec un glob de branche qui ne correspond pas à la branche actuelle.

Principes de base de la syntaxe

  • Interprétation des champs : les champs sont séparés par des espaces.
    • Les champs contenant @ sont identifiés comme des adresses e-mail de propriétaire.
    • Si un champ sans @ précède les adresses e-mail des propriétaires, il est traité comme PATH_GLOB. Par exemple, dans *.js user@example.com, *.js est le PATH_GLOB.
    • Si deux champs sans @ précèdent les adresses e-mail des propriétaires, le premier est BRANCH_GLOB et le second est PATH_GLOB. Par exemple, dans main *.js user@example.com, main correspond à BRANCH_GLOB et *.js à PATH_GLOB.
    • La même logique s'applique si aucun propriétaire n'est spécifié : un champ est PATH_GLOB et deux champs sont BRANCH_GLOB PATH_GLOB.
  • Syntaxe de style glob : Secure Source Manager utilise la syntaxe standard de style glob (.gitignore) pour les expressions de chemin d'accès.
  • Informations sur les caractères génériques :
    • ** correspond à n'importe quelle séquence de caractères, y compris /.
    • * correspond à n'importe quelle séquence de caractères, à l'exception de /.
    • ? correspond à n'importe quel caractère, à l'exception de /.
  • Sensibilité à la casse : les fichiers CODEOWNERS sont sensibles à la casse.
  • Identification du propriétaire : le système identifie les propriétaires par leur adresse e-mail. Le caractère @ permet de distinguer les champs de propriétaire.
  • Dans les adresses e-mail du propriétaire, seuls space et backslash doivent être échappés.
  • Caractères réservés : le système réserve les caractères suivants. Vous devez les échapper avec une barre oblique inverse (\) dans les expressions de branche et de chemin d'accès : [, ], , @, *, ?, \, {, } et !.
  • Si ** est associé à des caractères non-slash, le système le traite comme un caractère générique normal. Par exemple, /**/*.py correspond à n'importe quel fichier Python en profondeur, tandis que /**.py est traité comme /*.py et ne correspond qu'aux fichiers du répertoire racine.

Sections pour plusieurs ensembles d'approbation

Les règles de groupes de lignes [Section] regroupent les approbations requises indépendantes. Cela peut être utile pour exiger des examens de différentes équipes, par exemple l'équipe de sécurité ou l'équipe QA.

  • Définition de la section : utilisez une ligne au format [Section Name] (utilisez n'importe quel nom en langage naturel).
  • Nombre d'approbations : une section peut inclure un suffixe facultatif [<approverCount>] pour spécifier un nombre d'approbations autre que 1. Un nombre de 0 indique des propriétaires facultatifs. Par exemple, vous pouvez l'utiliser pour afficher des experts sur des fichiers spécifiques à des fins d'information, sans avoir besoin de leur examen.
  • Fin de section : une section s'applique à toutes les règles qui la suivent jusqu'à ce que la section suivante commence.
  • Règles non sectionnées : le système traite les règles qui apparaissent avant toute définition [Section] comme une seule section unifiée, nécessitant une approbation par défaut.
  • Consolidation : le système traite les sections portant le même nom (sans tenir compte de la casse), même dans plusieurs fichiers CODEOWNERS imbriqués, comme une seule section unifiée, en suivant les règles de priorité standards.

Exclusion de chemin d'accès

Pour exclure des chemins d'accès spécifiques d'une clause plus large précédente, définissez le nombre de propriétaires sur zéro pour le chemin d'accès. Si vous définissez une règle sans propriétaire, le système supprime tous les propriétaires de ce chemin définis par les règles précédentes, et le chemin ne nécessite pas l'approbation d'un propriétaire.

Les correspondances de répertoire ne fonctionnent que si elles se terminent par / ou si la dernière partie ne contient aucun caractère générique.

Par exemple, *.py ne correspondra pas à un répertoire caché .py/, mais *.py/ le fera.

Résolution des conflits et priorité

Si un fichier .securesourcemanager/CODEOWNERS existe, tous les autres fichiers CODEOWNERS sont ignorés. Si un chemin d'accès correspond à deux lignes différentes dans la même section, seule la dernière ligne s'appliquera. Si les lignes se trouvent dans des sections différentes, les deux s'appliqueront.

Le système utilise une règle de priorité basée sur l'emplacement pour les fichiers imbriqués :

  • Les règles d'un fichier CODEOWNERS plus imbriqué (plus local) remplacent les règles correspondantes d'un fichier moins imbriqué.
  • Le fichier CODEOWNERS du répertoire racine a toujours la priorité la plus basse.

Exemple de fichier CODEOWNERS

Voici un exemple de fichier CODEOWNERS illustrant la syntaxe CODEOWNERS :

# 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

Compatibilité avec d'autres gestionnaires de code source

Secure Source Manager fournit une syntaxe familière et portable avec d'autres gestionnaires de code source. La syntaxe CODEOWNERS de Secure Source Manager est compatible avec la syntaxe CODEOWNERS de GitHub et partiellement compatible avec la syntaxe CODEOWNERS de GitLab, y compris les nombres d'approbations par section, comme [Section Name][2].

L'implémentation Secure Source Manager de CODEOWNERS n'est pas compatible avec la syntaxe GitLab !path pour la négation de chemin d'accès. Pour en savoir plus sur la négation de chemin dans Secure Source Manager, consultez Exclusion de chemin. Secure Source Manager n'est pas non plus compatible avec les propriétaires par défaut dans les en-têtes de section, par exemple [Section Name] @owner1 @owner2.

Validation et gestion des erreurs

Lorsque vous consultez un fichier CODEOWNERS, l'UI affiche son état, ainsi que des avertissements ou des informations au niveau des lignes (par exemple, les lignes qui ne correspondent pas à cette branche). Vous pouvez pointer sur les numéros ou les lignes mis en surbrillance pour afficher des informations supplémentaires.

Application

Une protection avant l'envoi applique la vérification des erreurs de syntaxe sur toute branche sur laquelle vous activez la règle de branche des propriétaires du code. Cela vous évite d'archiver accidentellement des fichiers CODEOWNERS corrompus.

Gestion des erreurs de syntaxe

Les vérifications avant envoi ne s'exécutent que sur les branches où l'option Exiger une revue du propriétaire du code pour les demandes d'extraction est activée. Si un fichier CODEOWNERS dont la syntaxe n'est pas valide est envoyé à une branche, et que l'examen par le propriétaire du code est activé ultérieurement pour cette branche, le système gère les erreurs de manière fluide :

  • Le système ignore les lignes qui ne peuvent pas être analysées en définition de section, en ligne de règle ou en format de commentaire.
  • Si le nombre d'approbations est négatif, le système le considère comme nul.
  • Le système continue d'analyser et d'appliquer les lignes valides comme d'habitude.

Étapes suivantes