Criar um decorador de pipeline

Azure DevOps Services | Azure DevOps Server 2022

Os decoradores de pipeline permitem adicionar etapas ao início e ao fim de cada trabalho. O processo de criação de um decorador de pipeline é diferente de adicionar etapas a uma única definição porque se aplica a todos os pipelines em uma organização.

Suponha que sua organização exija a execução de um verificador de vírus em todas as saídas de compilação que podem ser lançadas. Os autores do pipeline não precisam se lembrar de adicionar essa etapa. Criamos um decorador que injeta automaticamente a etapa. Nosso decorador de pipeline injeta uma tarefa personalizada que faz a verificação de vírus no final de cada trabalho de pipeline.

1. Adicionar contribuições a uma extensão

O exemplo a seguir pressupõe que você esteja familiarizado com os modelos de contribuição.

1. Crie uma extensão. Depois que sua extensão for criada, você terá um vss-extension.json arquivo.
2. Adicione contribuições ao vss-extension.json arquivo para nosso novo decorador 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"
        }
    ]
}

Opções de contribuição

Vamos dar uma olhada nas propriedades e para que elas são usadas:

Destinos

Neste exemplo, usamos ms.azure-pipelines-agent-job.post-job-tasks porque queremos executar no final de todos os trabalhos de compilação.

Essa extensão contribui com um decorador de pipeline. Em seguida, criamos um arquivo YAML de modelo para definir o comportamento do decorador.

2. Crie um arquivo YAML do decorador

Nas propriedades da extensão, escolhemos o nome "my-decorator.yml". Crie esse arquivo na raiz de sua contribuição. Ele contém o conjunto de etapas a serem executadas após cada trabalho. Começamos com um exemplo básico e trabalhamos até a tarefa completa.

my-decorator.yml (versão inicial)

steps:
- task: CmdLine@2
  displayName: 'Run my script (injected from decorator)'
  inputs:
    script: dir

3. Instale o decorador

Para adicionar um decorador de pipeline à sua organização, você deve instalar uma extensão. Somente extensões privadas podem contribuir com decoradores de pipeline. A extensão deve ser criada e compartilhada com sua organização antes de poder ser usada.

Depois que a extensão for compartilhada com sua organização, pesquise a extensão e instale-a.

Salve o arquivo e, em seguida , compile e instale a extensão. Crie e execute um pipeline básico. O decorador injeta automaticamente nosso dir roteiro no final de cada trabalho. Uma execução de pipeline é semelhante ao exemplo a seguir.

4. Condições de injeção

Em nosso exemplo, só precisamos executar o verificador de vírus se as saídas de compilação puderem ser liberadas para o público. Digamos que apenas compilações do branch padrão (normalmente main) sejam lançadas. Devemos limitar o decorador a trabalhos executados no branch padrão.

O arquivo atualizado tem esta aparência:

my-decorator.yml (versão revisada)

steps:
- ${{ if eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

Você pode começar a ver o poder desse ponto de extensibilidade. Use o contexto do trabalho atual para injetar condicionalmente etapas em tempo de execução. Use expressões YAML para tomar decisões sobre quais etapas injetar e quando. Consulte o contexto de expressão do decorador de pipeline para obter uma lista completa dos dados disponíveis.

Há outra condição que precisamos considerar: e se o usuário já incluiu a etapa de verificação de vírus? Não devemos perder tempo executando-o novamente. Neste exemplo simples, vamos fingir que qualquer script tarefa encontrada no trabalho está executando o verificador de vírus. (Em uma implementação real, você teria uma tarefa personalizada para verificar isso.)

A ID da tarefa de script é d9bafed4-0b18-4f58-968d-86655b4d2ce9. Se virmos outra tarefa de script, não devemos injetar a nossa.

my-decorator.yml (versão final)

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. Especifique uma tarefa de destino

Você pode especificar a ID da tarefa de destino e injetar tarefas antes ou depois dessa tarefa de destino. Para especificar a tarefa de destino, você pode modificar vss-extension.json arquivo de manifesto como no exemplo a seguir.

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"
            }
        }
    ],
    ...
}

Ao configurar a propriedade 'targettask', você pode especificar o ID de uma tarefa de destino. As tarefas serão injetadas antes/depois de todas as instâncias da tarefa de destino especificada.

Especificar a injeção de entradas da tarefa de destino

Você pode especificar uma lista de entradas da tarefa de destino que deseja injetar como entradas para a tarefa injetada.

Esse recurso foi projetado para funcionar com tarefas de pipeline personalizadas. Ele não se destina a fornecer acesso a entradas de tarefa de pipeline de destino por meio de variáveis de pipeline.

Para obter acesso às entradas da tarefa de pipeline de destino (entradas com o prefixo), a tarefa de pipeline injetada target_ deve usar métodos do azure-pipelines-tasks-task-lib e não as variáveis de pipeline, por exemplo const inputString = tl.getInput('target_targetInput')).

Para fazer isso, você pode criar sua própria tarefa de pipeline personalizada e usar as entradas de destino lá. Se você precisar da funcionalidade de uma das tarefas prontas para uso, como CmdLine@2, poderá criar uma cópia da tarefa CmdLine@2 e publicá-la com sua extensão decorator.

Para especificar essa lista de entradas, você pode modificar vss-extension.json arquivo de manifesto como no exemplo a seguir.

vss-extension.json (versão de entradas de tarefas injetadas)

{
    "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"]
            }
        }
    ],
    ...
}

Ao configurar a propriedade 'targettaskinputs', você pode especificar a lista de entradas que devem ser injetadas. Essas entradas serão injetadas na tarefa com o prefixo "target_" e estarão disponíveis na tarefa injetada como target_target-task-input.

Depurar

Talvez seja necessário depurar ao criar seu decorador. Você também pode querer ver quais dados você tem disponíveis no contexto.

Você pode definir a system.debugContext variável como true quando enfileirar um pipeline. Em seguida, observe a página de resumo do pipeline.

Você vê algo semelhante à imagem a seguir.

Selecione a tarefa para ver os logs, que mostram valores de tempo de execução e se o contexto está disponível.

Artigos relacionados

• Sobre a sintaxe da expressão YAML
• Contexto de expressão do decorador de pipeline
• Desenvolver uma extensão da Web
• Guia de autenticação