Condições do gasoduto

Serviços de DevOps do Azure | 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 é executado e como especificar condições diferentes. Para obter mais contexto sobre estágios, trabalhos e etapas, consulte Conceitos-chave para Pipelines do Azure.

• Por padrão, um trabalho ou estágio é 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. Este requisito aplica-se não só às dependências diretas, mas também às suas dependências indiretas, calculadas recursivamente.

• Por padrão, uma etapa é executada se nada em seu trabalho ainda falhou e a etapa imediatamente anterior foi concluída.

Você pode substituir ou personalizar esse comportamento forçando um estágio, trabalho ou etapa a ser executado, mesmo que uma dependência anterior falhe, ou especificando uma condição personalizada.

Condições em que um estágio, trabalho ou etapa é executado

Na definição de pipeline YAML, 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 forem bem-sucedidas. Se você tiver pools de agentes diferentes, esses estágios ou trabalhos serão executados simultaneamente. Esta condição é o padrão se nenhuma condição estiver definida no YAML.

• Mesmo que uma dependência anterior falhe, a menos que a execução seja cancelada. Use succeededOrFailed() no YAML para esta condição.

• Mesmo que uma dependência anterior falhe e mesmo que a execução seja cancelada. Use always() no YAML para esta condição.

• Apenas quando uma dependência anterior falha. Use failed() no YAML para esta condição.

• Condições personalizadas.

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

Ao especificar uma condition propriedade 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 se a compilação for cancelada. Certifique-se de que as condições que você escreve levam em conta o estado do estágio ou trabalho pai.

O exemplo YAML a seguir mostra as always() condições e failed() . A etapa no primeiro trabalho é executada mesmo se as dependências falharem ou a compilação for cancelada. O segundo trabalho é executado somente se o primeiro trabalho 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 isMain variável 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, você poderá especificar condições personalizadas. Você escreve condições como expressões em definições de pipeline YAML.

O agente avalia a expressão começando com a função mais interna e prosseguindo para fora. O resultado final é um valor booleano que determina se a tarefa, o trabalho ou o estágio deve ou não ser executado. Para obter um guia completo sobre a sintaxe, consulte Expressões.

Se qualquer uma das suas condições permitir que a tarefa seja executada mesmo depois que a compilação for cancelada, especifique um valor razoável para cancelar o tempo limite 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 seus estágios, trabalhos ou etapas parem de ser executados. Quais estágios, trabalhos 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, a tarefa não será executada, independentemente de suas condições.

Um estágio, trabalho ou etapa é executado sempre que suas condições avaliam a true. Se a 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 são executados quando uma compilação é 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 condition conjunto para ser executado sempre que a ramificação de origem for main, independentemente do stage1 status.

Se você enfileirar uma compilação na main ramificação e cancelá-la enquanto stage1 estiver em execução, stage2 ainda será executado, porque eq(variables['Build.SourceBranch'], 'refs/heads/main') avalia 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 estágio 2

No pipeline a seguir, stage2 depende por stage1 padrão. Job B in stage2 tem um condition conjunto. Se você enfileirar uma compilação na main ramificação e cancelá-la enquanto stage1 estiver em execução, stage2 ela não será executada, mesmo que ela contenha um trabalho cuja condição seja avaliada como true.

O motivo é porque stage2 tem o padrão condition: succeeded(), que avalia até 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 condition conjunto.

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

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 condition conjunto para ser executado sempre que a ramificação de origem for main. Se você enfileirar uma compilação na ramificação e cancelá-la enquanto o trabalho A estiver em execução, o main trabalho B ainda será executado, porque eq(variables['Build.SourceBranch'], 'refs/heads/main') avalia 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 fonte de compilação for a main ramificação, você condition deve 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 e cancelá-la enquanto o main trabalho A estiver em execução, o trabalho B não será executado, mesmo que sua etapa tenha um condition que avalia como true.

O motivo é porque o trabalho B tem o padrão condition: succeeded(), que avalia quando o false 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 passo

Você também pode ter condições sobre os degraus.

No pipeline a seguir, a etapa 2.3 tem um condition conjunto para ser executado sempre que a ramificação de origem for main. Se você enfileirar uma compilação na ramificação e cancelá-la enquanto as etapas 2.1 ou 2.2 estiverem em execução, a main 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')

Configurações de condição

A tabela a seguir mostra configurações de exemplo 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 do parâmetro acontece antes que as condições sejam consideradas. Portanto, quando você declara um parâmetro no mesmo pipeline como uma condição, você pode incorporar o parâmetro dentro da condição. O script no YAML a seguir é executado porque parameters.doThing é verdadeiro.

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

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

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

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

Parâmetros do 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 de parameters.yml declara o parâmetro e o doThing 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 de 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 obter mais exemplos de parâmetros de modelo, consulte a Referência de uso de 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 que está disponível para etapas futuras a serem especificadas em uma condição. As variáveis criadas a partir de 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 observar sobre as variáveis de escopo que são criadas a partir de etapas.

• As variáveis criadas em uma etapa em um trabalho têm como escopo as etapas no mesmo trabalho.
• As variáveis criadas em uma etapa estão disponíveis nas etapas subsequentes somente 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'))

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. 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 foi bem-sucedido 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

Eu cancelei minha compilação, mas ela ainda está em execução. Porquê?

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.

Se você cancelar um trabalho enquanto ele estiver no estágio de 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 anteriormente neste artigo.

Conteúdos relacionados

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