Condições do pipeline

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

Este artigo descreve as condições sob as quais um estágio, trabalho ou etapa do Azure Pipelines acontece e como especificar condições diferentes. Para ter acesso a mais contexto sobre estágios, trabalhos e etapas, consulte Principais conceitos do Azure Pipelines.

• Por padrão, um trabalho ou estágio acontecerá se ele não depender de nenhum outro trabalho ou estágio ou se todas as dependências forem concluídas sem erros. Esse requisito se aplica não apenas às dependências diretas, mas também às dependências indiretas, calculadas recursivamente.

• Por padrão, uma etapa acontece se nenhum erro ocorrer no trabalho e a etapa imediatamente anterior for concluída.

Você pode substituir ou personalizar esse comportamento ao especificar uma condição personalizada ou ao forçar a execução de um estágio, trabalho ou etapa, mesmo que uma dependência anterior falhe.

Condições sob as quais um estágio, trabalho ou etapa é executado

No YAML de definição de pipeline, você pode especificar as seguintes condições sob as quais um estágio, trabalho ou etapa é executado:

• Somente quando todas as dependências diretas e indiretas anteriores com o mesmo pool de agentes tiverem sido bem-sucedidas. Se houver pools de agentes diferentes, esses fases ou trabalhos serão executados simultaneamente. Esta condição é o padrão se nenhuma condição for definida no YAML.

• Mesmo que uma dependência anterior tenha falhado, a menos que a execução tenha sido cancelada. Use succeededOrFailed() no YAML para essa condição.

• Mesmo que uma dependência anterior tenha falhado, mesmo que a execução tenha sido cancelada. Use always() no YAML para essa condição.

• Somente quando uma dependência anterior tiver falhado. Use failed() no YAML para essa condição.

• Condições personalizadas.

Por padrão, estágios, trabalhos e etapas serão executados se todas as dependências diretas e indiretas tiverem êxito. Esse status é o mesmo que especificar condition: succeeded(). Para obter mais informações, consulte Função de status com êxito.

Ao especificar uma propriedade condition para um estágio, trabalho ou etapa, você substitui o padrão condition: succeeded(). Especificar suas próprias condições pode fazer com que seu estágio, trabalho ou etapa seja executado mesmo que a compilação seja cancelada. Certifique-se de que as condições gravadas levem em conta o estado do estágio ou trabalho pai.

O exemplo de YAML a seguir mostra as condições always() e failed(). A etapa no primeiro trabalho é executada mesmo se as dependências falharem ou se a compilação for cancelada. O segundo trabalho será executado somente se o primeiro falhar.

jobs:
- job: Foo

  steps:
  - script: echo Hello!
    condition: always() # this step runs, even if the build is canceled

- job: Bar
  dependsOn: Foo
  condition: failed() # this job runs only if Foo fails

Você também pode definir e usar variáveis em condições. O exemplo a seguir define e usa uma variável isMain para designar main como Build.SourceBranch.

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)

Condições personalizadas

Se as condições internas não atenderem às suas necessidades, é possível especificar condições personalizadas. Grave condições como expressões em definições do pipeline 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 booleano que determina se a tarefa, o trabalho ou o estágio deve ou não ser executado. Para ter acesso a um guia completo sobre sintaxe, consulte Expressões.

Se qualquer uma de suas condições possibilitar que a tarefa seja executada mesmo após o cancelamento da compilação, especifique um valor razoável de tempo-limite de cancelamento para que essas tarefas tenham tempo suficiente para serem concluídas depois que o usuário cancelar uma execução.

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

Cancelar uma compilação não significa que todos os estágios, trabalhos ou etapas vão parar de ser executados. Os estágios, trabalhos ou etapas que não serão mais executados dependerão das condições especificadas e em que ponto da execução do pipeline você cancelou a compilação. Se o pai de um estágio, trabalho ou etapa for ignorado, a tarefa não será executada, independentemente das condições.

Um estágio, trabalho ou etapa é executado sempre que as condições são avaliadas quanto ao true. Se sua condição não levar em conta o estado do pai da tarefa, a tarefa poderá ser executada mesmo que o pai seja cancelado. Para controlar se estágios, trabalhos ou etapas com condições serão executados quando uma compilação for cancelada, certifique-se de incluir uma função de verificação de status do trabalho em suas condições.

Os exemplos a seguir mostram os resultados de várias condições definidas em estágios, trabalhos ou etapas quando a compilação é cancelada.

Exemplo de estágio 1

No pipeline a seguir, por padrão, stage2 dependeria de stage1, mas stage2 tem um conjunto condition para ser executado sempre que a ramificação de origem for main, independentemente do status stage1.

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, stage2 depende de stage1 por padrão. O trabalho B em stage2 tem um conjunto condition. Se você enfileirar uma compilação na ramificação main e cancelá-la enquanto stage1 estiver em execução, stage2 não será executado, mesmo que ele contenha um trabalho cuja condição seja avaliada quanto a true.

O motivo é que stage2 tem o padrão condition: succeeded(), que é avaliado como false quando stage1 é cancelado. Portanto, stage2 é ignorado e nenhum de seus trabalhos é executado.

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, stage2 depende de stage1, e a etapa dentro do trabalho B tem um conjunto condition.

Se você enfileirar uma compilação na ramificação main e cancelá-la enquanto stage1 estiver em execução, stage2 não será executado, mesmo que contenha uma etapa no trabalho B cuja condição seja avaliada quanto a true. O motivo é que stage2 é ignorado em resposta ao cancelamento de stage1.

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')

Exemplo de trabalho 1

No pipeline YAML a seguir, o trabalho B depende do trabalho A por padrão, mas o trabalho B 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 o trabalho A estiver em execução, o trabalho B ainda será executado, pois 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 tiver êxito e a origem da compilação for a ramificação main, condition deverá ser and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')).

Exemplo de trabalho 2

No pipeline a seguir, o trabalho B depende do trabalho A por padrão. Se você enfileirar uma compilação na ramificação main e cancelá-la enquanto o trabalho A estiver em execução, o trabalho B não será executado, mesmo que sua etapa tenha um condition que seja avaliado como true.

O motivo é que o trabalho B tem o padrão condition: succeeded(), que é avaliado como false quando o trabalho A é cancelado. Portanto, o trabalho B é ignorado e nenhuma de suas etapas é executada.

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

Exemplo de etapa

Você também pode ter 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')

Configurações da condição

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

variables:
- name: testEmpty
  value: ''

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

Parâmetros em condições

A expansão de parâmetros ocorre antes que as condições sejam consideradas. Portanto, ao declarar um parâmetro no mesmo pipeline como uma condição, você pode incorporar o parâmetro na condição. O script no YAML a seguir é executado porque parameters.doThing é true.

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

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

O condition no pipeline anterior combina duas funções: succeeded() e ${{ eq(parameters.doThing, true) }}. A função succeeded() verifica se a etapa anterior foi bem-sucedida. A função succeeded() retorna true porque não havia nenhuma etapa anterior.

A função ${{ eq(parameters.doThing, true) }} verifica se o parâmetro doThing é igual a true. Como o valor padrão de doThing é true, a condição retorna true por padrão, a menos que o pipeline defina um valor diferente.

Parâmetros de modelo em condições

Ao passar um parâmetro para um modelo, você precisa definir o valor do parâmetro em seu modelo ou usar templateContext para passar o parâmetro para o modelo.

Por exemplo, o seguinte arquivo parameters.yml declara o parâmetro doThing e o valor padrão:

# parameters.yml
parameters:
- name: doThing
  default: true # value passed to the condition
  type: boolean

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

O código do pipeline faz referência ao modelo parameters.yml. A saída do pipeline é I did a thing porque o parâmetro doThing é true.

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

trigger:
- none

extends:
  template: parameters.yml

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

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

Você pode disponibilizar uma variável para trabalhos futuros e especificá-la em uma condição. As variáveis disponíveis para trabalhos futuros devem ser marcadas como variáveis de saída de vários trabalhos usando isOutput=true, como no código a seguir:

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

Variáveis criadas em uma etapa usada em condições de etapa subsequentes

Você pode criar uma variável disponível para etapas futuras para especificá-la em uma condição. As variáveis criadas com base nas etapas estão disponíveis para etapas futuras por padrão e não precisam ser marcadas como variáveis de saída de vários trabalhos.

Há algumas coisas importantes a serem observadas sobre variáveis de escopo criadas com base em etapas.

• As variáveis criadas em uma etapa em um trabalho terão como escopo as etapas no mesmo trabalho.
• As variáveis criadas em uma etapa serão disponibilizadas nas etapas subsequentes apenas como variáveis de ambiente.
• As variáveis criadas em uma etapa não podem ser usadas na etapa que as define.

O exemplo a seguir mostra a criação de uma variável de pipeline em uma etapa e o uso da variável na condição e no script de uma etapa subsequente.

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 is able to use doThing, so it 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'))

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. Por exemplo, no YAML a seguir, a condição eq(dependencies.A.result,'SucceededWithIssues') permite que o trabalho B seja executado porque o trabalho A teve êxito com problemas.

jobs:
- job: A
  displayName: Job A
  continueOnError: true # next job starts even if this one fails
  steps:
  - script: echo Job A ran
  - script: exit 1

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

Cancelei minha compilação, mas ela ainda está em execução. Por quê?

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.

Se você cancelar um trabalho enquanto ele estiver no estágio da fila, mas não estiver em execução, todo o trabalho será cancelado, incluindo todos os outros estágios. Para obter mais informações, consulte Resultados da condição quando uma compilação é cancelada acima neste artigo.

Conteúdo relacionado

• Especificar trabalhos no pipeline
• Adicionar estágios, dependências e condições