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.
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 plus d’informations sur la création des ensembles de règles et d’autorisations de contournement, consultez « 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 que les déploiements réussissent avant de fusionner
Note
Cette règle n’est pas disponible pour les ensembles de règles créés au niveau de l’organisation.
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 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.
Note
Si un collaborateur envoie (push) une validation non signée à une branche qui exige des signatures de validation, ce collaborateur devra rebaser la validation pour inclure une signature vérifiée, puis effectuer un envoi (push) forcé de la validation réécrite à la branche.
Vous pouvez toujours envoyer (push) des validations locales à la branche si elles sont signées et vérifiées. Toutefois, vous ne pouvez pas fusionner des demandes de tirage dans la branche sur GitHub Enterprise Server. Vous pouvez les fusionner localement. Pour plus d’informations, consultez « Extraction de demandes de tirage localement ».
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
Note
Si vous sélectionnez Ignorer les approbations de demandes de tirage obsolètes lorsque de nouveaux commits sont poussés et/ou Demander l’approbation de la poussée révisable la plus récente, la création manuelle du commit de fusion pour une demande de tirage (pull request) et sa poussée (push) directement vers une branche protégée échouent, sauf si le contenu de la fusion correspond exactement à la fusion générée par GitHub pour la demande de tirage.
En outre, avec ces paramètres, l’approbation des révisions est ignorée comme obsolète si la base de fusion introduit de nouvelles modifications après l’envoi de la révision. La base de fusion est le commit qui est le dernier ancêtre commun entre la branche de rubrique et le branche de base. Si la base de fusion change, la demande de tirage ne peut pas être fusionnée tant que quelqu’un n’a pas approuvé à nouveau le travail.
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.
Note
Pour les vérifications d’état au niveau de l’organisation, l’application doit être installée avec l’autorisation statuses:write. Seules les applications avec cette autorisation sont affichées durant la configuration des ensembles de règles au niveau de l’organisation.
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.
Vous ne pouvez pas activer les poussées forcées pour une branche si un administrateur de site les a bloquées sur toutes les branches de votre dépôt. Pour plus d’informations, consultez « Application de stratégies de gestion des dépôts dans votre entreprise ».
Si un administrateur de site a bloqué les poussées forcées vers la branche par défaut uniquement, vous pouvez toujours activer les poussées forcées pour toute autre branche ou étiquette.
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.
| Event | 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
Remarques :
- L’ajout de restrictions de métadonnées peut avoir un impact sur l’expérience des personnes qui contribuent à votre référentiel. Avant d’appliquer un ensemble de règles avec des restrictions de métadonnées, vous pouvez sélectionner l’état d’application « Évaluer » pour votre ensemble de règles afin de tester les effets des restrictions de métadonnées sans affecter les contributeurs. Pour plus d’informations sur les restrictions de métadonnées, consultez « Règles disponibles pour les ensembles de règles ».
- Les restrictions de métadonnées sont destinées à accroître la cohérence entre les commits de votre dépôt. Elles ne sont pas destinées à remplacer les mesures de sécurité, comme exiger une révision du code via des demandes de tirage.
- Si vous effectuez la fusion Squash d’une branche, toutes les validations sur cette branche doivent répondre à toutes les exigences de métadonnées pour la branche de base.
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. Vous pouvez utiliser des restrictions de métadonnées comme alternative à la configuration de scripts de hook de préréception personnalisés. Pour plus d’informations, consultez « [AUTOTITLE (/admin/policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks) ».
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.