Personnalisez et étendez les workflows de pull request avec le statut de pull request.

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 flux de travail de demande de tirage implique quelques concepts différents :

• État de la demande de tirage ( pull request) : permet aux services d’associer des informations de réussite/échec à une demande de tirage.
• 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 statuts des pull requests et comment ils peuvent être intégrés dans le flux de travail des pull requests.

É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 compilation, un état semblable à celui-ci peut être publié sur la pull request :

{
    "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 pull request pour un seul pull request en publiant des statuts supplémentaires, seul le dernier étant affiché pour chaque pull request 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éussi »

État de l’itération

Lorsque la branche source d'un pull request change, une nouvelle "itération" est créée pour suivre les dernières modifications. Les services qui évaluent les modifications de code souhaitent mettre à jour le statut à chaque itération d'une pull request. La publication de l’état dans une itération spécifique d’un pull request garantit que l’état s’applique uniquement au code évalué et à aucune des mises à jour futures.

À l’inverse, si l’état publié s’applique à l’ensemble de la demande de tirage, indépendamment du code, la publication dans l’itération peut être inutile. Par exemple, vérifier que l’auteur (une propriété PR immuable) appartient à un groupe spécifique ne nécessiterait d'être évalué qu'une seule fois, et aucun état d'itération n’est requis.

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 également que le pull request ne pourra pas être fusionné tant que le dernier 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

En utilisant uniquement le statut, les détails d’un service externe peuvent être fournis aux utilisateurs au sein de l'expérience de la revue de code. Parfois, le partage d'informations sur un pull request est tout ce qui est nécessaire, mais dans d'autres cas, les pull requests doivent être bloqués temporairement pour empêcher la fusion jusqu'à satisfaction des exigences. Comme les stratégies intégrées, la stratégie d’état permet aux services externes de bloquer l’achèvement des demandes de tirage jusqu’à ce que les exigences soient remplies. Si la stratégie est requise, elle doit être validée pour compléter la pull request. Si la stratégie est facultative, il s'agit uniquement d'informations, et un état de succeeded n'est pas requis pour terminer le pull request.

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, elle exige qu’un état avec succeeded correspondant au nom sélectionné context soit présent pour que cette stratégie puisse être validée.

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 règle ne s'applique pas après la création d'une pull request tant qu'un succeeded état n'est pas publié. Une demande de tirage peut être marquée comme exemptée de la politique en publiant un état notApplicable, ce qui supprime l’exigence de la politique.

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 d’« orchestration » de niveau supérieur peut être définie pour s’appliquer par défaut pendant que le pull request est évalué 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’un résultat de la build spécifique), le statut peut être mis à jour pour les rendre requis. 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

Outre les événements de hook de service prédéfinis qui peuvent déclencher le service pour mettre à jour le statut du PR, il est possible d’étendre le menu de statut à l’aide des extensions Azure DevOps Services pour permettre à l'utilisateur final de créer des actions de déclenchement. 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 du PR et découvrez les guides pratiques :

• Créer un serveur de statut de requêtes 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