Personnaliser et étendre les flux de travail de demande de tirage avec l’état de la demande de tirage

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 demande de tirage en établissant des exigences qui doivent être effectuées 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 états de demande de tirage. Les états des demandes de tirage (pull request) s’intègrent au workflow de demande de tirage et permettent aux services externes de se déconnecter par programmation d’une modification de code en associant des informations de type réussite/échec simples à une demande de tirage( pull request). Si vous le souhaitez, les demandes de tirage peuvent être bloquées jusqu’à ce que le service externe approuve 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.
• Stratégie d’état : fournit un mécanisme permettant de bloquer l’achèvement de la demande de tirage jusqu’à ce que l’état de la demande de tirage 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 la façon dont ils peuvent être utilisés pour s’intégrer dans le flux de travail de demande de tirage.

État de la demande de tirage

L’état de la demande de tirage (pull request) permet aux services d’associer des informations simples de type réussite/échec à une demande de tirage à 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 une demande de tirage et fournit la réponse aux questions telles que :

• 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 à une demande de tirage, il doit publier les résultats de la build et des tests. Pour les modifications qui passent la build, un état semblable à 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"
}

Cet état s’affiche à l’utilisateur final dans la vue Détails de la demande de tirage :

• L’utilisateur state s’affiche à l’aide d’une icône (coche succeededverte, rouge X pour failed, horloge pour pending, et rouge ! pour error).
• L’icône description s’affiche en regard de l’icône, et elle 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 état de demande de tirage pour une demande de tirage unique en publiant des états supplémentaires, dont la dernière est affichée 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 :

• « Générer en file d’attente »
• « Générer en cours »
• « Build réussi »

É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 de code souhaitent publier un nouvel état sur chaque itération d’une demande de tirage. La publication de l’état dans une itération spécifique d’une demande de tirage garantit que l’état s’applique uniquement au code évalué et aucune des futures mises à jour.

À 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, la vérification que l’auteur (une propriété PR immuable) appartient à un groupe spécifique ne doit être évalué qu’une seule fois, et l’état de l’itération n’est 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 pour réinitialiser l’état chaque fois qu’il existe de nouvelles modifications. Cela garantit également 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 demande de tirage.

Stratégie d’état

À l’aide de l’état seul, les détails d’un service externe peuvent être fournis aux utilisateurs au sein de l’expérience pr. Parfois, le partage d’informations sur une demande de tirage est tout ce qui est nécessaire, mais dans d’autres cas, les demandes de tirage doivent être bloquées de fusionner 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 des demandes 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, il s’agit uniquement d’informations et d’un état non succeeded requis pour terminer la demande de tirage.

Les stratégies d’état 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 l’état a été publié précédemment, vous pouvez le sélectionner dans la liste ; s’il s’agit d’une nouvelle stratégie, vous pouvez taper le nom de la stratégie dans lenom du / de format.

Lorsqu’une stratégie d’état est spécifiée, elle exige qu’un état correspondant succeeded au context nom sélectionné soit présent pour que cette stratégie passe.

Un compte autorisé peut également être sélectionné pour exiger qu’un compte spécifique ait l’autorité de publier l’état qui approuvera la stratégie.

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 dès que la demande de tirage est créée. Avec cette option, la stratégie ne passe pas après la création d’une demande de tirage tant qu’un succeeded état n’est pas publié. Une demande de tirage peut être marquée comme exemptée de la stratégie en publiant un état , notApplicablece qui supprime l’exigence de la stratégie.

2. Conditionnel : la stratégie ne s’applique pas tant que le premier état n’est pas publié dans la demande de tirage.

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), l’état 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

Outre les événements de hook de service prédéfinis qui peuvent déclencher le service pour mettre à jour l’état de la 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