Compartilhar via

Criar um decorador de pipeline

  • Artigo

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.

Dica

Confira nossa documentação mais recente sobre o desenvolvimento de extensão usando o SDK da Extensão do Azure DevOps.

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:

Propriedade Descrição
id Identificador de contribuição. Deve ser único entre as contribuições nesta extensão.
type Especifica que essa contribuição é um decorador de pipeline. Deve ser a string ms.azure-pipelines.pipeline-decorator.
targets Os decoradores podem ser executados antes do seu trabalho/tarefa especificada, depois ou ambos. Consulte a tabela a seguir para ver as opções disponíveis.
properties.template (Obrigatório) O modelo é um arquivo YAML incluído em sua extensão, que define as etapas para o decorador de pipeline. É um caminho relativo da raiz da pasta de extensão.
properties.targettask A ID da tarefa de destino usada para ms.azure-pipelines-agent-job.pre-task-tasks ou ms.azure-pipelines-agent-job.post-task-tasks destinos. Deve ser semelhante a uma cadeia de caracteres GUID 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Destinos

Destino Descrição
ms.azure-pipelines-agent-job.pre-job-tasks Execute antes de outras tarefas em um build clássico ou pipeline YAML. Devido às diferenças em como o check-out do código-fonte acontece, esse destino é executado após o check-out em um pipeline YAML, mas antes do check-out em um pipeline de build clássico.
ms.azure-pipelines-agent-job.post-checkout-tasks Execute após a última checkout tarefa em um build clássico ou pipeline YAML.
ms.azure-pipelines-agent-job.post-job-tasks Execute outras tarefas em um build clássico ou pipeline YAML.
ms.azure-pipelines-agent-job.pre-task-tasks Execute antes da tarefa especificada em um build clássico ou pipeline YAML.
ms.azure-pipelines-agent-job.post-task-tasks Execute após a tarefa especificada em um build clássico ou pipeline YAML.
ms.azure-release-pipelines-agent-job.pre-task-tasks Executar antes da tarefa especificada em um pipeline RM clássico.
ms.azure-release-pipelines-agent-job.post-task-tasks Execute após a tarefa especificada em um pipeline RM clássico.
ms.azure-release-pipelines-agent-job.pre-job-tasks Execute antes de outras tarefas em um pipeline RM clássico.
ms.azure-release-pipelines-agent-job.post-job-tasks Execute outras tarefas em um pipeline RM clássico.

Observação

Os trabalhos de implantação em um pipeline YAML só dão suporte ms.azure-pipelines-agent-job.pre-job-tasks e ms.azure-pipelines-agent-job.post-job-tasks destinos. Os trabalhos dão suporte a todos os destinos de pipeline YAML. Não há suporte para trabalhos de implantação em pipelines de lançamento clássicos.

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

Observação

Não há suporte para tarefas do decorador de pipeline com uso de conexão de serviço para pipelines de lançamento clássicos.

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.

Decorador de pipeline executando um script simples

Observação

O decorador executa todos os trabalhos em todos os funis da organização. Em etapas posteriores, adicionamos lógica para controlar quando e como o decorador é executado.

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.

Observação

Essa funcionalidade só está disponível para tarefas que são injetadas antes ou depois da tarefa de destino.

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.

Observação

As entradas de tarefa de destino que obtêm valores secretos com variáveis ou os obtêm de outras tarefas não serão injetadas.

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.

Exibir o contexto do decorador de pipeline

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