Les personnes que vous choisissez en tant que propriétaires de code doivent disposer d’autorisations d’écriture pour le dépôt. Lorsque le propriétaire du code est une équipe, cette équipe doit être visible et doit disposer d’autorisations d’écriture, même si chaque membre de l’équipe dispose déjà d’autorisations d’écriture directement, par le biais de l’appartenance à l’organisation ou par le biais d’une autre appartenance à l’équipe.
À propos des propriétaires de code
Les propriétaires de code sont automatiquement demandés pour révision lorsqu’une personne ouvre une demande de tirage (pull request) qui modifie du code dont ils sont propriétaires. Les propriétaires de code ne sont pas automatiquement invités à réviser les brouillons de demandes de tirage. Pour plus d’informations sur les brouillons de demande de tirage, consultez « À propos des demandes de tirage (pull requests) ». Lorsque vous marquez un brouillon de demande de tirage comme étant prêt pour révision, les propriétaires de code sont automatiquement avertis. Si vous convertissez une demande de tirage en brouillon, les personnes qui sont déjà abonnées aux notifications ne sont pas automatiquement désabonnées. Pour plus d’informations, consultez « Modification de la phase d’une demande de tirage ».
Lorsqu’une personne disposant d’autorisations d’administrateur ou de propriétaire a activé les révisions requises, elle peut également exiger l’approbation d’un propriétaire de code avant que l’auteur puisse fusionner une demande de tirage dans le dépôt. Pour plus d’informations, consultez « À propos des branches protégées ».
Si un fichier a un propriétaire de code, vous pouvez voir qui est le propriétaire du code avant d’ouvrir une demande de tirage. Dans le dépôt, vous pouvez accéder au fichier et pointer sur pour voir une info-bulle avec les détails de l’appartenance du code.
Emplacement du fichier CODEOWNERS
Pour utiliser un fichier CODEOWNERS, créez un nouveau fichier appelé CODEOWNERS dans le .github/, la racine ou docs/ l’annuaire du référentiel, dans la branche où vous souhaitez ajouter les propriétaires du code. Si des fichiers CODEOWNERS existent dans plusieurs de ces emplacements, GitHub effectue une recherche les concernant dans cet ordre et utilise le premier qu’il trouve.
Chaque fichier CODEOWNERS affecte les propriétaires de code pour une branche unique dans le dépôt. Par conséquent, vous pouvez affecter différents propriétaires de code pour différentes branches, par exemple @octo-org/codeowners-team pour une base de code sur la branche par défaut et @octocat pour un site GitHub Pages sur la branche gh-pages.
Pour que les propriétaires de code reçoivent des demandes de révision, le fichier CODEOWNERS doit se trouver sur la branche de base de la demande de tirage. Par exemple, si vous affectez @octocat en tant que propriétaire de code pour des fichiers .js sur la branche gh-pages de votre dépôt, @octocat recevra des demandes de révision lorsqu’une demande de tirage avec des modifications apportées à des fichiers .js sera ouverte entre la branche principale et gh-pages.
PROPRIÉTAIRES DU CODE et forks
Pour déclencher des demandes de révision, les demandes de tirage (pull requests) utilisent la version de CODEOWNERS de la branche de base de la demande de tirage (pull request). La branche de base est la branche qu’une demande de tirage (pull request) modifiera si la demande de tirage (pull request) est fusionnée.
Si vous créez une demande de tirage (pull request) à partir d’une fork, et que la branche de base se trouve dans le référentiel amont, la demande de tirage utilisera le fichier CODEOWNERS de cette branche dans le référentiel amont. Si la branche de base est une branche de votre fork, alors la demande de tirage (pull request) utilisera le fichier CODEOWNERS de cette branche dans votre fork, mais cela ne déclenchera des demandes de révision que si les propriétaires du code sont ajoutés à votre fork avec un accès write spécifique.
Lorsque vous voyez qui est responsable d’un fichier en survolant , vous verrez des informations sur le fichier CODEOWNERS pour n’importe quelle branche dans n’importe quel référentiel que vous consultez.
Taille des fichiers CODEOWNERS
Les fichiers CODEOWNERS doivent avoir une taille inférieure à 3 Mo. Un fichier CODEOWNERS au-delà de cette limite ne sera pas chargé, ce qui signifie que les informations du propriétaire de code ne seront pas affichées et que les propriétaires de code appropriés ne seront pas invités à réviser les modifications dans une demande de tirage.
Pour réduire la taille de votre fichier CODEOWNERS, utilisez des modèles génériques afin de consolider plusieurs entrées en une entrée unique.
Syntaxe de CODEOWNERS
Avertissement : il existe certaines règles de syntaxe pour les fichiers gitignore qui ne fonctionnent pas dans les fichiers CODEOWNERS :
- L’échappement d’un modèle commençant par
#à l’aide de\afin qu’il soit traité comme un modèle et non comme un commentaire ne fonctionne pas - L’utilisation de
!pour la négation d’un modèle ne fonctionne pas - L’utilisation de
[ ]pour définir une plage de caractères ne fonctionne pas
Un fichier CODEOWNERS utilise un modèle qui suit la plupart des mêmes règles que celles utilisées dans les fichiers gitignore. Le modèle est suivi d’un ou plusieurs noms d’utilisateur ou noms d’équipe GitHub au format @username ou @org/team-name standard. Les utilisateurs et les équipes doivent avoir un accès write explicite au dépôt, même si les membres de l’équipe ont déjà un accès.
Si vous souhaitez mettre en correspondance plusieurs propriétaires de code avec le même modèle, tous les propriétaires de code doivent se trouver sur la même ligne. Si les propriétaires de code ne sont pas sur la même ligne, le modèle met uniquement en correspondance le dernier propriétaire de code mentionné.
Vous pouvez également faire référence à un utilisateur par une adresse e-mail qui a été ajoutée à son compte, par exemple user@example.com.
Les chemins CODEOWNERS respectent la casse, car GitHub utilise un système de fichiers qui respecte la casse. Les fichiers CODEOWNERS étant évalués par GitHub, même les systèmes qui ne respectent pas la casse (par exemple macOS) doivent utiliser des chemins et des fichiers dont la casse est correcte dans le fichier CODEOWNERS.
Si une ligne de votre fichier CODEOWNERS contient une syntaxe non valide, cette ligne est ignorée. Lorsque vous accédez au fichier CODEOWNERS dans votre dépôt, vous pouvez voir toutes les erreurs mises en surbrillance. Une liste d’erreurs dans le fichier CODEOWNERS d’un dépôt est également accessible via l’API. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les référentiels ».
Si vous spécifiez un utilisateur ou une équipe qui n’existe pas ou n’a pas d’accès suffisant, un propriétaire de code ne sera pas affecté.
Exemple de fichier CODEOWNERS
# This is a comment.
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @global-owner1 and @global-owner2 will be requested for
# review when someone opens a pull request.
* @global-owner1 @global-owner2
# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
*.js @js-owner #This is an inline comment.
# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
*.go docs@example.com
# Teams can be specified as code owners as well. Teams should
# be identified in the format @org/team-name. Teams must have
# explicit write access to the repository. In this example,
# the octocats team in the octo-org organization owns all .txt files.
*.txt @octo-org/octocats
# In this example, @doctocat owns any files in the build/logs
# directory at the root of the repository and any of its
# subdirectories.
/build/logs/ @doctocat
# The `docs/*` pattern will match files like
# `docs/getting-started.md` but not further nested files like
# `docs/build-app/troubleshooting.md`.
docs/* docs@example.com
# In this example, @octocat owns any file in an apps directory
# anywhere in your repository.
apps/ @octocat
# In this example, @doctocat owns any file in the `/docs`
# directory in the root of your repository and any of its
# subdirectories.
/docs/ @doctocat
# In this example, any change inside the `/scripts` directory
# will require approval from @doctocat or @octocat.
/scripts/ @doctocat @octocat
# In this example, @octocat owns any file in a `/logs` directory such as
# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes
# in a `/logs` directory will require approval from @octocat.
**/logs @octocat
# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as its owners are left empty. Without an owner, changes
# to `apps/github` can be made with the approval of any user who has
# write access to the repository.
/apps/ @octocat
/apps/github
# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as this subdirectory has its own owner @doctocat
/apps/ @octocat
/apps/github @doctocat
CODEOWNERS et protection de branche
Les propriétaires de référentiels peuvent mettre à jour des règles de protection de branche pour s'assurer que le code modifié est révisé par les propriétaires des fichiers modifiés. Modifiez votre règle de protection de branche et activez l'option « Exiger une révision des propriétaires de code. » Pour plus d’informations, consultez « À propos des branches protégées ».
Remarque : lorsque des révisions de propriétaire de code sont requises, une approbation de l’un des propriétaires suffit pour répondre à cette exigence. Par exemple, supposons que votre fichier CODEOWNERS contient la ligne suivante :
*.js @global-owner1 @global-owner2
Cela signifie que les modifications apportées aux fichiers JavaScript peuvent être approuvées par @global-owner1 , ou @global-owner2 ; l’approbation des deux n’est pas nécessaire.
Pour protéger complètement un référentiel contre les modifications non autorisées, vous devez également définir un propriétaire pour le fichier CODEOWNERS lui-même. La méthode la plus sécurisée consiste à définir un fichier CODEOWNERS dans le répertoire .github du dépôt et à définir le propriétaire du dépôt en tant que propriétaire du fichier CODEOWNERS (/.github/CODEOWNERS @owner_username) ou du répertoire entier (/.github/ @owner_username).
En guise d’alternative aux règles de protection de branche ou aux règles de protection des balises, vous pouvez créer des ensembles de règles. Les ensembles de règles présentent quelques avantages par rapport aux règles de protection des branches et des balises, telles que les états et une meilleure détectabilité sans nécessiter d’accès administrateur. Vous pouvez également appliquer plusieurs ensembles de règles en même temps. Pour plus d’informations, consultez « À propos des ensembles de règles ».