Créer un décorateur de pipeline
Azure DevOps Services | Azure DevOps Server 2022
Les décorateurs de pipeline vous permettent d’ajouter des étapes au début et à la fin de chaque travail. Le processus de création d’un décorateur de pipeline est différent de l’ajout d’étapes à une définition unique, car il s’applique à tous les pipelines d’une organisation.
Supposons que votre organisation exige l’exécution d’un scanneur antivirus sur toutes les sorties de build qui peuvent être publiées. Les auteurs de pipelines n’ont pas besoin de se rappeler d’ajouter cette étape. Nous créons un décorateur qui injecte automatiquement l’étape. Notre décorateur de pipeline injecte une tâche personnalisée qui effectue une analyse antivirus à la fin de chaque travail de pipeline.
Conseil
Consultez notre documentation la plus récente sur le développement d’extensions à l’aide du Kit de développement logiciel (SDK) d’extension Azure DevOps.
1. Ajouter des contributions à une extension
L’exemple suivant part du principe que vous connaissez les modèles de contribution.
- Créez une extension.
Une fois votre extension créée, vous disposez d’un
vss-extension.jsonfichier. - Ajoutez des contributions au
vss-extension.jsonfichier pour notre nouveau décorateur de pipeline.
vss-extension.json
{
"manifestVersion": 1,
"contributions": [
{
"id": "my-required-task",
"type": "ms.azure-pipelines.pipeline-decorator",
"targets": [
"ms.azure-pipelines-agent-job.post-job-tasks"
],
"properties": {
"template": "my-decorator.yml"
}
}
],
"files": [
{
"path": "my-decorator.yml",
"addressable": true,
"contentType": "text/plain"
}
]
}
Options de contribution
Examinons les propriétés et ce qu’elles sont utilisées pour :
| Propriété | Description |
|---|---|
id |
Identificateur de contribution. Doit être unique parmi les contributions de cette extension. |
type |
Spécifie que cette contribution est un décorateur de pipeline. Doit être la chaîne ms.azure-pipelines.pipeline-decorator. |
targets |
Les décorateurs peuvent s’exécuter avant votre tâche/tâche spécifiée, après ou les deux. Consultez le tableau suivant pour connaître les options disponibles. |
properties.template |
(Obligatoire) Le modèle est un fichier YAML inclus dans votre extension, qui définit les étapes de votre décorateur de pipeline. Il s’agit d’un chemin relatif à partir de la racine de votre dossier d’extension. |
properties.targettask |
ID de tâche cible utilisé pour ms.azure-pipelines-agent-job.pre-task-tasks ou ms.azure-pipelines-agent-job.post-task-tasks cible. Doit être une chaîne GUID comme 89b8ac58-8cb7-4479-a362-1baaacc6c7ad |
Targets
| Cible | Description |
|---|---|
ms.azure-pipelines-agent-job.pre-job-tasks |
Exécutez avant d’autres tâches dans un pipeline yaML ou build classique. En raison des différences dans la façon dont l’extraction du code source se produit, cette cible s’exécute après l’extraction dans un pipeline YAML, mais avant l’extraction dans un pipeline de build classique. |
ms.azure-pipelines-agent-job.post-checkout-tasks |
Exécutez après la dernière checkout tâche d’une build classique ou d’un pipeline YAML. |
ms.azure-pipelines-agent-job.post-job-tasks |
Exécutez après d’autres tâches dans un pipeline de build ou YAML classique. |
ms.azure-pipelines-agent-job.pre-task-tasks |
Exécutez avant la tâche spécifiée dans une build classique ou un pipeline YAML. |
ms.azure-pipelines-agent-job.post-task-tasks |
Exécutez après la tâche spécifiée dans une build classique ou un pipeline YAML. |
ms.azure-release-pipelines-agent-job.pre-task-tasks |
Exécutez avant la tâche spécifiée dans un pipeline RM classique. |
ms.azure-release-pipelines-agent-job.post-task-tasks |
Exécutez après la tâche spécifiée dans un pipeline RM classique. |
ms.azure-release-pipelines-agent-job.pre-job-tasks |
Exécutez avant d’autres tâches dans un pipeline RM classique. |
ms.azure-release-pipelines-agent-job.post-job-tasks |
Exécutez après d’autres tâches dans un pipeline RM classique. |
Remarque
Les travaux de déploiement dans un pipeline YAML prennent uniquement en charge ms.azure-pipelines-agent-job.pre-job-tasks et ms.azure-pipelines-agent-job.post-job-tasks cible.
Les travaux prennent en charge toutes les cibles de pipeline YAML.
Les travaux de déploiement ne sont pas pris en charge dans les pipelines de mise en production classiques.
Dans cet exemple, nous utilisons ms.azure-pipelines-agent-job.post-job-tasks parce que nous voulons exécuter à la fin de tous les travaux de génération.
Cette extension contribue à un décorateur de pipeline. Ensuite, nous créons un fichier YAML de modèle pour définir le comportement du décorateur.
2. Créer un fichier YAML décoratif
Dans les propriétés de l’extension, nous avons choisi le nom « my-decorator.yml ». Créez ce fichier à la racine de votre contribution. Il contient l’ensemble des étapes à exécuter après chaque travail. Nous commençons par un exemple de base et travaillons jusqu’à la tâche complète.
my-decorator.yml (version initiale)
steps:
- task: CmdLine@2
displayName: 'Run my script (injected from decorator)'
inputs:
script: dir
Remarque
Les tâches de décorateur de pipeline avec utilisation de la connexion de service ne sont pas prises en charge pour les pipelines de mise en production classiques.
3. Installer le décorateur
Pour ajouter un décorateur de pipeline à votre organisation, vous devez installer une extension. Seules les extensions privées peuvent contribuer aux décorateurs de pipeline. L’extension doit être créée et partagée avec votre organisation avant de pouvoir être utilisée.
Une fois l’extension partagée avec votre organisation, recherchez l’extension et installez-la.
Enregistrez le fichier, puis générez et installez l’extension.
Créez et exécutez un pipeline de base.
Le décorateur injecte automatiquement notre dir script à la fin de chaque travail.
Une exécution de pipeline ressemble à l’exemple suivant.
Remarque
Le décorateur s’exécute sur chaque travail de chaque pipeline de l’organisation. Dans les étapes ultérieures, nous ajoutons une logique pour contrôler quand et comment l’élément décoratif s’exécute.
4. Injecter des conditions
Dans notre exemple, nous n’avons besoin d’exécuter le scanneur antivirus que si les sorties de build peuvent être publiées sur le public. Supposons que seules les builds des branche par défaut (généralementmain) soient publiées.
Nous devrions limiter le décorateur aux travaux qui s’exécutent sur le branche par défaut.
Le fichier mis à jour ressemble à ceci :
my-decorator.yml (version révisée)
steps:
- ${{ if eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch) }}:
- script: dir
displayName: 'Run my script (injected from decorator)'
Vous pouvez commencer à voir la puissance de ce point d’extensibilité. Utilisez le contexte du travail actuel pour injecter des étapes conditionnellement au moment de l’exécution. Utilisez des expressions YAML pour prendre des décisions sur les étapes à injecter et quand. Consultez le contexte d’expression de décorateur de pipeline pour obtenir la liste complète des données disponibles.
Il existe une autre condition à prendre en compte : que se passe-t-il si l’utilisateur a déjà inclus l’étape d’analyse du virus ?
On ne devrait pas perdre du temps à le réécuter.
Dans cet exemple simple, nous allons prétendre que toute script tâche trouvée dans le travail exécute le scanneur antivirus.
(Dans une implémentation réelle, vous avez une tâche personnalisée à vérifier à la place.)
L’ID de la tâche de script est d9bafed4-0b18-4f58-968d-86655b4d2ce9.
Si nous voyons une autre tâche de script, nous ne devrions pas injecter le nôtre.
my-decorator.yml (version finale)
steps:
- ${{ if and(eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch), not(containsValue(job.steps.*.task.id, 'd9bafed4-0b18-4f58-968d-86655b4d2ce9'))) }}:
- script: dir
displayName: 'Run my script (injected from decorator)'
5. Spécifier une tâche cible
Vous pouvez spécifier l’ID de tâche cible et injecter des tâches avant ou après cette tâche cible. Pour spécifier la tâche cible, vous pouvez modifier vss-extension.json fichier manifeste comme dans l’exemple suivant.
vss-extension.json
{
"contributions": [
{
"id": "my-required-task",
"type": "ms.azure-pipelines.pipeline-decorator",
"targets": [
"ms.azure-pipelines-agent-job.pre-task-tasks",
"ms.azure-pipelines-agent-job.post-task-tasks"
],
"properties": {
"template": "my-decorator.yml",
"targettask": "target-task-id"
}
}
],
...
}
Lorsque vous configurez la propriété « targettask », vous pouvez spécifier l’ID d’une tâche cible. Les tâches seront injectées avant/après toutes les instances de la tâche cible spécifiée.
Spécifier l’injection d’entrées de la tâche cible
Vous pouvez spécifier une liste d’entrées de la tâche cible que vous souhaitez injecter en tant qu’entrées à la tâche injectée.
Cette fonctionnalité est conçue pour fonctionner avec des tâches de pipeline personnalisées. Il n’est pas destiné à fournir l’accès aux entrées de tâche de pipeline cible via des variables de pipeline.
Pour accéder aux entrées de tâche de pipeline cible (entrées avec le target_ préfixe), la tâche de pipeline injectée doit utiliser des méthodes à partir d’azure-pipelines-tasks-task-lib, et non les variables de pipeline, par exempleconst inputString = tl.getInput('target_targetInput')).
Pour ce faire, vous pouvez créer votre propre tâche de pipeline personnalisée et utiliser les entrées cibles là-bas. Si vous avez besoin des fonctionnalités de l’une des tâches prêtes à l’emploi, par CmdLine@2exemple, vous pouvez créer une copie de la tâche CmdLine@2 et la publier avec votre extension de décorateur.
Remarque
Cette fonctionnalité est disponible uniquement pour les tâches qui sont injectées avant ou après la tâche cible.
Pour spécifier cette liste d’entrées, vous pouvez modifier vss-extension.json fichier manifeste comme dans l’exemple suivant.
vss-extension.json (version des entrées de tâche injectées)
{
"contributions": [
{
"id": "my-required-task",
"type": "ms.azure-pipelines.pipeline-decorator",
"targets": [
"ms.azure-pipelines-agent-job.pre-task-tasks",
"ms.azure-pipelines-agent-job.post-task-tasks"
],
"properties": {
"template": "my-decorator.yml",
"targettask": "target-task-id",
"targettaskinputs": ["target-task-input", "target-task-second-input"]
}
}
],
...
}
En configurant la propriété « targettaskinputs », vous pouvez spécifier la liste des entrées attendues à injecter.
Ces entrées seront injectées dans la tâche avec le préfixe «target_ » et seront disponibles dans la tâche injectée comme target_target-task-input.
Remarque
Les entrées de tâche cible qui obtiennent des valeurs secrètes avec des variables ou les obtiennent à partir d’autres tâches ne seront pas injectées.
Déboguer
Vous devrez peut-être déboguer lorsque vous créez votre décorateur. Vous pouvez également voir les données disponibles dans le contexte.
Vous pouvez définir la system.debugContext variable true sur quand vous mettez en file d’attente un pipeline.
Examinez ensuite la page récapitulative du pipeline.
Vous voyez quelque chose de similaire à l’image suivante.
Sélectionnez la tâche pour afficher les journaux, qui affichent les valeurs d’exécution et que le contexte est disponible.