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.

1. Ajouter des contributions à une extension

L’exemple suivant part du principe que vous connaissez les modèles de contribution.

1. Créez une extension. Une fois votre extension créée, vous disposez d’un vss-extension.json fichier.
2. Ajoutez des contributions au vss-extension.json fichier 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 :

Targets

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

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.

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.

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.

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.

Articles connexes

• À propos de la syntaxe d’expression YAML
• Contexte d’expression de décorateur de pipeline
• Développer une extension web
• Guide d’authentification