Pipelinebedingungen

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

In diesem Artikel werden die verschiedenen Bedingungen beschrieben, mit denen eine Azure Pipelines-Phase, ein Auftrag oder ein Schritt ausgeführt werden kann und wie Sie diese Bedingungen in einer YAML-Pipelinedefinition festlegen.

Bedingungen, unter der eine Phase, ein Auftrag oder ein Schritt ausgeführt wird

Standardmäßig wird ein Pipelineauftrag oder eine Pipelinephase ausgeführt, wenn er nicht von einem anderen Auftrag oder einer anderen Phase abhängt oder ob alle Abhängigkeiten abgeschlossen und erfolgreich waren. Die Abhängigkeitsanforderung gilt für direkte Abhängigkeiten und für ihre indirekten Abhängigkeiten, die rekursiv berechnet werden.

Schritte werden standardmäßig ausgeführt, wenn im zugehörigen Auftrag noch kein Fehler aufgetreten ist und der unmittelbar vorangehende Schritt abgeschlossen wurde. Mehr Kontext zu Phasen, Aufträgen und Schritten finden Sie unter Wichtige Konzepte für Azure Pipelines.

Sie können diese Standardverhalten außer Kraft setzen oder anpassen, indem Sie eine Phase, einen Auftrag oder einen Schritt festlegen, der ausgeführt werden soll, auch wenn eine vorherige Abhängigkeit fehlschlägt oder ein anderes Ergebnis hat. Sie können auch benutzerdefinierte Bedingungen definieren. In einer YAML-Pipelinedefinition verwenden Sie die condition Eigenschaft, um Bedingungen anzugeben, unter denen eine Phase, ein Auftrag oder ein Schritt ausgeführt werden kann.

Zu den Bedingungen, die auf dem vorherigen Abhängigkeitsstatus basieren, gehören:

• Erfolgreich: Nur ausgeführt, wenn alle vorherigen Abhängigkeiten erfolgreich sind. Dieses Verhalten ist die Standardeinstellung, wenn keine Bedingung im YAML festgelegt ist. Geben Sie condition: succeeded()an, um diese Bedingung anzuwenden.
• Erfolgreich oder fehlgeschlagen: Führen Sie die Ausführung auch dann aus, wenn eine vorherige Abhängigkeit fehlschlägt, es sei denn, die Ausführung wird abgebrochen. Geben Sie condition: succeededOrFailed()an, um diese Bedingung anzuwenden.
• Always: Run even if a previous dependency fails, even if the run is canceled. Geben Sie condition: always()an, um diese Bedingung anzuwenden.
• Fehler: Wird nur ausgeführt, wenn eine vorherige Abhängigkeit fehlschlägt. Geben Sie condition: failed()an, um diese Bedingung anzuwenden.

Bedingungsbeispiel

Im folgenden YAML-Beispiel werden die always() Bedingungen veranschaulicht failed() . Die erste Skriptaufgabe in Auftrag 1 weist eine always Bedingung auf, sodass sie auch dann ausgeführt wird, wenn Abhängigkeiten fehlschlagen oder der Build abgebrochen wird. In der zweiten Skriptaufgabe sorgt exit job1 dafür, dass der job1 Auftrag fehlschlägt.

Pipelinephasen werden standardmäßig sequenziell ausgeführt, Aufträge können jedoch parallel ausgeführt werden. Sie können die dependsOn Eigenschaft verwenden, um explizit Abhängigkeiten zwischen Phasen oder Aufträgen zu definieren.

Verwenden Sie zum Festlegen der Bedingungen für einen Auftrag, der vom Ergebnis eines anderen Auftrags abhängt, dependsOn die Abhängigkeit zu definieren. Im folgenden Beispiel hängt von job2 und wird ausgeführt, job1 da job1 ein Fehler auftritt.

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

Benutzerdefinierte Bedingungen

Wenn die integrierten Bedingungen Ihren Anforderungen nicht entsprechen, können Sie benutzerdefinierte Bedingungen als Ausdrücke in YAML-Pipelinedefinitionen angeben.

Der Agent wertet den Ausdruck aus, indem er mit der innersten Funktion beginnt und nach außen fortfährt. Das endgültige Ergebnis ist ein boolescher Wert, der bestimmt, ob die Phase, der Auftrag oder der Schritt ausgeführt werden soll. Eine vollständige Anleitung für die Syntax finden Sie unter Ausdrücke.

Variablen in Bedingungen

Sie können Pipelinevariablen festlegen und in Bedingungen verwenden. Die folgende Pipeline legt eine isMain Variable fest und verwendet sie in einer Bedingung, die Phase B nur ausführt, wenn der Buildquellzweig ist 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)

Sie können eine Bedingung festlegen, die ausgeführt werden soll, wenn eine Variable null oder eine leere Zeichenfolge ist. Alle Variablen werden in Azure Pipelines als Zeichenfolgen behandelt, sodass eine leere Zeichenfolge in der folgenden Pipeline entspricht null :

variables:
- name: testEmpty
  value: ''

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

Auftragsausgabevariablen, die in anderen Auftragsbedingungen verwendet werden

Sie können eine Variable in einem Auftrag erstellen, den andere Aufträge in derselben Phase in Bedingungen angeben können. Variablen, die abhängigen Aufträgen zur Verfügung stehen, müssen wie im folgenden Code als AusgabevariablenisOutput=truemit mehreren Aufträgen gekennzeichnet werden:

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

In nachfolgenden Schrittbedingungen verwendete Schrittvariablen

Sie können in einem Schritt eine Variable erstellen, die zukünftige Schritte im selben Auftrag in Bedingungen angeben kann. Variablen, die anhand von Schritten erstellt wurden, sind standardmäßig für zukünftige Schritte im Auftrag verfügbar und müssen nicht als Ausgabevariablen mit mehreren Stellen gekennzeichnet werden.

Variablen, die in einem Schritt in einem Auftrag erstellt wurden, weisen die folgenden Einschränkungen auf:

• Sind auf die Schritte im selben Auftrag eingestellt.
• Sind in nachfolgenden Schritten nur als Umgebungsvariablen verfügbar.
• Kann nicht in demselben Schritt verwendet werden, der sie definiert.

Im folgenden Beispiel wird eine Pipelinevariable in einem Schritt erstellt und die Variable in der Skriptbedingung eines späteren Schritts verwendet.

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

Bedingungseinstellungen für verschiedene Ergebnisse

Die folgende Tabelle zeigt condition Einstellungen, um verschiedene gewünschte Ergebnisse zu erzielen.

Bedingungsergebnisse, wenn ein Buildvorgang abgebrochen wird

Das Abbrechen eines Builds bedeutet nicht, dass alle Phasen, Aufträge und Schritte nicht mehr ausgeführt werden. Welche Aufträge, Phasen oder Schritte nicht mehr ausgeführt werden, hängt von den von Ihnen angegebenen Bedingungen ab, und an welchem Punkt der Ausführung der Pipeline Sie den Build abgebrochen haben. Wenn das übergeordnete Element einer Phase, eines Auftrags oder eines Schritts übersprungen wird, wird die Phase, der Auftrag oder der Schritt unabhängig von den Bedingungen nicht ausgeführt.

Eine Phase, ein Auftrag oder ein Schritt wird ausgeführt, wenn die Auswertung der zugehörigen Bedingungen true ergibt. Wenn eine Bedingung nicht den Status des übergeordneten Elements der Aufgabe berücksichtigt, kann die Aufgabe auch dann ausgeführt werden, wenn das übergeordnete Element abgebrochen wird. Um zu steuern, ob Aufträge, Phasen oder Schritte ausgeführt werden, wenn ein Build abgebrochen wird, fügen Sie eine Auftragsstatusüberprüfungsfunktion in Ihre Bedingungen ein.

Wenn Sie einen Build abbrechen, während er sich in der Warteschleife befindet, aber noch nicht ausgeführt wird, wird die gesamte Ausführung abgebrochen, einschließlich aller anderen Phasen.

Beispiel für Phasenbedingungsergebnisse

Die folgenden Beispiele zeigen die Ergebnisse verschiedener Bedingungen, die auf Phasen festgelegt sind, wenn der Build abgebrochen wird.

Phasenbeispiel 1

In der folgenden Pipeline hängt standardmäßig stage2 davon ab stage1 , dass sie erfolgreich abgeschlossen wurde. Verfügt jedoch über einen stage2 Satz, der ausgeführt werden soll, condition wenn der Quellzweig unabhängig vom main Status iststage1.

Wenn Sie einen Buildvorgang für den main-Branch in die Warteschlange stellen und ihn während der Ausführung von stage1 abbrechen, wird stage2 trotzdem ausgeführt, da eq(variables['Build.SourceBranch'], 'refs/heads/main') als true ausgewertet wird.

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

Phasenbeispiel 2

In der folgenden Pipeline hängt standardmäßig stage2 davon ab stage1 , dass sie erfolgreich abgeschlossen wird. Auftrag B in stage2 verfügt über einen condition Satz, der ausgeführt werden soll, wenn die Quell-Verzweigung ist main.

Wenn Sie einen Build auf der Verzweigung in die main Warteschlange stellen und ihn während der stage1 Ausführung abbrechen und stage2 dessen Aufträge überhaupt nicht ausgeführt werden, obwohl die Phase einen Auftrag enthält, dessen Bedingung ausgewertet wird 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

Phasenbeispiel 3

In der folgenden Pipeline hängt standardmäßig stage2 davon ab stage1 , dass sie erfolgreich abgeschlossen wird. Der schritt inside job B within stage2 has a condition set to run whenever the source branch is main.

Wenn Sie einen Build auf der Verzweigung in die main Warteschlange stellen und ihn abbrechen, während stage1 er ausgeführt wird, stage2 und der Auftrag B überhaupt nicht ausgeführt wird, obwohl der Auftrag B einen Schritt enthält, dessen Bedingung ausgewertet wird true. Stage2 wird vollständig übersprungen, weil stage1 sie abgebrochen wurde.

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

Beispiel für Ergebnisse der Auftragsbedingung

Die folgenden Beispiele zeigen die Ergebnisse verschiedener Bedingungen, die für Aufträge festgelegt sind, wenn der Build abgebrochen wird.

Auftragsbeispiel 1

In der folgenden YAML-Pipeline hängt der Auftrag B , der ausgeführt wird, von der Ausführung des Auftrags A ab. Der Auftrag B verfügt außerdem über einen condition Satz, der ausgeführt werden soll, wenn der Quellzweig ist main.

Wenn Sie einen Buildvorgang für den main-Branch in die Warteschlange stellen und ihn während der Ausführung des Auftrags A abbrechen, wird der Auftrag B trotzdem ausgeführt, da condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') als true ausgewertet wird.

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

Wenn der Auftrag nur ausgeführt werden soll, wenn der Auftrag BA erfolgreich ist und die Buildquelle lautet main, müssen Sie den condition Wert auf " and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')).

Auftragsbeispiel 2

In der folgenden YAML-Pipeline hängt der Auftrag B vom erfolgreichen Auftrag A ab. Auftrag verfügt über einen Satz, der ausgeführt werden soll, wenn der Auftrag Bcondition erfolgreich ist und der Buildquellzweig istA.main

Wenn Sie einen Build auf der Verzweigung in die main Warteschlange stellen und ihn abbrechen, während der Auftrag A ausgeführt wird, wird der Auftrag B nicht ausgeführt, obwohl er einen condition hat, der trueausgewertet wird. Die Bedingung für den Auftrag B wird ausgewertet, false weil der Auftrag A nicht erfolgreich war. Daher werden Auftrag B und die zugehörigen Schritte übersprungen.

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

Beispiel für schrittbedingungsergebnis

Sie können auch Bedingungen für Schritte festlegen. In der folgenden Pipeline ist für den Schritt 2.3 eine Bedingung (condition) festgelegt, damit der Schritt ausgeführt wird, wenn der Quellbranch main lautet.

Wenn Sie einen Buildvorgang für den main-Branch in die Warteschlange stellen und ihn abbrechen, während der Schritt 2.1 oder 2.2 ausgeführt wird, wird der Schritt 2.3 trotzdem ausgeführt, da eq(variables['Build.SourceBranch'], 'refs/heads/main') als true ausgewertet wird.

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

Parameter in Bedingungen

Sie können Parameter in Bedingungen verwenden. Die Parametererweiterung erfolgt, bevor die Pipeline ausgeführt wird und Werte ersetzt, die von ${{ }} den Literalparameterwerten umgeben sind. Da die Parametererweiterung vor der Bedingungsauswertung auftritt, können Sie einen Parameter in einer Pipeline deklarieren und den Parameter in eine beliebige Bedingung in dieser Pipeline einbetten.

Im condition folgenden Beispiel werden zwei Funktionen kombiniert: succeeded() und ${{ eq(parameters.doThing, true) }}. Die Funktion succeeded() überprüft, ob der vorherige Schritt erfolgreich war. Diese Funktion gibt auch zurück true , wenn kein vorheriger Schritt vorhanden ist.

Die Funktion ${{ eq(parameters.doThing, true) }} überprüft, ob der doThing-Parameter gleich true ist. Der Skriptschritt im folgenden Beispiel wird ausgeführt, da kein vorheriger Schritt vorhanden war und parameters.doThing standardmäßig vorhanden ist true .

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

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

Vorlagenparameter in Bedingungen

Wenn Sie einen Parameter an eine Pipelinevorlage übergeben, können Sie den Wert des Parameters in der Vorlagendatei festlegen oder templateContext verwenden, um den Parameter an die Vorlage zu übergeben.

Die folgende parameters.yml Vorlagendatei deklariert den doThing Parameter mit einem Standardwert true und verwendet den Parameter in einer Auftragsbedingung.

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

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

Die folgende azure-pipelines.yml Pipelinedefinition verweist auf den Auftrag in der parameters.yml Vorlagendatei. Die Ausgabe der Pipeline liegt I did a thing daran, dass der Parameter doThing standardmäßig "true" ist.

# azure-pipelines.yml

extends:
  template: parameters.yml

Weitere Vorlagenparameterbeispiele finden Sie in der Referenz zur Vorlageverwendung.

Häufig gestellte Fragen

Wie kann ich einen Auftrag auslösen, wenn ein vorheriger Auftrag trotz Problemen erfolgreich abgeschlossen wurde?

Sie können das Ergebnis des vorherigen Auftrags als Bedingung verwenden. Im folgenden YAML legt der Bedingungsauftrag eq(dependencies.A.result,'SucceededWithIssues')B fest, der ausgeführt werden soll, nachdem der Auftrag A mit Problemen erfolgreich war.

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

Warum wird mein Build nach dem Abbrechen noch ausgeführt?

Dieses Problem kann auftreten, wenn eine in einer Phase konfigurierte Bedingung keine Auftragsstatus-Überprüfungsfunktion enthält. Um das Problem zu beheben, fügen Sie der Bedingung eine Auftragsstatus-Überprüfungsfunktion hinzu. Weitere Informationen finden Sie unter Bedingungsergebnisse, wenn ein Build abgebrochen wird.

Zugehöriger Inhalt

• Angeben von Aufträgen in Ihrer Pipeline
• Hinzufügen von Phasen, Abhängigkeiten und Bedingungen
• Verwenden von Vorlagenparametern