Personnaliser et étendre les workflows de demande de tirage avec des statuts

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Les demandes de tirage sont un excellent outil pour faciliter les révisions de code et gérer le déplacement du code dans un référentiel. Les stratégies de branche appliquent la qualité du code pendant le processus de pull request en établissant des exigences qui doivent être remplies pour chaque modification de code. Ces stratégies permettent aux équipes d’appliquer de nombreuses bonnes pratiques liées à l’examen du code et à l’exécution de builds automatisées, mais de nombreuses équipes ont des exigences et des validations supplémentaires pour effectuer du code. Pour couvrir ces besoins individuels et personnalisés, Azure Repos offre des statuts de pull request. Les états des pull requests s'intègrent au workflow des pull requests et permettent aux services externes d'approuver par programmation une modification de code en associant des informations simples de type réussite/échec à une pull request. De manière optionnelle, les pull requests peuvent être bloquées jusqu'à ce que le service externe valide la modification.

Prerequisites

L’intégration dans le workflow de demande de tirage implique différents concepts :

• Statut de la pull request : permet aux services d’associer des informations de réussite/d’échec à une pull request.
• Politique de statut : fournit un mécanisme permettant de bloquer l’achèvement de la pull request jusqu’à ce que le statut de la pull request indique la réussite.
• Actions personnalisées : permet d’étendre le menu d’état à l’aide des extensions Azure DevOps Services.

Dans cette rubrique, vous allez découvrir les états des demandes de tirage et comment ils peuvent être utilisés pour s’intégrer dans le workflow de demande de tirage.

État du pull request

L’état du pull request permet aux services d’associer des informations de réussite/échec simples à une pull request à l’aide de l’API Status. Un état se compose de quatre éléments clés de données :

• État. L’un des états prédéfinis suivants : succeeded, , failedpending, notSet, notApplicableou error.
• Description. Chaîne qui décrit l’état de l’utilisateur final.
• Contexte. Nom de l’état : décrit généralement l’entité qui publie l’état.
• URL. Lien dans lequel les utilisateurs peuvent obtenir plus d’informations spécifiques à l’état.

Essentiellement, l’état est la façon dont un utilisateur ou un service publie son évaluation sur un pull request et fournit la réponse aux questions comme :

• Les modifications ont-ils satisfait aux exigences ?
• Où puis-je en savoir plus sur ce que je dois faire pour répondre aux exigences ?

Examinons un exemple. Considérez un service CI requis pour générer toutes les modifications de code dans un projet. Lorsque ce service évalue les modifications apportées à un pull request, il doit publier les résultats de la compilation et des tests. Pour les modifications qui passent la build, un statut comme celui-ci peut être publié sur la demande de tirage :

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

Ce statut s'affiche à l'utilisateur final dans la vue des détails de la PR :

• L’élément state est présenté à l'utilisateur à l'aide d'une icône (une coche verte pour succeeded, un X rouge pour failed, une horloge pour pending, et un ! rouge pour error).
• L’élément description s’affiche à côté de l’icône, et l’élément context est disponible dans une info-bulle.
• Lorsqu’une targetUrl application est appliquée, la description est affichée sous la forme d’un lien vers l’URL.

Mise à jour de l’état

Un service peut mettre à jour un statut de demande de tirage pour une seule demande de tirage en publiant des états supplémentaires, dont seul le dernier est affiché pour chaque demande de tirage unique context. La publication de plusieurs états permet aux utilisateurs de gérer les attentes. Par exemple, la publication d’un pending état est un bon moyen de reconnaître à l’utilisateur qu’un système a reçu un événement et démarre le travail. L’utilisation d’une information telle description que les exemples suivants peut aider l’utilisateur à comprendre le fonctionnement du système :

• « Construction en file d’attente »
• « Construction en cours »
• « Build réussie »

État de l’itération

Lorsque la branche source d’une demande de tirage change, une nouvelle « itération » est créée pour suivre les dernières modifications. Les services qui évaluent les modifications du code souhaitent publier de nouveaux statuts à chaque itération d’une demande de tirage. La publication statut à une itération spécifique d’une demande de tirage garantit que le statut s’applique uniquement au code qui a été évalué et aucune des mises à jour futures.

À l’inverse, si le statut publié s’applique à l’ensemble de la demande de tirage, indépendamment du code, la publication dans l’itération peut ne pas être nécessaire. Par exemple, la vérification du fait que l’auteur (une propriété immuable de la demande de tirage) appartient à un groupe spécifique ne devrait être évaluée qu’une seule fois, et le statut d’itération ne serait pas nécessaire.

Lors de la configuration de la stratégie d’état, si l’état de l’itération est utilisé, les conditions de réinitialisation doivent être définies de manière à réinitialiser l’état chaque fois qu’il y a de nouvelles modifications. Cela garantit en outre que la demande de tirage ne pourra pas être fusionnée tant que la dernière itération n’aura pas l’état succeeded.

Consultez les exemples d’API REST pour publier l’état sur une itération et sur une pull request.

Politique de statut

À l’aide du statut seul, les détails d’un service externe peuvent être fournis aux utilisateurs au sein de l’expérience demande de tirage. Parfois, le partage d’informations sur une demande de tirage est tout ce qui est nécessaire, mais dans d’autres cas, la fusion des demandes de tirage doit être bloquée jusqu’à ce que les exigences soient remplies. Comme les stratégies intégrées, la stratégie d’état permet aux services externes de bloquer l’achèvement de la demande de tirage jusqu’à ce que les exigences soient remplies. Si la stratégie est requise, elle doit passer pour terminer la demande de tirage. Si la stratégie est facultative, elle n’est qu’informationnelle et l’état succeeded n’est pas nécessaire pour effectuer la demande de tirage.

Les stratégies de statut sont configurées comme d’autres stratégies de branche. Lors de l’ajout d’une nouvelle stratégie d’état, le nom et le genre de la stratégie d’état doivent être entrés. Si le statut a été publié précédemment, vous pouvez le sélectionner dans la liste ; s'il s'agit d'une nouvelle politique, vous pouvez taper le nom de la politique dans le format genre/nom.

Lorsqu’une stratégie d’état est spécifiée, un statut de succeeded avec le context nom sélectionné doit être présente pour que cette stratégie passe.

Un compte autorisé peut également être configuré pour exiger qu’un compte spécifique ait l’autorisation de publier un statut qui approuvera la politique.

Applicabilité de la stratégie

Les options d’applicabilité de la stratégie déterminent si cette stratégie s’applique dès qu’une demande de tirage est créée ou si la stratégie s’applique uniquement une fois que le premier état est publié dans la demande de tirage.

1. Appliquer par défaut : la stratégie s’applique lorsque le pull request est créé. Avec cette option, la stratégie ne passe pas après la création d’une demande de tirage tant que l’état succeeded n’est pas publié. Une demande de tirage peut être marquée comme exemptée de la stratégie en publiant un statut de notApplicable, ce qui supprimera l’exigence de stratégie.

2. Conditionnel : la politique ne s’applique pas tant que le premier état n’est pas publié dans la pull request.

Ensemble, ces options peuvent être utilisées pour créer une suite de stratégies dynamiques. Une stratégie « orchestration » de niveau supérieur peut être définie pour s’appliquer par défaut pendant que la demande de tirage est évaluée pour les stratégies applicables. Ensuite, à mesure que des stratégies conditionnelles supplémentaires sont déterminées à s’appliquer (peut-être en fonction d’une sortie de build spécifique), le statut peut être publié pour les rendre obligatoires. Cette stratégie d’orchestration peut être marquée succeeded lorsqu’elle a terminé l’évaluation ou peut être marquée notApplicable pour indiquer à la demande de tirage que la stratégie ne s’applique pas.

Actions personnalisées

En plus des événements de crochet de service prédéfinis qui peuvent déclencher le service pour mettre à jour les états de demande de tirage, il est possible d’étendre le menu d’état à l’aide des extensions Azure DevOps Services pour donner des actions de déclencheur à l’utilisateur final. Par exemple, si l’état correspond à une exécution de test qui peut être redémarrée par l’utilisateur final, il est possible d’avoir un élément de menu Redémarrer dans le menu d’état qui déclencherait l’exécution des tests. Pour ajouter un menu d’état, vous devez utiliser le modèle de contribution. Pour plus d’informations, consultez l’exemple d’extension Azure DevOps.

Étapes suivantes

En savoir plus sur l’API État de la demande de tirage et consultez les guides pratiques :

• Créer un serveur d’état de demande de tirage avec Node.js
• Créer des stratégies de branche personnalisées à l’aide d’Azure Functions
• Configurer une stratégie de branche pour un service externe