Personalizar o 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.

Compreender o azure-pipelines.yml ficheiro

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

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 para o pipeline.

Nota

Para obter instruções sobre como exibir e gerenciar seus pipelines no portal do Azure DevOps, consulte 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'

Nota

O conteúdo do seu 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 seu repositório ou cria uma solicitação pull. Ele é executado em uma máquina Linux hospedada pela Microsoft. O processo de pipeline tem uma única etapa, que é executar a tarefa Maven.

Altere a plataforma para desenvolver

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 que você precisa.

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

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

  pool:
    vmImage: "ubuntu-latest"
  

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

  pool:
    vmImage: "windows-latest"
  

  pool:
    vmImage: "macos-latest"
  

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

Adicionar passos

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

• Abra o editor YAML para seu pipeline.

• Adicione o seguinte trecho 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 visualizar os resultados da cobertura de teste e código selecionando sua compilação e indo para as guias Teste e Cobertura .

Crie em várias plataformas

Você pode criar e testar seu projeto em várias plataformas. Uma maneira 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 queremos usar.

• No seu azure-pipelines.yml ficheiro, 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 sua compilação executar até três trabalhos em três plataformas diferentes.

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

Crie usando várias versões

Para criar um projeto usando diferentes versões desse idioma, você pode usar uma matrix das versões e uma variável. Nesta etapa, você pode construir o projeto Java com duas versões diferentes do Java em uma única plataforma ou executar versões diferentes do Java em plataformas diferentes.

Nota

Não é possível usar strategy várias vezes em um contexto.

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

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

• Em seguida, substitua esta linha na sua tarefa maven:

  jdkVersionOption: "1.11"
  

  com esta linha:

  jdkVersionOption: $(jdkVersion)
  

• Certifique-se de alterar a $(imageName) variável de volta para a plataforma de sua escolha.

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

  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

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

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

  trigger:
    - main
    - releases/*
  

  pr:
    - main
    - releases/*
  

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

Definições do pipeline

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

• Gerir a segurança - Gerir a 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 todas as compilações e artefatos associados.
• Execuções - agendadas Vista 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 seguintes configurações.

• Processamento de novas solicitações de execução - Às vezes, você vai querer impedir que novas execuções comecem em seu pipeline.

  • Por padrão, o processamento de novas solicitações de execução é Habilitado. Essa configuração permite o processamento padrão de todos os tipos de gatilho, incluindo execuções manuais.
  • Os pipelines pausados permitem que as solicitações de execução sejam processadas, mas essas solicitações são enfileiradas sem realmente iniciar. Quando o processamento de novas solicitações estiver habilitado, o processamento de execução será retomado começando com a primeira solicitação na fila.
  • Os pipelines desativados impedem que os usuários iniciem novas execuções. Todos os gatilhos também são desativados enquanto essa configuração é aplicada. Todas as políticas de compilação que usam um pipeline desativado mostrarão a mensagem "Não é possível enfileirar compilação" ao lado da política de compilação na janela de visão geral de RP e o status da política de compilação será 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 pode ser útil se você precisar mover/renomear seu 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 a eles. Selecione esta opção para vincular esses itens de trabalho à execução. Quando a opção Vincular automaticamente os itens de trabalho incluídos nesta execução estiver selecionada, você deverá especificar uma ramificação específica ou * para todas as ramificações, que é o padrão. Se você especificar uma ramificação, os itens de trabalho serão associados apenas a execuções dessa ramificação. Se você especificar *, os itens de trabalho serão associados para todas as execuções.

  

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

Gerir a segurança

Você pode configurar a segurança de pipelines em um nível de projeto na página inicial Mais ações na página inicial de pipelines e em um nível de 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 interno, definir permissões individuais para um usuário ou grupo ou adicionar usuários a funções predefinidas. Você pode gerenciar a segurança do Azure Pipelines no portal da Web, a partir do contexto de usuário ou administrador. Para obter mais informações sobre como configurar a segurança de pipelines, consulte 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 falha , como os pipelines de compilação clássicos. Os pipelines de construção clássicos são de estágio único, e Criar item de trabalho em caso de falha se aplica a todo o pipeline. Os pipelines YAML podem ser de vários estágios, 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 a chamada Itens de Trabalho - Criar API REST ou o comando azur DevOps CLI az boards work-item create no ponto desejado em seu pipeline.

O exemplo a seguir tem dois trabalhos. O primeiro trabalho representa o trabalho do pipeline, mas se 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'

Nota

Os Painéis do Azure permitem configurar o acompanhamento de itens de trabalho usando vários processos diferentes, como Agile ou Basic. Cada processo tem diferentes tipos de item de trabalho, e nem todos os tipos de item de trabalho estão disponíveis em cada processo. Para obter uma lista dos tipos de item de trabalho suportados por cada processo, consulte Tipos de item de trabalho (WITs).

O exemplo anterior usa parâmetros de tempo de execução para configurar se o pipeline é bem-sucedido ou falha. Ao executar manualmente o pipeline, você pode definir o succeed valor do parâmetro. A segunda script etapa no primeiro trabalho do pipeline avalia o parâmetro e só é executada succeed quando succeed está definida 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 azur DevOps CLI az boards work-item create para criar um bug. Para obter mais informações sobre como executar comandos da CLI do Azure DevOps a partir de um pipeline, consulte Executar comandos em um pipeline YAML.

Este exemplo usa dois trabalhos, mas essa mesma abordagem pode ser usada em vários estágios.

Nota

Você também pode usar uma extensão de mercado como Create Bug on Release failure que tem suporte para pipelines de vários estágios YAML.

Próximos passos

Você aprendeu o básico para personalizar seu pipeline. Em seguida, recomendamos que você saiba mais sobre como personalizar um pipeline para o idioma usado:

• .NET Core
• Contentores
• Ir
• 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 deste guia, consulte Trabalhos, Tarefas, Catálogo de tarefas, Variáveis, Gatilhos ou Solução de problemas.

Para saber o que mais você pode fazer em pipelines YAML, consulte Referência de esquema YAML.