Condições do gasoduto

Serviços de DevOps do Azure | 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, trabalho ou etapa é executado

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

Por padrão, uma etapa é executada se ainda nada no seu trabalho falhou e a etapa imediatamente anterior terminou. Para obter mais contexto sobre estágios, trabalhos e etapas, consulte Conceitos-chave para Pipelines do Azure.

Você pode substituir ou personalizar esses comportamentos padrão definindo um estágio, trabalho ou etapa para ser executado, mesmo se ou somente se uma dependência anterior falhar ou tiver 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 baseadas no status de dependência anterior incluem:

• Êxito: execute somente se todas as dependências anteriores forem bem-sucedidas. Esse comportamento é o padrão se nenhuma condição estiver definida no YAML. Para aplicar essa condição, especifique condition: succeeded().
• Êxito ou 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: Executar 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 always() condições e failed() . A primeira tarefa de script no trabalho 1 tem uma always condição, portanto, é executada mesmo se as dependências falharem ou a compilação for cancelada. Na segunda tarefa de script, exit job1 provoca a falha do job1 processo.

Os estágios do 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 dependências entre estágios ou trabalhos.

Para definir as condições para um trabalho que depende do resultado de outro trabalho, use dependsOn para definir a dependência. No exemplo a seguir, job2 depende e job1 é 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 YAML.

O agente avalia a expressão começando pela função mais interna e depois para as funções exteriores. O resultado final é um valor booleano que determina se o estágio, o trabalho ou a etapa deve ou não ser executado. Para obter um guia completo sobre a 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 a ramificação de origem da compilação é 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 para 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 , como isOutput=trueno 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. As 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 de um trabalho têm as seguintes limitações:

• Têm como escopo 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 uma compilação 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 a compilação. Se o pai de um estágio, trabalho ou etapa for ignorado, o estágio, trabalho ou etapa não será executado, independentemente de suas condições.

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

Se você cancelar uma compilação enquanto ela estiver no estágio de fila, mas ainda não estiver em execução, toda a execução será cancelada, incluindo todos os outros estágios.

Exemplo de resultados da condição do estágio

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

Exemplo de estágio 1

No pipeline seguinte, por padrão stage2 , dependeria da stage1 conclusão bem-sucedida. No entanto, stage2 tem um condition conjunto para ser executado sempre que a ramificação de origem for main, independentemente do stage1 status.

Se enfileirarem uma compilação na ramificação main e cancelarem-na enquanto stage1 estiver em execução, stage2 ainda será executado, porque eq(variables['Build.SourceBranch'], 'refs/heads/main') é avaliado como 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 etapa 2

No pipeline a seguir, por padrão stage2 , depende da stage1 conclusão bem-sucedida. Job B in tem um stage2 conjunto para ser executado sempre que a ramificação de origem for conditionmain .

Se você enfileirar uma compilação na main ramificação e cancelá-la enquanto stage1 estiver em execução, e seus trabalhos não forem executados, stage2 mesmo que o estágio contenha um trabalho cuja condição seja avaliada como true.

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 fase 3

No pipeline a seguir, por padrão stage2 , depende da stage1 conclusão bem-sucedida. A etapa dentro do trabalho B tem stage2 um condition conjunto para ser executado sempre que a ramificação de origem for main.

Se você enfileirar uma compilação na main ramificação e cancelá-la enquanto stage1 estiver em execução, stage2 e o trabalho B não for executado, mesmo que o trabalho B contenha uma etapa cuja condição seja avaliada como true. Stage2 é ignorado inteiramente 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')

Exemplo de resultados de condições de trabalho

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

Exemplo de trabalho 1

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

Se uma compilação for enfileirada na ramificação main e for cancelada enquanto o trabalho A estiver em execução, o trabalho B ainda será executado, porque condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') é avaliado como 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 da compilação 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 para ser executado sempre que o trabalho A for bem-sucedido e a ramificação de origem da compilação for main.

Se você enfileirar uma compilação na ramificação e cancelá-la enquanto o trabalho estiver em execução, o main trabalho A não será executado, mesmo que tenha um B que seja avaliado como condition.true A condição no trabalho B avalia porque false o trabalho A não teve sucesso. 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 em etapas. No pipeline a seguir, a etapa 2.3 tem um condition definido para executar sempre que a ramificação de origem for main.

Se enfileirares uma compilação na ramificação main e a cancelares enquanto as etapas 2.1 ou 2.2 estiverem a decorrer, a etapa 2.3 ainda será executada, porque eq(variables['Build.SourceBranch'], 'refs/heads/main') avalia como 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 de parâmetros acontece antes da execução do pipeline e substitui os valores cercados pelos ${{ }} valores literais dos parâmetros. Como a expansão de parâmetros ocorre antes da avaliação da condição, você pode declarar um parâmetro em um pipeline e incorporar 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 succeeded() função verifica se a etapa anterior foi bem-sucedida. Esta função também retorna true se não houver nenhuma etapa anterior.

A ${{ eq(parameters.doThing, true) }} função verifica se o doThing parâmetro é 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 do template 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 de parameters.yml a seguir declara o doThing parâmetro com um valor padrão de e usa o parâmetro em uma condição de true 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 de azure-pipelines.yml a seguir faz referência ao trabalho no arquivo de modelo parameters.yml . A saída do pipeline é I did a thing porque o parâmetro doThing é true por padrão.

# azure-pipelines.yml

extends:
  template: parameters.yml

Para obter mais exemplos de parâmetros de modelo, consulte a Referência de uso de modelo.

FAQ

Como poderei acionar um trabalho se um trabalho anterior tiver sido concluído 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 para ser executado após o trabalho A ser bem-sucedido 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 minha compilação ainda está em execução depois que eu a cancelei?

Você pode enfrentar 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 Resultados da condição quando uma compilação é cancelada.

Conteúdos relacionados

• Especifique trabalhos na sua pipeline
• Adicionar estágios, dependências e condições
• Usar parâmetros de modelo