Conditions des pipelines

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

Cet article décrit les conditions dans lesquelles une étape, tâche ou segment Azure Pipelines s’exécute, et comment spécifier différentes conditions. Pour plus de contexte sur les étapes, tâches et segments, veuillez consulter la section Concepts clés pour Azure Pipelines.

• Par défaut, une tâche ou une étape s’exécute si elle ne dépend d’aucune autre tâche ou étape, ou si toutes ses dépendances sont terminées et réussies. Cette exigence s’applique non seulement aux dépendances directes, mais aussi à leurs dépendances indirectes, calculées de manière récursive.

• Par défaut, un segment s’exécute si aucune erreur n’a encore été rencontrée dans sa tâche et si le segment immédiatement précédent est terminé.

Vous pouvez remplacer ou personnaliser ce comportement en forçant une étape, une tâche ou un segment à s’exécuter, même si une dépendance précédente échoue, ou en spécifiant une condition personnalisée.

Conditions dans lesquelles une étape, tâche ou segment s’exécute

Dans la définition YAML du pipeline, vous pouvez spécifier les conditions suivantes pour qu’une étape, une tâche ou un segment s’exécute :

• Uniquement lorsque toutes les dépendances directes et indirectes précédentes avec le même pool d'agents réussissent. Si vous disposez de différents pools d'agents, ces étapes ou travaux s'exécutent simultanément. Cette condition est la condition par défaut si aucune condition n'est définie dans le YAML.

• Même si une dépendance précédente échoue, à moins que l'exécution ne soit annulée. Utilisez succeededOrFailed() dans le fichier YAML pour cette condition.

• Même si une dépendance précédente échoue, et même si l'exécution est annulée. Utilisez always() dans le fichier YAML pour cette condition.

• Uniquement en cas d'échec d'une dépendance précédente. Utilisez failed() dans le fichier YAML pour cette condition.

• Conditions personnalisées.

Par défaut, les étapes, tâches et segments s’exécutent si toutes les dépendances directes et indirectes réussissent. Ce statut est équivalent à la spécification condition: succeeded(). Pour plus d’informations, consultez la section Fonction du statut succeeded.

Lorsque vous spécifiez une propriété condition pour une étape, une tâche ou un segment, vous remplacez le comportement par défaut condition: succeeded(). Spécifier vos propres conditions peut faire en sorte que votre étape, tâche ou segment s’exécute même si la build est annulée. Assurez-vous que les conditions que vous écrivez tiennent compte de l’état de l’étape ou de la tâche parente.

L’exemple YAML suivant montre les conditions always() et failed(). Le segment dans la première tâche s’exécute même si des dépendances échouent ou si la build est annulée. La deuxième tâche ne s’exécute que si la première tâche échoue.

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

Vous pouvez également définir et utiliser des variables dans les conditions. L’exemple suivant définit et utilise une variable isMain pour désigner main comme 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)

Conditions personnalisées

Si les conditions intégrées ne répondent pas à vos besoins, vous pouvez spécifier des conditions personnalisées. Vous rédigez les conditions sous forme d’expressions dans les définitions de pipelines YAML.

L’agent évalue l’expression en commençant par la fonction la plus interne et en procédant vers l’extérieur. Le résultat final est une valeur booléenne qui détermine si la tâche, la tâche ou l’étape doit s’exécuter. Pour un guide complet de la syntaxe, veuillez consulter la section Expressions.

Si l’une de vos conditions permet que la tâche s’exécute même après l’annulation de la build, spécifiez une valeur raisonnable pour le délai d’annulation afin que ces tâches aient suffisamment de temps pour se terminer après l’annulation de l’exécution par l’utilisateur.

Résultats des conditions lorsque une build est annulée

Annuler une build ne signifie pas que toutes ses étapes, tâches ou segments s’arrêtent. Quelles étapes, tâches ou segments s’arrêtent dépendent des conditions que vous avez spécifiées, et du point d’exécution du pipeline où vous avez annulé la build. Si une étape, tâche ou segment parente est ignorée, la tâche ne s’exécute pas, quelle que soit sa condition.

Une étape, une tâche ou un segment s’exécute chaque fois que ses conditions évaluent à true. Si votre condition ne tient pas compte de l’état de la tâche parente, la tâche pourrait s’exécuter même si sa parente est annulée. Pour contrôler si les étapes, tâches ou segments avec des conditions s’exécutent lorsqu’une build est annulée, assurez-vous d’inclure une fonction de vérification du statut de la tâche dans vos conditions.

Les exemples suivants montrent les résultats de diverses conditions définies sur des étapes, tâches ou segments lorsque la build est annulée.

Exemple d’étape 1

Dans le pipeline suivant, par défaut stage2 dépendrait de stage1, mais stage2 a une condition définie pour s’exécuter chaque fois que la branche source est main, indépendamment du statut de stage1.

Si vous lancez une build sur la branche main et l’annulez pendant que stage1 est en cours d’exécution, stage2 s’exécute toujours, car eq(variables['Build.SourceBranch'], 'refs/heads/main') évalue à 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

Exemple d’étape 2

Dans le pipeline suivant, stage2 dépend de stage1 par défaut. La tâche B dans stage2 a une condition définie. Si vous lancez une build sur la branche main et l’annulez pendant que stage1 est en cours d’exécution, stage2 ne s’exécute pas, même si elle contient une tâche dont la condition évalue à true.

La raison est que stage2 a la valeur par défaut condition: succeeded(), qui prend la valeur false quand stage1 est annulé. Par conséquent, stage2 est ignoré et aucun de ses travaux ne s’exécute.

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

Exemple d’étape 3

Dans le pipeline suivant, par défaut stage2 dépend de stage1, et le segment à l’intérieur de la tâche B a une condition définie.

Si vous lancez une build sur la branche main et l’annulez pendant que stage1 est en cours d’exécution, stage2 ne s’exécute pas, même si elle contient un segment dans la tâche B dont la condition évalue à true. La raison est que stage2 est ignoré en réponse à l’annulation 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')

Exemple de tâche 1

Dans le pipeline YAML suivant, la tâche B dépend de la tâche A par défaut, mais la tâche B a une condition définie pour s’exécuter chaque fois que la branche source est main. Si vous lancez une build sur la branche main et l’annulez pendant que la tâche A est en cours d’exécution, la tâche B s’exécute toujours, car eq(variables['Build.SourceBranch'], 'refs/heads/main') évalue à 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

Si vous voulez que la tâche B s’exécute uniquement lorsque la tâche A réussit et que la source de la build est la branche main, votre condition doit être and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')).

Exemple de tâche 2

Dans le pipeline suivant, la tâche B dépend de la tâche A par défaut. Si vous lancez une build sur la branche main et l’annulez pendant que la tâche A est en cours d’exécution, la tâche B ne s’exécute pas, même si son segment a une condition qui évalue à true.

La raison est que le travail B a la valeur par défaut condition: succeeded(), qui prend la valeur false quand le travail A est annulé. Par conséquent, le travail B est ignoré et aucune de ses étapes ne s’exécute.

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

Exemple de segment

Vous pouvez également avoir des conditions sur des étapes.

Dans le pipeline suivant, le segment 2.3 a une condition définie pour s’exécuter chaque fois que la branche source est main. Si vous lancez une build sur la branche main et l’annulez pendant que les segments 2.1 ou 2.2 sont en cours d’exécution, le segment 2.3 s’exécute toujours, car eq(variables['Build.SourceBranch'], 'refs/heads/main') évalue à 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')

Paramètres de conditions

Le tableau suivant montre des exemples de paramètres condition pour produire divers résultats.

variables:
- name: testEmpty
  value: ''

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

Paramètres dans les conditions

L’expansion des paramètres se produit avant que les conditions ne soient prises en compte. Ainsi, lorsque vous déclarez un paramètre dans le même pipeline qu’une condition, vous pouvez intégrer le paramètre dans la condition. Le script dans le YAML suivant s’exécute car parameters.doThing est vrai.

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

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

Le condition dans le pipeline précédent combine deux fonctions : succeeded() et ${{ eq(parameters.doThing, true) }}. La fonction succeeded() vérifie si l’étape précédente a réussi. La fonction succeeded() renvoie true car il n’y avait pas d’étape précédente.

La fonction ${{ eq(parameters.doThing, true) }} vérifie si le paramètre doThing est égal à true. Comme la valeur par défaut pour doThing est true, la condition renvoie true par défaut sauf si le pipeline définit une valeur différente.

Paramètres de template dans les conditions

Lorsque vous transmettez un paramètre à un template, vous devez soit définir la valeur du paramètre dans votre template soit utiliser templateContext pour passer le paramètre au template.

Par exemple, le fichier parameters.yml suivant déclare le paramètre doThing et une valeur par défaut :

# 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) }}

Le code du pipeline fait référence au template parameters.yml. La sortie du pipeline est I did a thing car le paramètre doThing est vrai.

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

trigger:
- none

extends:
  template: parameters.yml

Pour plus d’exemples de paramètres de template, consultez la Référence d’utilisation des templates.

Variables de sortie de tâche utilisées dans les conditions de tâches suivantes

Vous pouvez rendre une variable disponible pour de futurs travaux et la spécifier dans une condition. Les variables disponibles pour les tâches futures doivent être marquées comme variables de sortie multi-tâches en utilisant isOutput=true, comme dans le code suivant :

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."

Variables créées dans un segment utilisé dans les conditions de segments suivants

Vous pouvez créer une variable disponible pour les segments futurs à spécifier dans une condition. Les variables créées à partir de segments sont disponibles pour les segments futurs par défaut et n’ont pas besoin d’être marquées comme variables de sortie multi-tâches.

Il y a des choses importantes à noter concernant l’étendue des variables créées à partir de segments.

• Les variables créées dans un segment d’une tâche sont limitées aux segments de la même tâche.
• Les variables créées dans un segment sont disponibles dans les segments suivants uniquement en tant que variables d’environnement.
• Les variables créées dans une étape ne peuvent pas être utilisées dans l’étape qui les définit.

L’exemple suivant montre comment créer une variable de pipeline dans un segment et utiliser cette variable dans la condition et le script d’un segment suivant.

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

Forum aux questions

Comment déclencher un travail si un travail précédent a réussi avec des problèmes ?

Vous pouvez utiliser le résultat de la tâche précédente dans une condition. Par exemple, dans le YAML suivant, la condition eq(dependencies.A.result,'SucceededWithIssues') permet à la tâche B de s’exécuter car la tâche A a réussi avec des problèmes.

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

J’ai annulé ma build, mais elle est toujours en cours d’exécution. Pourquoi ?

Vous pouvez rencontrer ce problème si une condition configurée dans une étape n’inclut pas une fonction de vérification du statut de la tâche. Pour résoudre le problème, ajoutez une fonction de vérification de l’état du travail à la condition.

Si vous annulez une tâche alors qu’elle est dans l’étape de mise en file d’attente mais non en cours d’exécution, toute la tâche est annulée, y compris toutes les autres étapes. Pour plus d’informations, consultez la section Résultats des conditions lorsque une build est annulée plus haut dans cet article.

Contenu connexe

• Spécifier des travaux dans votre pipeline
• Ajouter des phases, des dépendances et des conditions