Condições do pipeline

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Este artigo descreve as diferentes condições que permitem que um estágio, trabalho ou etapa do Azure Pipelines seja executado e como definir essas condições em uma definição de pipeline yaml.

Condições em que um estágio, um trabalho ou uma etapa são executados em

Por padrão, um trabalho de pipeline ou estágio é executado se ele não depende de nenhum outro trabalho ou estágio ou se todas as suas dependências foram concluídas e bem-sucedidas. O requisito de dependência se aplica a dependências diretas e a suas dependências indiretas, computadas recursivamente.

Por padrão, uma etapa acontece se nenhum erro ocorrer no trabalho e a etapa imediatamente anterior for concluída. Para ter acesso a mais contexto sobre estágios, trabalhos e etapas, consulte Principais conceitos do Azure Pipelines.

Você pode substituir ou personalizar esses comportamentos padrão definindo um estágio, um trabalho ou uma etapa para ser executado mesmo que uma dependência anterior falhe ou tenha outro resultado. Você também pode definir condições personalizadas. Em uma definição de pipeline yaml, você usa a condition propriedade para especificar condições sob as quais um estágio, trabalho ou etapa pode ser executado.

As condições com base no status de dependência anterior incluem:

• Bem-sucedido: execute somente se todas as dependências anteriores tiverem êxito. Esse comportamento será o padrão se nenhuma condição for definida no YAML. Para aplicar essa condição, especifique condition: succeeded().
• Bem-sucedido ou com falha: execute mesmo se uma dependência anterior falhar, a menos que a execução seja cancelada. Para aplicar essa condição, especifique condition: succeededOrFailed().
• Sempre: execute mesmo se uma dependência anterior falhar, mesmo que a execução seja cancelada. Para aplicar essa condição, especifique condition: always().
• Falha: execute somente quando uma dependência anterior falhar. Para aplicar essa condição, especifique condition: failed().

Exemplo de condição

O exemplo yaml a seguir demonstra as condições e always() as failed() condições. A primeira tarefa de script no trabalho 1 tem uma always condição, portanto, ela é executada mesmo se as dependências falharem ou se o build for cancelado. Na segunda tarefa de script, exit job1 força o trabalho job1 a falhar.

Os estágios de pipeline são executados sequencialmente por padrão, mas os trabalhos podem ser executados em paralelo. Você pode usar a dependsOn propriedade para definir explicitamente as dependências entre estágios ou trabalhos.

Para definir as condições de um trabalho que depende do resultado de outro trabalho, use dependsOn para definir a dependência. No exemplo a seguir, job2 depende job1 e é executado porque job1 falha.

jobs:
- job: job1
  steps:
  - script: echo Hello!
    condition: always() # this step runs even if the build is canceled
  - script: |
      echo "This task will fail."
      exit job1 
- job: job2
  dependsOn: job1
  condition: failed() # this job runs only if job1 fails

Condições personalizadas

Se as condições internas não atenderem às suas necessidades, você poderá especificar condições personalizadas como expressões nas definições de pipeline do YAML.

O agente avalia a expressão começando com a função mais interna e prosseguindo para o exterior. O resultado final é um valor booliano que determina se o estágio, o trabalho ou a etapa devem ou não ser executados. Para ter acesso a um guia completo sobre sintaxe, consulte Expressões.

Variáveis em condições

Você pode definir variáveis de pipeline e usá-las em condições. O pipeline a seguir define uma isMain variável e a usa em uma condição que executa o Estágio B somente quando o branch de origem de build é main.

variables:
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]

stages:
- stage: A
  jobs:
  - job: A1
    steps:
      - script: echo Hello Stage A!
- stage: B
  condition: and(succeeded(), eq(variables.isMain, true))
  jobs:
  - job: B1
    steps:
      - script: echo Hello Stage B!
      - script: echo $(isMain)

Você pode definir uma condição a ser executada se uma variável for nula ou uma cadeia de caracteres vazia. Todas as variáveis são tratadas como cadeias de caracteres no Azure Pipelines, portanto, uma cadeia de caracteres vazia é equivalente ao null seguinte pipeline:

variables:
- name: testEmpty
  value: ''

jobs:
  - job: A
    steps:
    - script: echo testEmpty is blank
    condition: eq(variables.testEmpty, '')

Variáveis de saída de trabalho usadas em outras condições de trabalho

Você pode criar uma variável em um trabalho que outros trabalhos no mesmo estágio podem especificar em condições. As variáveis disponíveis para trabalhos dependentes devem ser marcadas como variáveis de saída de vários trabalhos usando isOutput=true, como no código a seguir:

jobs:
- job: A
  steps:
  - bash: |
      echo "This is job A."
      echo "##vso[task.setvariable variable=doThing;isOutput=true]Yes" #set variable doThing to Yes
    name: DetermineResult
- job: B
  dependsOn: A
  condition: eq(dependencies.A.outputs['DetermineResult.doThing'], 'Yes') #map doThing and check the value
  steps:
  - script: echo "Job A ran and doThing is Yes."

Variáveis de etapa usadas em condições de etapa subsequentes

Você pode criar uma variável em uma etapa que as etapas futuras no mesmo trabalho podem especificar em condições. Variáveis criadas a partir de etapas estão disponíveis para etapas futuras no trabalho por padrão e não precisam ser marcadas como variáveis de saída de vários trabalhos.

As variáveis criadas em uma etapa em um trabalho têm as seguintes limitações:

• São definidos como escopo para as etapas no mesmo trabalho.
• Estão disponíveis nas etapas subsequentes apenas como variáveis de ambiente.
• Não pode ser usado na mesma etapa que os define.

O exemplo a seguir cria uma variável de pipeline em uma etapa e usa a variável na condição de script de uma etapa posterior.

steps:

# This step creates a new pipeline variable: doThing. This variable is available to subsequent steps.
- bash: |
    echo "##vso[task.setvariable variable=doThing]Yes"
  displayName: Step 1

# This step uses doThing in its condition
- script: |
    # Access the variable from Step 1 as an environment variable.
    echo "Value of doThing (as DOTHING env var): $DOTHING."
  displayName: Step 2
  condition: and(succeeded(), eq(variables['doThing'], 'Yes')) # or and(succeeded(), eq(variables.doThing, 'Yes'))

Configurações de condição para vários resultados

A tabela a seguir mostra condition as configurações para produzir vários resultados desejados.

Resultados da condição quando uma compilação é cancelada

Cancelar um build não significa que todos os seus estágios, trabalhos e etapas parem de ser executados. Quais trabalhos, estágios ou etapas param de ser executados dependem das condições especificadas e em que ponto da execução do pipeline você cancelou o build. Se um estágio, trabalho ou pai da etapa for ignorado, o estágio, o trabalho ou a etapa não serão executados, independentemente de suas condições.

Um estágio, trabalho ou etapa é executado sempre que as condições são avaliadas quanto ao true. Se uma condição não considerar o estado do pai da tarefa, a tarefa poderá ser executada mesmo se seu pai for cancelado. Para controlar se trabalhos, estágios ou etapas são executados quando um build é cancelado, inclua uma função de verificação de status do trabalho em suas condições.

Se você cancelar um build enquanto ele estiver no estágio da fila, mas ainda não estiver em execução, toda a execução será cancelada, incluindo todos os outros estágios.

Resultados de condição de estágio de exemplo

Os exemplos a seguir mostram os resultados de várias condições definidas em estágios quando o build é cancelado.

Exemplo de fase 1

No pipeline a seguir, por padrão, dependeria da stage2 conclusão com êxitostage1. No entanto, stage2 tem um condition conjunto a ser executado sempre que o branch de origem for main, independentemente do stage1 status.

Se você enfileirar uma compilação na ramificação main e cancelá-la enquanto stage1 estiver em execução, stage2 ainda será executado, pois eq(variables['Build.SourceBranch'], 'refs/heads/main') fará uma avaliação quanto a true.

stages:
- stage: stage1
  jobs:
  - job: A
    steps:
      - script: echo 1; sleep 30
- stage: stage2
  condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
  jobs:
  - job: B
    steps:
      - script: echo 2

Exemplo de estágio 2

No pipeline a seguir, por padrão, depende stage2 da conclusão com êxitostage1. O trabalho B tem stage2 um condition conjunto a ser executado sempre que o branch de origem for main.

Se você enfileirar um build no main branch e cancelá-lo enquanto stage1 estiver em execução e stage2 seus trabalhos não forem executados, mesmo que o estágio contenha um trabalho cuja condição seja avaliada truecomo .

stages:
- stage: stage1
  jobs:
  - job: A
    steps:
      - script: echo 1; sleep 30
- stage: stage2
  jobs:
  - job: B
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
    steps:
      - script: echo 2

Exemplo de estágio 3

No pipeline a seguir, por padrão, depende stage2 da conclusão com êxitostage1. A etapa dentro do trabalho B tem stage2 um condition conjunto a ser executado sempre que o branch de origem for main.

Se você enfileirar um build no main branch e cancelá-lo enquanto stage1 estiver em execução e stage2 o trabalho B não for executado, mesmo que o trabalho B contenha uma etapa cuja condição é avaliada truecomo . Stage2 é totalmente ignorado porque stage1 foi cancelado.

stages:
- stage: stage1
  jobs:
  - job: A
    steps:
      - script: echo 1; sleep 30
- stage: stage2
  jobs:
  - job: B
    steps:
      - script: echo 2
        condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

Resultados de condição de trabalho de exemplo

Os exemplos a seguir mostram os resultados de várias condições definidas em trabalhos quando o build é cancelado.

Exemplo de trabalho 1

No pipeline YAML a seguir, a execução do trabalho B depende da execução do trabalho A . O trabalho B também tem um condition conjunto a ser executado sempre que o branch de origem for main.

Se você enfileirar uma compilação na ramificação main e cancelá-la enquanto o trabalho A estiver em execução, o trabalho B ainda será executado, pois condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') será avaliado quanto a true.

jobs:
- job: A
  steps:
  - script: sleep 30
- job: B
  dependsOn: A 
  condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
  steps:
    - script: echo step 2.1

Se você quiser que o trabalho B seja executado somente quando o trabalho A for bem-sucedido e a origem do build for main, você deverá definir como conditionand(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')).

Exemplo de trabalho 2

No pipeline YAML a seguir, o trabalho B depende do sucesso do trabalho A . O trabalho B tem um condition conjunto a ser executado sempre que o trabalho A for bem-sucedido e o branch de origem de build for main.

Se você enfileirar um build no main branch e cancelá-lo enquanto o trabalho A estiver em execução, o trabalho B não será executado, mesmo que ele tenha um condition que seja avaliado como true. A condição no trabalho B é false avaliada como porque o trabalho A não foi bem-sucedido. Portanto, o trabalho B e suas etapas são ignorados.

jobs:
- job: A
  steps:
  - script: sleep 30
- job: B
  dependsOn: A 
  steps:
    - script: echo step 2.1
  condition: and(eq(variables['Build.SourceBranch'], 'refs/heads/main'), succeeded())

Exemplo de resultado da condição da etapa

Você também pode definir condições nas etapas. No pipeline a seguir, a etapa 2.3 tem um conjunto condition que será executado sempre que a ramificação de origem for main.

Se você enfileirar uma compilação na ramificação main e cancelá-la enquanto as etapas 2.1 ou 2.2 estiverem em execução, a etapa 2.3 ainda será executada, porque eq(variables['Build.SourceBranch'], 'refs/heads/main') é avaliado quanto a true.

steps:
  - script: echo step 2.1
  - script: echo step 2.2; sleep 30
  - script: echo step 2.3
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

Parâmetros em condições

Você pode usar parâmetros em condições. A expansão do parâmetro ocorre antes da execução do pipeline e substitui os valores cercados pelos ${{ }} valores de parâmetro literal. Como a expansão do parâmetro ocorre antes da avaliação da condição, você pode declarar um parâmetro em um pipeline e inserir o parâmetro dentro de qualquer condição nesse pipeline.

O condition exemplo a seguir combina duas funções: succeeded() e ${{ eq(parameters.doThing, true) }}. A função succeeded() verifica se a etapa anterior foi bem-sucedida. Essa função também retornará true se não houver nenhuma etapa anterior.

A função ${{ eq(parameters.doThing, true) }} verifica se o parâmetro doThing é igual a true. A etapa de script no exemplo a seguir é executada porque não havia nenhuma etapa anterior e parameters.doThing é true por padrão.

parameters:
- name: doThing
  default: true
  type: boolean

steps:
- script: echo I did a thing
  condition: and(succeeded(), ${{ eq(parameters.doThing, true) }})

Parâmetros de modelo em condições

Ao passar um parâmetro para um modelo de pipeline, você pode definir o valor do parâmetro no arquivo de modelo ou usar templateContext para passar o parâmetro para o modelo.

O arquivo de modelo parameters.yml a seguir declara o doThing parâmetro com um valor true padrão e usa o parâmetro em uma condição de trabalho.

# parameters.yml
parameters:
- name: doThing
  default: true
  type: boolean

jobs:
  - job: B
    steps:
    - script: echo I did a thing
    condition: ${{ eq(parameters.doThing, true) }}

A definição de pipeline azure-pipelines.yml a seguir faz referência ao trabalho no arquivo de modelo parameters.yml . A saída do pipeline ocorre I did a thing porque o parâmetro doThing é verdadeiro por padrão.

# azure-pipelines.yml

extends:
  template: parameters.yml

Para mais exemplos de parâmetro de modelo, confira Referência de uso do modelo.

perguntas frequentes

Como posso disparar um trabalho se um trabalho anterior concluir com problemas?

Você pode usar o resultado do trabalho anterior em uma condição. No YAML a seguir, a condição eq(dependencies.A.result,'SucceededWithIssues') define o trabalho B a ser executado após o trabalho A ter êxito com problemas.

jobs:
- job: A
  steps:
  - script: echo Job A ran
- job: B
  dependsOn: A
  condition: eq(dependencies.A.result,'SucceededWithIssues') # targets the result of the previous job 
  steps:
  - script: echo Job A had issues

Por que meu build ainda está em execução depois que eu cancelei?

Você pode ter esse problema se uma condição configurada em um estágio não incluir uma função de verificação de status do trabalho. Para resolver o problema, adicione uma função de verificação de status do trabalho à condição. Para obter mais informações, consulte Os resultados da condição quando um build é cancelado.

Conteúdo relacionado

• Especifique tarefas no seu pipeline
• Adicionar estágios, dependências e condições
• Usar parâmetros de modelo