Criar um decorador de pipeline

Azure DevOps Services | Servidor Azure DevOps | 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 scanner de vírus em todas as saídas de build que possam ser liberadas. 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 arquivo para nosso vss-extension.json 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:

Targets

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

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

2. Criar um arquivo YAML de decorador

Nas propriedades da extensão, escolhemos o nome "my-decorator.yml". Crie esse arquivo na raiz de sua contribuição. Ele manté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. Instalar 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 que possa ser usada.

Depois que a extensão tiver sido 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 script no final de cada trabalho. Uma execução de pipeline é semelhante ao exemplo a seguir.

4. Injetar condições

Em nosso exemplo, só precisaremos executar o verificador de vírus se as saídas de build puderem ser liberadas para o público. Digamos que somente os builds do branch padrão (normalmente main) sejam liberados. Devemos limitar o decorador a trabalhos em execução 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) }}:
  - task: CmdLine@2
    displayName: 'Run my script (injected from decorator)'
    inputs:
      script: dir

Você pode começar a ver o poder desse ponto de extensibilidade. Use o contexto do trabalho atual para injetar condicionalmente as etapas no runtime. 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 de dados disponíveis.

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

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'))) }}:
  - task: CmdLine@2
    displayName: 'Run my script (injected from decorator)'
    inputs:
      script: dir

5. Especificar 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 o 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 a 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 de tarefa de pipeline de destino (entradas com o target_ prefixo), a tarefa de pipeline injetada 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@2criar uma cópia da tarefa CmdLine@2 e publicá-la com a extensão do decorador.

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

vss-extension.json (versão de entradas de tarefa injetada)

{
    "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.

Debug

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 para true quando enfileirar um pipeline. Em seguida, examine a página de resumo do pipeline.

Você verá algo semelhante à imagem a seguir.

Selecione a tarefa para ver os logs, que mostram valores de runtime e que o contexto está disponível.

Conteúdo relacionado

• 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