Règles disponibles pour les ensembles de règles

Vous pouvez créer des ensembles de règles de branche ou balise pour contrôler la façon dont les utilisateurs peuvent interagir avec une sélection de branches et d’étiquettes dans un référentiel. Vous pouvez également créer des ensembles de règles de poussée pour bloquer les poussées vers un référentiel privé ou interne et l'ensemble du réseau de fourches de ce référentiel.

Lorsque vous créez un ensemble de règles, vous pouvez autoriser certains utilisateurs à contourner les règles de l’ensemble de règles. Il peut s’agir d’utilisateurs disposant de certains rôles, d’équipes spécifiques ou d’GitHub Apps.

Pour les jeux de règles de poussée, les autorisations de contournement s'appliquent à un référentiel et à l'ensemble du réseau de fourches du référentiel. Cela signifie que les seuls utilisateurs qui peuvent contourner cet ensemble de règles pour n’importe quel dépôt du réseau de fourche de ce référentiel sont les utilisateurs qui peuvent contourner cet ensemble de règles dans le référentiel racine.

Pour plus d’informations sur la création des ensembles de règles et d’autorisations de contournement, consultez « Création des ensembles de règles pour les référentiels de votre organisation » et « Création d’un ensemble de règles pour un dépôt ».

Limiter les créations

Si cette option est sélectionnée, seuls les utilisateurs disposant d’autorisations de contournement peuvent créer des branches ou des étiquettes dont le nom correspond au modèle que vous spécifiez.

Limiter les mises à jour

Si cette option est sélectionnée, seuls les utilisateurs disposant d’autorisations de contournement peuvent effectuer des poussées vers les branches ou les étiquettes dont le nom correspond au modèle que vous spécifiez.

Limiter les suppressions

Si cette option est sélectionnée, seuls les utilisateurs disposant d’autorisations de contournement peuvent supprimer les branches ou les étiquettes dont le nom correspond au modèle que vous spécifiez. Cette règle est sélectionnée par défaut.

Exiger un historique linéaire

L’application d’un historique de commits linéaire empêche les collaborateurs de pousser les commits de fusion vers les branches ou étiquettes ciblées. Cela signifie que toutes les demandes de tirage fusionnées dans la branche ou l’étiquette doivent utiliser une fusion « squash » ou « rebase ». Un historique de validation strictement linéaire peut aider les équipes à revenir sur des modifications plus facilement. Pour plus d’informations sur les méthodes de fusion, consultez « À propos des fusions de demande de tirage ».

Avant de pouvoir exiger un historique de validation linéaire, votre dépôt doit autoriser une fusion « squash » ou « rebase ». Pour plus d’informations, consultez « Configuration des fusions de demande de tirage ».

Exiger une file d’attente de fusion

Vous pouvez exiger que les fusions soient effectuées avec une file d’attente de fusion au niveau du référentiel. Pour plus d’informations sur les files d’attente de fusion, consultez « Fusion d’une demande de tirage avec une file d’attente de fusion ».

Paramètres supplémentaires

Vous pouvez configurer divers paramètres pour votre règle de file d’attente de fusion.

• Méthode de fusion : méthode à utiliser lors de la fusion des modifications des demandes de tirage (pull request).
• Concurrence de génération : limitez le nombre de demandes de tirage (pull request) en file d’attente demandant des vérifications et des exécutions de workflow en même temps.
  • Ce paramètre contrôle quand la file d’attente de fusion distribue l’événement webhook merge_group.checks_requested, qui déclenche les flux de travail GitHub Actions configurés pour s’exécuter sur merge_group. Pour plus d’informations, consultez « Événements et charges utiles du webhook ».
  • Par exemple, si 5 demandes de tirage (pull request) sont ajoutées à la file d’attente et que le paramètre de concurrence de génération est 3, la file d’attente de fusion distribue l’événement checks_requested pour les 3 premières mises en file d’attente. Lorsqu’il reçoit un résultat pour l’une de ces demandes de tirage (pull request), la file d’attente de fusion distribue l’événement pour la 4ème demande de tirage, et ainsi de suite.
• Taille minimale/maximale du groupe : nombre de demandes de tirage (pull request) qui seront fusionnées dans un groupe.
• Temps d’attente pour respecter la taille minimale du groupe (minutes)  : durée pendant laquelle la file d’attente de fusion attend une fois que la première demande de tirage (pull request) est ajoutée à la file d’attente pour que la taille minimale du groupe soit remplie. Une fois cette durée écoulée, la taille minimale du groupe est ignorée et un groupe plus petit sera fusionné.
• Exiger que toutes les entrées de file d’attente passent les vérifications requises :
  • Lorsque ce paramètre est activé, chaque élément du groupe de fusion doit passer toutes les vérifications requises.
  • Lorsque ce paramètre est désactivé, seule la validation à la tête du groupe de fusion, c’est-à-dire la validation contenant les modifications de toutes les demandes de tirage (pull request) dans le groupe, doit passer ses vérifications requises pour la fusion.
• Délai d’expiration de la vérification d’état (minutes)  : durée maximale laissée à une vérification d'état requise pour remonter une conclusion. Une fois cette durée écoulée, les vérifications qui n’ont pas remonté de conclusion seront supposées avoir échoué

Exiger que les déploiements réussissent avant de fusionner

Vous pouvez exiger que des modifications aient été déployées avec succès dans des environnements spécifiques avant qu’une branche puisse être fusionnée. Par exemple, vous pouvez utiliser cette règle pour vous assurer que les modifications ont été déployées avec succès dans un environnement intermédiaire avant la fusion des modifications dans votre branche par défaut.

Exiger des validations signées

Lorsque vous activez la signature de validation requise sur une branche, des contributeurs et des bots ne peuvent envoyer (push) à la branche que des validations signées et vérifiées. Pour plus d’informations, consultez « À propos de la vérification des signatures de commit ».

Les règles et ensembles de règles de protection des branches se comportent différemment lorsque vous créez une branche : avec les ensembles de règles, seules les validations qui ne sont pas accessibles depuis d’autres branches sont vérifiées, alors qu’avec les règles de protection des branches, les validations signées ne sont pas vérifiées, sauf si vous limitez les envois (push) qui créent des branches correspondantes. Dans les deux cas, lorsque vous mettez à jour une branche, toutes les validations de la plage spécifiée sont vérifiées, même si une validation est accessible à partir d’autres branches.

Avec les deux méthodes, nous utilisons verified_signature? pour confirmer si une validation a une signature valide. Si ce n’est pas le cas, la mise à jour n’est pas acceptée.

Vous pouvez toujours envoyer (push) des validations locales à la branche si elles sont signées et vérifiées. Vous pouvez également fusionner des validations signées et vérifiées dans la branche à l’aide d’une demande de tirage sur GitHub Enterprise Cloud. En revanche, vous ne pouvez pas effectuer de « squash and merge » sur une demande de tirage dans la branche sur GitHub Enterprise Cloud, sauf si vous en êtes l’auteur. Vous pouvez effectuer un « squash » sur des demandes de tirage et les fusionner localement. Pour plus d’informations, consultez « Extraction de demandes de tirage localement ».

Pour plus d’informations sur les méthodes de fusion, consultez « À propos des méthodes de fusion sur GitHub ».

Exiger une demande de tirage avant la fusion

Vous pouvez exiger que toutes les modifications apportées à la branche cible soient associées à une demande de tirage. La demande de tirage n’a pas nécessairement besoin d’être approuvée, mais elle doit être ouverte.

Paramètres supplémentaires

Les administrateurs de dépôts ou les rôles personnalisés avec l’autorisation « modifier les règles de dépôt » peuvent exiger que toutes les demandes de tirage reçoivent un nombre spécifique de révisions d’approbation avant qu’une personne ne fusionne la demande de tirage dans une branche protégée. Vous pouvez demander des révisions d’approbation à des personnes qui ont des autorisations d’écriture sur le dépôt ou à un propriétaire de code désigné.

Si vous activez les révisions requises, les collaborateurs peuvent pousser les modifications vers une branche uniquement via une demande de tirage approuvée par le nombre requis de réviseurs disposant d’autorisations d’écriture.

Si une personne choisit l’option Demander des modifications dans une révision, elle doit approuver la demande de tirage avant que celle-ci puisse être fusionnée. Si un réviseur qui demande des modifications sur une demande de tirage n’est pas disponible, toute personne disposant d’autorisations d’écriture sur le dépôt peut ignorer la révision bloquante.

Même si tous les réviseurs obligatoires ont approuvé une demande de tirage, les collaborateurs ne peuvent pas fusionner la demande de tirage si d’autres demandes de tirage ouvertes ont une branche principale qui pointe vers le même commit avec des révisions en attente ou rejetées. Une personne avec des autorisations d’écriture doit d’abord approuver ou ignorer la révision bloquante sur les autres demandes de tirage.

Si vous le souhaitez, vous pouvez choisir d’ignorer les approbations de demande de tirage obsolètes lorsque des commits sont poussés et affectent le diff dans la demande de tirage. GitHub enregistre l’état du diff au moment où une demande de tirage est approuvée. Cet état représente l’ensemble des modifications approuvées par le réviseur. Si le diff sort de cet état (par exemple, parce qu’un contributeur pousse de nouvelles modifications vers la branche de demande de tirage ou clique sur Mettre à jour la branche, ou parce qu’une demande de tirage associée est fusionnée dans la branche cible), la révision d’approbation est ignorée car considérée comme obsolète et la demande de tirage ne peut pas être fusionnée tant qu’une personne n’approuve pas une nouvelle fois le travail. Pour plus d’informations sur la branche cible, consultez « À propos des demandes de tirage (pull requests) ».

Si vous le souhaitez, vous pouvez choisir d’exiger des révisions des propriétaires de code. Dans ce cas, toute demande de tirage modifiant du contenu avec un propriétaire de code doit être approuvée par celui-ci avant qu’elle puisse être fusionnée dans la branche protégée. Notez que si le code a plusieurs propriétaires, l’approbation de n’importe lequel d’entre eux sera suffisante pour satisfaire à cette exigence. Pour plus d’informations, consultez « À propos des propriétaires de code ».

Si vous le souhaitez, vous pouvez exiger une approbation d’une autre personne que la dernière personne qui effectue une poussée vers une branche avant qu’une demande de tirage puisse être fusionnée. Cela signifie qu’au moins un autre réviseur autorisé approuve les modifications. Par exemple, le « dernier réviseur » peut vérifier que le dernier ensemble de modifications incorpore les commentaires d’autres révisions et n’ajoute pas de nouveau contenu non révisé.

Pour les demandes de tirage complexes qui nécessitent de nombreuses révisions, exiger l’approbation d’une personne autre que la dernière personne qui réalise la poussée peut être un compromis qui évite d’avoir à ignorer toutes les révisions obsolètes : avec cette option, les révisions « obsolètes » ne sont pas ignorées et la demande de tirage reste approuvée tant que quelqu’un d’autre que la personne qui a apporté les modifications les plus récentes l’approuve. Les utilisateurs qui ont déjà révisé une demande de tirage peuvent effectuer une nouvelle approbation après la poussée la plus récente pour répondre à cette exigence. Si vous craignez que les demandes de tirage soient « détournées » (où que du contenu non approuvé soit ajouté aux demandes de tirage approuvées), il est plus sûr d’ignorer les révisions obsolètes.

Si vous le souhaitez, vous pouvez exiger que tous les commentaires sur la demande de tirage soient résolus avant que celle-ci puisse être fusionnée dans une branche. Cela garantit que tous les commentaires ont été traités ou ont fait l’objet d’un accusé de réception avant la fusion.

Exiger la réussite des vérifications d’état avant de fusionner

Les vérifications d’état requises garantissent que tous les tests CI requis ont réussi avant que des collaborateurs puissent apporter des modifications à une branche ou une étiquette ciblée par votre ensemble de règles. Les vérifications d’état requises peuvent être des vérifications ou des états. Pour plus d’informations, consultez « À propos des vérifications d’état ».

Vous pouvez utiliser l’API d’état de commit pour autoriser les services externes à marquer les commits avec un état approprié. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les états de commit ».

Une fois que des vérifications d’état requises sont activées, elles doivent toutes réussir avant que des collaborateurs puissent fusionner des modifications dans la branche ou l’étiquette.

Toute personne ou intégration disposant d’autorisations d’écriture sur un dépôt peut définir l’état de toute vérification d’état dans le dépôt. Toutefois, dans certains cas, vous voudrez peut-être accepter uniquement la vérification d’état d’une GitHub App spécifique. Quand vous ajoutez une règle de vérification d’état requise, vous pouvez sélectionner une application comme source prévue des mises à jour d’état. L’application doit être installée dans le dépôt avec l’autorisation statuses:write, doit avoir récemment soumis une exécution des vérifications et doit être associée à une vérification d’état requise préexistante dans l’ensemble de règles. Si l’état est défini par une autre personne ou intégration, la fusion n’est pas autorisée. Si vous sélectionnez « toute source », vous pouvez toujours vérifier manuellement l’auteur de chaque état, répertorié dans la zone de fusion.

Vous pouvez considérer les vérifications d’état requises comme « lâches » ou « strictes ». Le type de vérification d’état requise que vous choisissez détermine si votre branche doit être à jour avec la branche de base avant de la fusion.

Type de vérification d’état requise	Paramètre	Exigences pour la fusion	Considérations
Strictes	La case à cocher Exiger que les branches soient à jour avant la fusion est activée.	La branche de rubrique doit être à jour avec la branche de base avant la fusion.	Il s’agit du comportement par défaut pour les vérifications d’état requises. D’autres builds peuvent être requises, car vous devez mettre à jour la branche principale une fois que les autres collaborateurs ont mis à jour la branche cible.
Lâches	La case à cocher Exiger que les branches soient à jour avant la fusion n’est pas activée.	La branche ne doit pas être à jour avec la branche de base avant la fusion.	Vous aurez moins de builds requises, car vous n’aurez pas besoin de mettre à jour la branche principale après que d’autres collaborateurs auront fusionné des demandes de tirage. Des vérifications d’état peuvent échouer après que vous avez fusionné votre branche s’il existe des modifications incompatibles avec la branche de base.
Désactivé	La case à cocher Exiger la réussite des vérifications d’état avant de fusionner n’est pas activée.	La branche n’a aucune restriction de fusion.	Si les vérifications d’état requises ne sont pas activées, des collaborateurs peuvent fusionner la branche à tout moment, qu’elle soit ou non à jour avec la branche de base. Cela augmente la possibilité de modifications incompatibles.

Pour obtenir des informations de dépannage, consultez « Résolution des problèmes liés aux vérifications de statut requises ».

Bloquer les poussées forcées

Vous pouvez empêcher les utilisateurs de forcer les poussées vers les branches ou étiquettes ciblées. Cette règle est activée par défaut.

Si quelqu’un force les poussées vers une branche ou une étiquette, les commits sur lesquels les autres collaborateurs ont basé leur travail peuvent être supprimés de l’historique de la branche ou de l’étiquette. Cela peut entraîner des conflits de fusion ou des demandes de tirage endommagées. Une poussée forcée peut également être utilisée pour supprimer des branches ou pointer une branche vers des commits qui n’ont pas été approuvés dans une demande de tirage.

L’activation des poussées forcées ne remplace aucune autre règle. Par exemple, si une branche nécessite un historique de validation linéaire, vous ne pouvez envoyer (push) de force des validations de fusion à cette branche.

Exiger que les flux de travail passent avant la fusion

Les flux de travail des jeux de règles peuvent être configurés au niveau de l'organisation pour exiger que les flux de travail soient transférés avant de fusionner les demandes de tirage. Pour plus d’informations, consultez « Création des ensembles de règles pour les référentiels de votre organisation ».

Pour plus d'informations sur le dépannage des paramètres de configuration du flux de travail des jeux de règles, consultez « Résolution des problèmes de règles ».

Utilisation d’un fichier de flux de travail

Pour utiliser cette règle, commencez par créer un fichier de flux de travail. Le fichier de flux de travail doit se trouver dans un référentiel qui correspond à la visibilité des référentiels dans lesquels vous souhaitez l'exécuter. En clair, un flux de travail public peut s'exécuter sur n'importe quel référentiel de votre organisation, tandis qu'un flux de travail interne ne peut s'exécuter que sur des référentiels internes et privés, et qu'un flux de travail privé ne peut s'exécuter que sur des référentiels privés. Pour plus d’informations, consultez « À propos des workflows ».

Si le fichier de flux de travail se trouve dans un référentiel interne ou dans un référentiel privé et que vous souhaitez utiliser ce flux de travail dans d'autres référentiels de l'organisation, vous devez autoriser l'accès au flux de travail à partir de l'extérieur du référentiel. Pour plus d'informations, reportez-vous à « Autorisation de l'accès aux composants dans un référentiel privé » ou « Permettre l'accès aux composants d'un référentiel privé. »

Lorsque vous ajoutez cette règle à un ensemble de règles, dans les paramètres de votre organisation, vous spécifiez le référentiel source et le flux de travail que vous souhaitez appliquer.

Utilisation du mode « Évaluer » pour les flux de travail d'un ensemble de règles

Si un flux de travail d'un ensemble de règles s'exécute en mode « Évaluer » et passe, vous pouvez mettre le flux de travail de l'ensemble de règles en mode « Actif » et fusionner votre demande de tirage sans déclencher une nouvelle exécution du flux de travail.

Si vous ouvrez une demande de tirage avant d'avoir créé l'ensemble de règles en mode « Évaluer », vous pouvez toujours fusionner la demande de tirage puisque l'ensemble de règles n'est pas appliqué.

Pour plus d’informations sur les états de mise en œuvre, consultez « Création d’un ensemble de règles pour un dépôt ».

Déclencheurs d’événements pris en charge

Les flux de travail des jeux de règles prennent en charge l'utilisation de pull_request, pull_request_target, et d'événements merge_group. Par conséquent, vous devez spécifier un ou plusieurs de ces événements dans la section on: du flux de travail pour que le flux de travail soit exécuté par un jeu de règles.

Tous les filtres que vous spécifiez pour les événements pris en charge sont ignorés, par exemple, branches, branches-ignore, paths, types et ainsi de suite. Le flux de travail n'est déclenché, et est toujours déclenché, que par les types d'activité par défaut des événements pris en charge.

Événement	Types d’activités par défaut
pull_request	opened, synchronize, reopened
pull_request_target	opened, synchronize, reopened
merge_group	checks_requested

Ciblage de branches spécifiques avec votre flux de travail d’ensemble de règles

L'application de cette règle bloquera les poussées directes car les flux de travail de l'ensemble de règles s'exécutent dans le cadre de l'expérience de la demande de tirage et de la file d'attente de fusion. C'est pourquoi vous ne devez pas appliquer cette règle à un ensemble de règles qui cible toutes les branches du référentiel.

Cette règle ne doit être ajoutée qu'aux ensembles de règles qui ciblent des branches où toutes les modifications de la branche sont effectuées par des demandes de tirage.

Restrictions des métadonnées

Les organisations avec un plan GitHub Enterprise peuvent accéder à des règles supplémentaires pour contrôler la façon dont les métadonnées de commit doivent être mises en forme. Vous pouvez utiliser des chaînes littérales ou une syntaxe d’expression régulière pour définir un modèle auquel les métadonnées de commit doivent se conformer. Par exemple, vous pouvez exiger que les messages de commit contiennent un numéro de problème GitHub, ou que le commiteur ou l’auteur ait une adresse e-mail se terminant par @octoorg.com. Vous pouvez également contrôler le format des nouveaux noms de branche et d’étiquette. Pour obtenir une sélection d’expressions régulières utiles pour les métadonnées de commit, consultez « Création d’un ensemble de règles pour un dépôt ».

Si un contributeur tente de mettre à jour une branche ou une étiquette avec un commit qui ne répond pas à vos besoins, le contributeur voit une erreur lui indiquant ce qui ne va pas avec son commit. Cette erreur peut apparaître à la fois dans la ligne de commande, lorsque l’utilisateur effectue une poussée, et sur GitHub.com, lorsque l’utilisateur tente d’effectuer un commit ou de fusionner une demande de tirage. Les commits sont immuables dans Git : une fois qu’un contributeur a créé un commit, il ne peut pas modifier les métadonnées du commit. Il devra donc peut-être effectuer un rebasage pour réécrire son historique de commits avec de nouveaux commits avant de pouvoir contribuer correctement à son travail dans le dépôt.

Les restrictions de métadonnées sont utiles pour appliquer une cohérence entre les commits dans l’historique d’une branche. Cela peut être utile pour appliquer une adhésion aux bonnes pratiques, telles que la spécification Conventional Commits, ou pour intégrer des outils qui s’appuient sur les métadonnées de commit. Par exemple, il est plus facile d’exécuter des scripts basés sur le contenu d’un message de commit si chaque message est conforme à un format prévisible.

Points importants sur les restrictions de métadonnées

Les restrictions de métadonnées bloquent les « mises à jour de référence ». Si un contributeur pousse un travail contenant un commit qui ne répond pas aux exigences, la poussée n’est pas rejetée, mais la branche ou l’étiquette qu’elle cible n’est pas mise à jour. Techniquement, les commits entrent quand même dans votre dépôt : les commits sont « récupérables » (vous pouvez y accéder dans votre dépôt), mais ne sont pas « accessibles » (ils ne sont pas connectés à l’historique d’une branche ou d’une étiquette). Si la poussée du contributeur comprend également du travail sur d’autres branches ou étiquettes, avec des commits qui répondent aux exigences de ces branches ou étiquettes, ces références sont correctement mises à jour.

Les restrictions de métadonnées peuvent augmenter les conflits pour les personnes qui contribuent à un dépôt. En règle générale, si vous imposez des restrictions de métadonnées, vous devez le faire sur un ensemble limité de branches pour éviter d’affecter le travail quotidien des contributeurs. Par exemple, au lieu d’exiger des messages de validation cohérents sur n’importe quelle branche de rubrique sur laquelle un contributeur est susceptible de travailler, vous devez exiger des messages de validation cohérents uniquement sur main, puis exiger des demandes de tirage dans main.

Si vous utilisez des fusions Squash, vous devez savoir que les restrictions de métadonnées sont évaluées avant la fusion, de sorte que toutes les validations sur la demande de tirage doivent répondre aux exigences. Pour les restrictions de métadonnées qui s'appliquent aux e-mails du « committer », le modèle doit également inclure noreply@github.com pour les fusions Squash pour satisfaire à la restriction.

Lorsque vous ajoutez des restrictions de métadonnées à une branche ou une étiquette existante, les règles sont appliquées pour les nouveaux commits poussés vers la branche ou l’étiquette à partir de ce moment-là, mais elles ne sont pas appliquées à l’historique existant de la branche ou de l’étiquette.

Restreindre les chemins d’accès aux fichiers

Empêchez les commit qui incluent des modifications dans les chemins d'accès vers des fichiers spécifiés d'être poussés vers le référentiel.

Vous pouvez utiliser la syntaxe fnmatch pour cela. Par exemple, une restriction ciblant test/demo/**/* empêche toute poussée vers les fichiers ou dossiers du répertoire test/demo/. Une restriction visant test/docs/pushrules.md empêche les poussées spécifiquement vers le fichier pushrules.md dans le répertoire test/docs/. Pour plus d’informations, consultez « Création d’un ensemble de règles pour un dépôt ».

Restreindre la longueur du chemin d'accès du fichier

Empêchez les commits qui incluent des chemins d'accès aux fichiers dépassant une limite de caractères spécifiée d'être poussés vers le référentiel.

Restreindre les extensions de fichier

Empêchez les commits qui incluent des fichiers avec les extensions spécifiées d'être poussés vers le référentiel.

Restreindre la taille de fichier

Empêchez les commit qui dépassent une limite de taille de fichier spécifiée d'être poussés vers le référentiel.