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

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

Les demandes de tirage sont un excellent outil pour faciliter les révisions de code et gérer le déplacement du code au sein d’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 à effectuer sur le code. Pour couvrir ces besoins individuels et personnalisés, Azure Repos offre des états de demande de tirage. Les états de demande de tirage s’intègrent au workflow de demande de tirage et permettent aux services externes de signer par programmation une modification de code en associant des informations simples sur le type de réussite/échec à une demande de tirage. Si vous le souhaitez, les demandes de tirage peuvent être bloquées jusqu’à ce que le service externe approuve la modification.

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

• Statut de demande de tirage : permet aux services d’associer des informations de réussite/d’é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 le statut de la demande de tirage indique la réussite.
• Actions personnalisées : permet d’étendre le menu statut à 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 de la demande de tirage

Le statut de demande de tirage permet aux services d’associer des informations simples sur le type de réussite/échec à une demande de tirage, à l’aide de l’API Statut. Un statut se compose de quatre éléments clés de données :

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

Essentiellement, le statut est la façon dont un utilisateur ou un service publie son évaluation d’une demande de tirage et fournit la réponse à des 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 ?

Prenons 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 d’une demande de tirage, il doit publier les résultats de la génération 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 Détails de la demande de tirage :

• Le state est affiché à l’utilisateur à l’aide d’une icône (vert pour succeeded, rouge X pour failed, une horloge pour pending et un ! rouge pour error).
• Le description s’affiche en regard de l’icône et context est disponible dans une info-bulle.
• Quand un targetUrl est appliqué, la description est rendue sous forme de 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 aide les utilisateurs à gérer les attentes. Par exemple, la publication d’un statut pending est un bon moyen de reconnaître à l’utilisateur qu’un système a reçu un événement et qu’il commence à travailler. L’utilisation d’informations description telles que les exemples suivants peut aider l’utilisateur à comprendre le fonctionnement du système :

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

Statut d’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.

Remarque

Si la demande de tirage en cours de création contient plus de 100 000 fichiers modifiés, elle ne prend pas en charge les itérations pour des raisons de performances et de stabilité. Cela signifie que toute modification supplémentaire apportée à cette demande de tirage sera incluse, mais qu’aucune nouvelle itération ne sera créée pour cette modification. En outre, toute tentative de création d’un état pour une itération inexistante retourne une erreur.

À 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 de statut, si le statut d’itération est utilisé, les conditions de réinitialisation doivent être définies sur Réinitialiser le statut 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 des statuts sur une itération et sur une demande de tirage.

Stratégie d'état

À 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 d’état sont configurées comme les 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 au 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 sélectionné pour exiger qu’un compte spécifique ait le pouvoir de publier un statut qui approuvera la stratégie.

Applicabilité de la stratégie

Les options d’applicabilité de 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 après la publication du premier statut 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 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 stratégie ne s’applique pas tant que le premier statut 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), 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 série de tests 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èlede 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
• Utiliser Azure Functions pour créer des stratégies de branche personnalisées
• Configurer une stratégie de branche pour un service externe