Conditions des pipelines

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

Cet article décrit les différentes conditions qui permettent à l’exécution d’une étape, d’un travail ou d’une étape Azure Pipelines et de la définition de ces conditions dans une définition de pipeline YAML.

Conditions d’exécution d’une étape, d’un travail ou d’une étape sous

Par défaut, un travail de pipeline ou une étape s’exécute s’il ne dépend d’aucun autre travail ou étape, ou si toutes ses dépendances sont terminées et réussies. L’exigence de dépendance s’applique aux dépendances directes et à 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é. Pour plus de contexte sur les étapes, tâches et segments, veuillez consulter la section Concepts clés pour Azure Pipelines.

Vous pouvez remplacer ou personnaliser ces comportements par défaut en définissant une étape, un travail ou une étape à exécuter, même si une dépendance précédente échoue ou a un autre résultat. Vous pouvez également définir des conditions personnalisées. Dans une définition de pipeline YAML, vous utilisez la condition propriété pour spécifier les conditions dans lesquelles une étape, un travail ou une étape peut s’exécuter.

Les conditions basées sur l’état de dépendance précédent sont les suivantes :

• Réussite : Exécutez uniquement si toutes les dépendances précédentes réussissent. Ce comportement est la valeur par défaut si aucune condition n’est définie dans yaML. Pour appliquer cette condition, spécifiez condition: succeeded().
• Réussite ou échec : Exécuter même si une dépendance précédente échoue, sauf si l’exécution est annulée. Pour appliquer cette condition, spécifiez condition: succeededOrFailed().
• Toujours : Exécutez même si une dépendance précédente échoue, même si l’exécution est annulée. Pour appliquer cette condition, spécifiez condition: always().
• Échec : Exécuter uniquement lorsqu’une dépendance précédente échoue. Pour appliquer cette condition, spécifiez condition: failed().

Exemple de condition

L’exemple YAML suivant illustre les conditions et always() les failed() conditions. La première tâche de script du travail 1 a une always condition. Elle s’exécute donc même si les dépendances échouent ou si la build est annulée. Dans la deuxième tâche de script, exit job1 force le job1 travail à échouer.

Les étapes de pipeline s’exécutent de manière séquentielle par défaut, mais les travaux peuvent s’exécuter en parallèle. Vous pouvez utiliser la dependsOn propriété pour définir explicitement des dépendances entre les étapes ou les travaux.

Pour définir les conditions d’un travail qui dépend du résultat d’un autre travail, utilisez cette option dependsOn pour définir la dépendance. Dans l’exemple suivant, job2 dépend job1 et s’exécute en raison job1 d’échecs.

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

Conditions personnalisées

Si les conditions intégrées ne répondent pas à vos besoins, vous pouvez spécifier des conditions personnalisées en tant qu’expressions dans les définitions de pipeline 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 s’il faut exécuter l’étape, le travail ou l’étape. Pour un guide complet de la syntaxe, veuillez consulter la section Expressions.

Variables dans les conditions

Vous pouvez définir des variables de pipeline et les utiliser dans des conditions. Le pipeline suivant définit une isMain variable et l’utilise dans une condition qui exécute l’étape B uniquement lorsque la branche source de build est 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)

Vous pouvez définir une condition à exécuter si une variable a la valeur Null ou une chaîne vide. Toutes les variables sont traitées comme des chaînes dans Azure Pipelines. Par conséquent, une chaîne vide est équivalente au null pipeline suivant :

variables:
- name: testEmpty
  value: ''

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

Variables de sortie de travail utilisées dans d’autres conditions de travail

Vous pouvez créer une variable dans un travail que d’autres travaux de la même étape peuvent spécifier dans des conditions. Les variables disponibles pour les travaux dépendants doivent être marquées comme variables de sortie à plusieurs travaux à l’aide isOutput=truede , comme dans le code suivant :

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

Variables d’étape utilisées dans les conditions d’étape suivantes

Vous pouvez créer une variable dans une étape que les étapes futures du même travail peuvent spécifier dans des conditions. Les variables créées à partir des étapes sont disponibles pour les futures étapes du travail par défaut et n’ont pas besoin d’être marquées comme variables de sortie à plusieurs travaux.

Les variables créées à une étape d’un travail présentent les limitations suivantes :

• Sont délimités aux étapes du même travail.
• Sont disponibles dans les étapes suivantes uniquement en tant que variables d’environnement.
• Impossible d’utiliser dans la même étape que celle qui les définit.

L’exemple suivant crée une variable de pipeline dans une étape et utilise la variable dans la condition de script d’une étape ultérieure.

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

Paramètres de condition pour différents résultats

Le tableau suivant présente condition les paramètres permettant de produire différents résultats souhaités.

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

L’annulation d’une build ne signifie pas que toutes ses étapes, travaux et étapes arrêtent de s’exécuter. Les travaux, étapes ou étapes qui arrêtent l’exécution dépendent des conditions que vous avez spécifiées et à quel point de l’exécution du pipeline vous avez annulé la génération. Si le parent d’une étape, d’un travail ou d’une étape est ignoré, l’étape, le travail ou l’étape ne s’exécute pas, quelles que soient ses conditions.

Une étape, une tâche ou un segment s’exécute chaque fois que ses conditions évaluent à true. Si une condition ne tient pas compte de l’état du parent de la tâche, elle peut s’exécuter même si son parent est annulé. Pour contrôler si les travaux, les étapes ou les étapes s’exécutent lorsqu’une build est annulée, incluez une fonction de vérification de l’état du travail dans vos conditions.

Si vous annulez une build pendant qu’elle se trouve dans la phase de file d’attente, mais qu’elle n’est pas encore en cours d’exécution, l’exécution entière est annulée, y compris toutes les autres étapes.

Exemples de résultats de condition d’étape

Les exemples suivants montrent les résultats de différentes conditions définies sur les phases lorsque la build est annulée.

Exemple d’étape 1

Dans le pipeline suivant, par défaut stage2 , dépend stage1 de l’exécution réussie. Toutefois, stage2 a un condition ensemble à exécuter chaque fois que la branche source est main, quel que soit l’état 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, par défaut stage2 , dépend de stage1 l’exécution réussie. Le travail B dans a stage2 un condition jeu à exécuter chaque fois que la branche source est main.

Si vous mettez en file d’attente une build sur la branche et annulez-la main pendant stage1 l’exécution, stage2 et que ses travaux ne s’exécutent pas du tout, même si l’étape contient un travail dont la condition est trueévaluée .

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 l’exécution réussie. L’étape à l’intérieur du travail B au sein stage2 d’un condition groupe doit s’exécuter chaque fois que la branche source est main.

Si vous mettez en file d’attente une build sur la branche et annulez-la main pendant stage1 l’exécution, stage2 et que le travail B ne s’exécute pas du tout, même si le travail B contient une étape dont la condition est évaluée true. Stage2 est ignoré entièrement parce qu’il stage1 a été annulé.

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

Exemples de résultats de condition de travail

Les exemples suivants montrent les résultats de différentes conditions définies sur les travaux lorsque la build est annulée.

Exemple de tâche 1

Dans le pipeline YAML suivant, l’exécution du travail B dépend de l’exécution du travail A . Le travail B a également un condition ensemble à 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 condition: 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 souhaitez que le travail s’exécute uniquement lorsque le travail BA réussit et que la source de build est main, vous devez définir la valeur conditionand(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))sur .

Exemple de tâche 2

Dans le pipeline YAML suivant, le travail B dépend de la réussite du travail A . Le travail B a un condition ensemble à exécuter chaque fois que le travail A réussit et que la branche source de build est main.

Si vous mettez en file d’attente une build sur la branche et annulez-la main pendant l’exécution du travail A , le travail B ne s’exécute pas, même s’il en a un condition qui est évalué à true. La condition sur le travail B est évaluée parce false que le travail A n’a pas réussi. Par conséquent, le travail B et ses étapes sont ignorés.

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

Exemple de résultat de la condition d’étape

Vous pouvez également définir des conditions sur les é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 dans les conditions

Vous pouvez utiliser des paramètres dans des conditions. L’expansion des paramètres se produit avant l’exécution du pipeline et remplace les valeurs entourées par ${{ }} les valeurs de paramètre littérales. Étant donné que l’expansion des paramètres se produit avant l’évaluation de la condition, vous pouvez déclarer un paramètre dans un pipeline et incorporer le paramètre à l’intérieur de n’importe quelle condition dans ce pipeline.

L’exemple condition suivant combine deux fonctions : succeeded() et ${{ eq(parameters.doThing, true) }}. La fonction succeeded() vérifie si l’étape précédente a réussi. Cette fonction retourne true également s’il n’y a pas d’étape précédente.

La fonction ${{ eq(parameters.doThing, true) }} vérifie si le paramètre doThing est égal à true. L’étape de script de l’exemple suivant s’exécute, car il n’y a pas eu d’étape précédente et parameters.doThing est true par défaut.

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

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

Paramètres de template dans les conditions

Lorsque vous passez un paramètre à un modèle de pipeline, vous pouvez définir la valeur du paramètre dans le fichier de modèle ou utiliser templateContext pour transmettre le paramètre au modèle.

Le fichier de modèle parameters.yml suivant déclare le doThing paramètre avec une valeur par défaut et true utilise le paramètre dans une condition de travail.

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

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

La définition de pipeline azure-pipelines.yml suivante fait référence au travail dans le fichier de modèle parameters.yml . La sortie du pipeline est I did a thing due au fait que le paramètre doThing a la valeur true par défaut.

# azure-pipelines.yml

extends:
  template: parameters.yml

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

Questions fréquentes (FAQ)

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. Dans le yaML suivant, la condition eq(dependencies.A.result,'SucceededWithIssues') définit le travail B à exécuter après la réussite du travail A avec des problèmes.

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

Pourquoi ma build est-elle toujours en cours d’exécution après l’avoir annulée ?

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. Pour plus d’informations, consultez Résultats de condition lorsqu’une build est annulée.

Contenu connexe

• Spécifier des travaux dans votre pipeline
• Ajouter des phases, des dépendances et des conditions
• Utiliser des paramètres de modèle