Personalizar um pipeline

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Este é um guia passo a passo sobre maneiras comuns de personalizar seu pipeline.

Pré-requisito

Siga as instruções em Criar seu primeiro pipeline para criar um pipeline de trabalho.

Entender o arquivo azure-pipelines.yml

Um pipeline é definido usando um arquivo YAML em seu repositório. Normalmente, esse arquivo se chama azure-pipelines.yml e está localizado na raiz do repositório.

Navegue até a página Pipelines no Azure Pipelines, selecione o pipeline que você criou e escolha Editar no menu de contexto do pipeline para abrir o editor YAML do pipeline.

Observação

Para instruções sobre como exibir e gerenciar seus pipelines no portal do Azure DevOps, confira Exibir e gerenciar seus pipelines.

Examine o conteúdo do arquivo YAML.

 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest'

 steps:
 - task: Maven@4
   inputs:
     mavenPomFile: 'pom.xml'
     mavenOptions: '-Xmx3072m'
     javaHomeOption: 'JDKVersion'
     jdkVersionOption: '1.11'
     jdkArchitectureOption: 'x64'
     publishJUnitResults: false
     testResultsFiles: '**/surefire-reports/TEST-*.xml'
     goals: 'package'

Observação

O conteúdo do arquivo YAML pode ser diferente dependendo do repositório de exemplo com o qual você começou ou das atualizações feitas no Azure Pipelines.

Esse pipeline é executado sempre que sua equipe envia uma alteração para a ramificação principal do repositório ou cria uma solicitação de pull. Ele é executado em um computador do Linux hospedado pela Microsoft. O processo de pipeline tem uma só etapa, que é executar a tarefa Maven.

Alterar a plataforma para compilar

Você pode criar seu projeto em agentes hospedados pela Microsoft que já incluem SDKs e ferramentas para várias linguagens de desenvolvimento. Ou você pode usar agentes auto-hospedados com ferramentas específicas necessárias.

• Navegue até o editor do pipeline selecionando Editar ação de pipeline no build ou selecionando Editar na página principal do pipeline.

• Atualmente, o pipeline é executado em um agente do Linux:

  pool:
    vmImage: "ubuntu-latest"
  

• Para escolher uma plataforma diferente, como Windows ou Mac, altere o valor vmImage:

  pool:
    vmImage: "windows-latest"
  

  pool:
    vmImage: "macos-latest"
  

• Selecione Salvar e confirme as alterações para ver o pipeline ser executado em uma plataforma diferente.

Adicionar etapas

Você pode adicionar mais scripts ou tarefas como etapas ao pipeline. Uma tarefa é um script pré-empacotado. Você pode usar tarefas para criar, testar, publicar ou implantar seu aplicativo. No entanto, para Java, a tarefa do Maven usada lida com testes e resultados de publicação. No entanto, você também pode usar uma tarefa para publicar resultados de cobertura de código.

• Abra o editor YAML do pipeline.

• Adicione o snippet a seguir ao final do arquivo YAML.

  - task: PublishCodeCoverageResults@1
    inputs:
      codeCoverageTool: "JaCoCo"
      summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml"
      reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco"
      failIfCoverageEmpty: true
  

• Selecione Salvar e confirme as alterações.

• Você pode exibir os resultados de teste e cobertura de código selecionando seu build e acessando as guias Teste e Cobertura.

Criar em várias plataformas

Você pode criar e testar seu projeto em várias plataformas. Um modo de fazer isso é com strategy e matrix. Você pode usar variáveis para colocar dados convenientemente em várias partes de um pipeline. Para este exemplo, usaremos uma variável para passar o nome da imagem que desejamos usar.

• No arquivo azure-pipelines.yml, substitua este conteúdo:

  pool:
    vmImage: "ubuntu-latest"
  

  com o seguinte conteúdo:

  strategy:
    matrix:
      linux:
        imageName: "ubuntu-latest"
      mac:
        imageName: "macOS-latest"
      windows:
        imageName: "windows-latest"
    maxParallel: 3
  
  pool:
    vmImage: $(imageName)
  

• Selecione Salvar e confirme as alterações para ver o build ser executado em até três trabalhos em três plataformas diferentes.

Cada agente pode executar apenas um trabalho por vez. Para executar vários trabalhos paralelamente, você deve configurar vários agentes. Você também precisa de trabalhos paralelos suficientes.

Compilar usando várias versões

Para criar um projeto usando diferentes versões dessa linguagem, você pode usar um matrix de versões e uma variável. Nesta etapa, você pode compilar o projeto Java com duas versões diferentes do Java em uma só plataforma ou executar versões diferentes do Java em diferentes plataformas.

Observação

Você não pode usar strategy várias vezes em um contexto.

• Se você quiser criar em uma só plataforma e em várias versões, adicione a matriz a seguir ao arquivo azure-pipelines.yml antes da tarefa Maven e depois do vmImage.

  strategy:
    matrix:
      jdk10:
        jdkVersion: "1.10"
      jdk11:
        jdkVersion: "1.11"
    maxParallel: 2
  

• Em seguida, substitua essa linha em sua tarefa do Maven:

  jdkVersionOption: "1.11"
  

  com esta linha:

  jdkVersionOption: $(jdkVersion)
  

• Altere a variável $(imageName) de volta para a plataforma de sua escolha.

• Se você quiser criar várias plataformas e versões, substitua todo o conteúdo em seu arquivo azure-pipelines.yml antes da tarefa de publicação pelo seguinte snippet:

  trigger:
  - main
  
  strategy:
    matrix:
      jdk10_linux:
        imageName: "ubuntu-latest"
        jdkVersion: "1.10"
      jdk11_windows:
        imageName: "windows-latest"
        jdkVersion: "1.11"
    maxParallel: 2
  
  pool:
    vmImage: $(imageName)
  
  steps:
  - task: Maven@4
    inputs:
      mavenPomFile: "pom.xml"
      mavenOptions: "-Xmx3072m"
      javaHomeOption: "JDKVersion"
      jdkVersionOption: $(jdkVersion)
      jdkArchitectureOption: "x64"
      publishJUnitResults: true
      testResultsFiles: "**/TEST-*.xml"
      goals: "package"
  

• Selecione Salvar e confirme as alterações para ver sua compilação executar dois trabalhos em duas plataformas e SDKs diferentes.

Personalizar gatilhos de CI

Gatilhos de pipeline fazem com que um pipeline seja executado. Você pode usar trigger: para fazer com que um pipeline seja executado sempre que você efetuar push de uma atualização para um branch. Os pipelines YAML são configurados por padrão com um gatilho de CI no branch padrão (que geralmente é main). Você pode configurar gatilhos para ramificações específicas ou para validação de solicitação de pull. Para um gatilho de validação de solicitação de pull, basta substituir a etapa trigger: por pr:, conforme mostrado nos dois exemplos abaixo. Por padrão, o pipeline é executado para cada alteração de solicitação de pull.

• Se você quiser configurar gatilhos, adicione um dos snippets a seguir no início do arquivo azure-pipelines.yml.

  trigger:
    - main
    - releases/*
  

  pr:
    - main
    - releases/*
  

  Você pode especificar o nome completo do branch (por exemplo, main) ou um curinga de correspondência de prefixo (por exemplo, releases/*).

Configurações do pipeline

Você pode exibir e definir as configurações de pipeline no menu Mais ações na página de detalhes do pipeline.

• Gerenciar segurança - Gerenciar segurança
• Renomear/mover – edite o nome do pipeline e o local da pasta.
• Selo de status - Adicionar um selo de status ao repositório
• Excluir – exclui o pipeline, incluindo todos os builds e artefatos associados.
• Execuções agendadas - Exibição de execuções agendadas

Escolha Configurações para definir as seguintes configurações de pipeline.

No painel Configurações do pipeline, você pode definir as configurações a seguir.

• Processamento de novas solicitações de execução – às vezes, você desejará impedir o início de novas execuções em seu pipeline.

  • Por padrão, o processamento de novas solicitações de execução está Habilitado. Essa configuração permite o processamento padrão de todos os tipos de gatilho, incluindo execuções manuais.
  • Os pipelines pausados permitem o processamento de solicitações de execução, mas essas solicitações são enfileiradas sem realmente iniciar. Quando o novo processamento de solicitação está habilitado, o processamento de execução é retomado começando com a primeira solicitação na fila.
  • Pipelines desabilitados impedem que os usuários iniciem novas execuções. Todos os gatilhos também são desabilitados enquanto essa configuração é aplicada. Todas as políticas de compilação que usam um pipeline desabilitado mostrarão a mensagem "Não é possível enfileirar a compilação" ao lado da política de compilação na janela de visão geral de relações públicas, e o status da política de compilação estará quebrado.

• Caminho do arquivo YAML – se você precisar direcionar seu pipeline para usar um arquivo YAML diferente, poderá especificar o caminho para esse arquivo. Essa configuração também poderá ser útil se você precisar mover/renomear o arquivo YAML.

• Vincular automaticamente itens de trabalho incluídos nesta execução – as alterações associadas a uma determinada execução de pipeline podem ter itens de trabalho associados. Selecione essa opção para vincular esses itens de trabalho à execução. Quando Vincular automaticamente os itens de trabalho incluídos nesta execução for selecionado, você deverá especificar um branch específico ou * para todos os branches, que é o padrão. Se você especificar um branch, os itens de trabalho serão associados apenas a execuções desse branch. Se você especificar *, os itens de trabalho serão associados a todas as execuções.

  

  • Para receber notificações quando suas execuções falharem, confira como Gerenciar notificações para uma equipe

Gerenciar a segurança

Você pode configurar a segurança de pipelines em um nível de projeto em Mais ações na página de aterrissagem de pipelines e no nível de um pipeline na página de detalhes do pipeline.

Para dar suporte à segurança de suas operações de pipeline, você pode adicionar usuários a um grupo de segurança integrado, definir permissões individuais para um usuário ou grupo, ou adicionar usuários a funções predefinidas. Gerencie a segurança dos objetos a seguir do Azure Pipelines no portal da Web, seja no contexto de usuário ou de administrador. Para obter mais informações sobre como configurar a segurança de pipelines, confira Permissões de pipeline e funções de segurança.

Criar item de trabalho em caso de falha

Os pipelines YAML não têm uma configuração Criar item de trabalho em caso de falha, como pipelines de build clássicos. Os pipelines de build clássicos são de fase única e Criar item de trabalho em caso de falha se aplica a todo o pipeline. Os pipelines YAML podem ser de várias fases e uma configuração de nível de pipeline pode não ser apropriada. Para implementar Criar item de trabalho em caso de falha em um pipeline YAML, você pode usar métodos como Itens de Trabalho – Criar chamada à API REST ou o comando az boards work-item create da CLI do Azure DevOps no ponto desejado do pipeline.

O exemplo a seguir tem dois trabalhos. O primeiro trabalho representa o trabalho do pipeline, mas, se ele falhar, o segundo trabalho será executado e criará um bug no mesmo projeto que o pipeline.

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      az boards work-item create \
        --title "Build $(build.buildNumber) failed" \
        --type bug \
        --org $(System.TeamFoundationCollectionUri) \
        --project $(System.TeamProject)
    env: 
      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
    displayName: 'Create work item on failure'

Observação

O Azure Boards permite configurar o acompanhamento de item de trabalho usando vários processos diferentes, como Agile ou Basic. Cada processo tem tipos de item de trabalho diferentes, e nem todos os tipos de item de trabalho estão disponíveis em cada processo. Para obter uma lista de tipos de item de trabalho compatíveis com cada processo, confira WITs (Tipos de item de trabalho).

O exemplo anterior usa Parâmetros de runtime para configurar se o pipeline é bem-sucedido ou falha. Ao executar o pipeline manualmente, você pode definir o valor do parâmetro succeed. A segunda etapa script no primeiro trabalho do pipeline avalia o parâmetro succeed e só é executada quando succeed é definido como false.

O segundo trabalho no pipeline tem uma dependência do primeiro trabalho e só é executado se o primeiro trabalho falhar. O segundo trabalho usa o comando az boards work-item create da CLI do Azure DevOps para criar um bug. Para obter mais informações sobre como executar comandos da CLI do Azure DevOps de um pipeline, confira Executar comandos em um pipeline do YAML.

Este exemplo usa dois trabalhos, mas essa mesma abordagem pode ser usada em várias fases.

Observação

Você também pode usar uma extensão do marketplace, como Criar bug na falha de versão, que tem suporte para pipelines de vários estágios do YAML.

Próximas etapas

Você aprendeu as noções básicas de personalização do pipeline. Em seguida, recomendamos que você aprenda mais sobre como personalizar um pipeline para o idioma usado:

• .NET Core
• Contêineres
• Go
• Java
• Node.js
• Python

Ou, para expandir seu pipeline de CI para um pipeline de CI/CD, inclua um trabalho de implantação com etapas para implantar seu aplicativo em um ambiente.

Para saber mais sobre os tópicos neste guia, confira Trabalhos, Tarefas, Catálogo de Tarefas, Variáveis, Gatilhos ou Solução de Problemas.

Para saber o que mais você pode fazer em pipelines do YAML, confira referência de esquema do YAML.