Anpassen Ihrer Pipeline

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

Dies ist eine schrittweise Anleitung zur allgemeinen Anpassung Ihrer Pipeline.

Voraussetzungen

Befolgen Sie die Anweisungen zum Erstellen Ihrer ersten Pipeline, um eine funktionierende Pipeline zu erstellen.

Grundlegendes zur azure-pipelines.yml-Datei

Eine Pipeline wird mithilfe einer YAML-Datei in Ihrem Repository definiert. Normalerweise trägt diese Datei den Namen azure-pipelines.yml und befindet sich im Stammverzeichnis Ihres Repositorys.

Navigieren Sie in Azure Pipelines zur Seite Pipelines, wählen Sie die erstellte Pipeline aus, und wählen Sie Bearbeiten im Kontextmenü der Pipeline aus, um den YAML-Editor für die Pipeline zu öffnen.

Hinweis

Anweisungen zum Anzeigen und Verwalten Ihrer Pipelines im Azure DevOps-Portal finden Sie unter Anzeigen und Verwalten Ihrer Pipelines.

Untersuchen Sie den Inhalt der YAML-Datei.

 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest'

 steps:
 - task: Maven@4
   inputs:
     mavenPomFile: 'pom.xml'
     mavenOptions: '-Xmx3072m'
     javaHomeOption: 'JDKVersion'
     jdkVersionOption: '1.11'
     jdkArchitectureOption: 'x64'
     publishJUnitResults: false
     testResultsFiles: '**/surefire-reports/TEST-*.xml'
     goals: 'package'

Hinweis

Der Inhalt Ihrer YAML-Datei kann dem anfänglichen Beispielrepository entsprechend oder aufgrund von Upgrades in Azure Pipelines abweichen.

Diese Pipeline wird immer ausgeführt, wenn Ihr Team eine Änderung an den Mainbranch Ihres Repositorys pusht oder eine Pull Request erstellt. Sie wird auf einem von Microsoft gehosteten Linux-Computer ausgeführt. Der Pipelineprozess besteht aus einem einzelnen Schritt: der Ausführung der Maven-Aufgabe.

Ändern der Plattform für die Erstellung

Sie können Ihr Projekt auf von Microsoft gehosteten Agents erstellen, die bereits SDKs und Tools für verschiedene Entwicklungssprachen enthalten. Oder Sie können selbstgehostete Agents mit bestimmten Tools verwenden, die Sie benötigen.

  • Navigieren Sie zum Editor für Ihre Pipeline, indem Sie im Build die Pipeline bearbeiten-Aktion auswählen oder auf der Hauptseite der Pipeline Bearbeiten auswählen.

  • Derzeit wird die Pipeline auf einem Linux-Agent ausgeführt:

    pool:
      vmImage: "ubuntu-latest"
    
  • Um eine andere Plattform wie Windows oder Mac auszuwählen, ändern Sie den vmImage-Wert:

    pool:
      vmImage: "windows-latest"
    
    pool:
      vmImage: "macos-latest"
    
  • Wählen Sie Speichern aus und bestätigen Sie dann die Änderungen, damit Ihre Pipeline auf einer anderen Plattform ausgeführt wird.

Schritte hinzufügen

Sie können Ihrer Pipeline weitere Skripts oder Aufgaben als Schritte hinzufügen. Eine Aufgabe ist ein vorgefertigtes Skript. Sie können Aufgaben zum Erstellen, Testen, Veröffentlichen oder Bereitstellen Ihrer App verwenden. Für Java verarbeitet die Maven-Aufgabe, die wir verwendet haben, Tests und die Veröffentlichung von Ergebnissen. Sie können jedoch auch eine Aufgabe verwenden, um Code Coverage-Ergebnisse zu veröffentlichen.

  • Öffnen Sie den YAML-Editor für Ihre Pipeline.

  • Fügen Sie den folgenden Codeschnipsel am Ende Ihrer YAML-Datei hinzu.

    - task: PublishCodeCoverageResults@1
      inputs:
        codeCoverageTool: "JaCoCo"
        summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml"
        reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco"
        failIfCoverageEmpty: true
    
  • Wählen Sie Speichern aus und bestätigen Sie dann die Änderungen.

  • Sie können Ihre Test- und Code Coverage-Ergebnisse anzeigen, indem Sie Ihren Build auswählen und zu den Registerkarten Test und Coverage wechseln.

Erstellen auf mehreren Plattformen

Sie können Ihr Projekt auf mehreren Plattformen erstellen und testen. strategy und matrix sind eine Möglichkeit dazu. Sie können Variablen verwenden, um Daten bequem in verschiedene Teile einer Pipeline einzufügen. In diesem Beispiel verwenden wir eine Variable, um den Namen des Image zu übergeben, das wir verwenden möchten.

  • Ersetzen Sie in Ihrer azure-pipelines.yml-Datei den folgenden Inhalt:

    pool:
      vmImage: "ubuntu-latest"
    

    durch folgenden Inhalt:

    strategy:
      matrix:
        linux:
          imageName: "ubuntu-latest"
        mac:
          imageName: "macOS-latest"
        windows:
          imageName: "windows-latest"
      maxParallel: 3
    
    pool:
      vmImage: $(imageName)
    
  • Wählen Sie Speichern aus und bestätigen Sie dann die Änderungen, damit Ihr Build bis zu drei Aufträge auf drei verschiedenen Plattformen ausführen kann.

Jeder Agent kann jeweils nur einen Auftrag ausführen. Um mehrere Aufträge parallel auszuführen, müssen Sie mehrere Agents konfigurieren. Außerdem sind genügend Parallelaufträge erforderlich.

Erstellen mit mehreren Versionen

Um ein Projekt mit verschiedenen Versionen dieser Sprache zu erstellen, können Sie eine matrix der Versionen und eine Variable verwenden. In diesem Schritt können Sie entweder das Java-Projekt mit zwei verschiedenen Versionen von Java auf einer einzelnen Plattform erstellen oder unterschiedliche Versionen von Java auf verschiedenen Plattformen ausführen.

Hinweis

Sie können strategy in einem Kontext nicht mehrmals verwenden.

  • Wenn Sie auf einer einzelnen Plattform und mehreren Versionen erstellen möchten, fügen Sie der azure-pipelines.yml-Datei vor der Maven-Aufgabe und nach der vmImage die folgende Matrix hinzu.

    strategy:
      matrix:
        jdk10:
          jdkVersion: "1.10"
        jdk11:
          jdkVersion: "1.11"
      maxParallel: 2
    
  • Ersetzen Sie dann diese Zeile in Ihrer Maven-Aufgabe:

    jdkVersionOption: "1.11"
    

    Durch diese Zeile:

    jdkVersionOption: $(jdkVersion)
    
  • Stellen Sie sicher, dass Sie die $(imageName)-Variable wieder auf die Plattform Ihrer Wahl ändern.

  • Wenn Sie auf mehreren Plattformen und Versionen erstellen möchten, ersetzen Sie den gesamten Inhalt in Ihrer azure-pipelines.yml-Datei vor der Veröffentlichungsaufgabe durch den folgenden Codeschnipsel:

    trigger:
    - main
    
    strategy:
      matrix:
        jdk10_linux:
          imageName: "ubuntu-latest"
          jdkVersion: "1.10"
        jdk11_windows:
          imageName: "windows-latest"
          jdkVersion: "1.11"
      maxParallel: 2
    
    pool:
      vmImage: $(imageName)
    
    steps:
    - task: Maven@4
      inputs:
        mavenPomFile: "pom.xml"
        mavenOptions: "-Xmx3072m"
        javaHomeOption: "JDKVersion"
        jdkVersionOption: $(jdkVersion)
        jdkArchitectureOption: "x64"
        publishJUnitResults: true
        testResultsFiles: "**/TEST-*.xml"
        goals: "package"
    
  • Wählen Sie Speichern und bestätigen Sie dann die Änderungen, damit Ihr Build zwei Aufträge auf zwei verschiedenen Plattformen und SDKs ausführen kann.

Anpassen von CI-Triggern

Pipelinetrigger bewirken, dass eine Pipeline ausgeführt wird. Sie können trigger: verwenden, um die Ausführung einer Pipeline zu veranlassen, wenn Sie ein Update per Push an einen Branch übertragen. YAML-Pipelines werden standardmäßig mit einem CI-Trigger auf Ihrem Standardbranch konfiguriert (in der Regel main). Sie können Trigger für bestimmte Branches oder für die Pull Request-Validierung einrichten. Ersetzen Sie für einen Pull Request-Validierungstrigger einfach den trigger:-Schritt durch pr:, wie in den beiden folgenden Beispielen gezeigt. Standardmäßig wird die Pipeline für jede Pull Request-Änderung ausgeführt.

  • Wenn Sie Trigger einrichten möchten, fügen Sie am Anfang der azure-pipelines.yml-Datei einen der folgenden Codeschnipsel hinzu.

    trigger:
      - main
      - releases/*
    
    pr:
      - main
      - releases/*
    

    Sie können den vollständigen Namen des Branchs (z. B. main) oder eine Wildcard mit übereinstimmendem Präfix (z. B. releases/*) angeben.

Pipelineeinstellungen

Sie können Pipelineeinstellungen über das Menü Weitere Aktionen auf der Seite mit den Pipelinedetails anzeigen und konfigurieren.

Screenshot: Menü mit Pipelineeinstellungen und weiteren Aktionen.

Wählen Sie Einstellungen aus, um die folgenden Pipelineeinstellungen zu konfigurieren.

Screenshot: Seite der Pipelineeinstellungen.

Im Bereich Pipelineeinstellungen können Sie die folgenden Einstellungen konfigurieren.

  • Verarbeitung neuer Ausführungsanforderungen: Manchmal möchten Sie verhindern, dass neue Ausführungen in Ihrer Pipeline gestartet werden.

    • Standardmäßig ist die Verarbeitung neuer Ausführungsanforderungen aktiviert. Diese Einstellung ermöglicht die Standardverarbeitung aller Triggertypen, einschließlich manueller Ausführungen.
    • Angehaltene Pipelines ermöglichen die Verarbeitung von Ausführungsanforderungen, diese Anforderungen werden jedoch in die Warteschlange gestellt, ohne tatsächlich zu beginnen. Wenn die Verarbeitung neuer Anforderungen aktiviert ist, wird die Verarbeitung ab der ersten Anforderung in der Warteschlange fortgesetzt.
    • Deaktivierte Pipelines verhindern, dass Benutzer neue Ausführungen starten. Es sind auch alle Trigger deaktiviert, solange diese Einstellung angewendet ist. Bei allen Build-Richtlinien, die eine deaktivierte Pipeline verwenden, wird im PR-Übersichtsfenster neben der Richtlinie die Nachricht „Build kann nicht in die Warteschlange gestellt werden“ angezeigt. Der Status der Richtlinie wird auf „Defekt“ festgelegt.
  • YAML-Dateipfad: Wenn Sie Ihre Pipeline jemals anweisen müssen, eine andere YAML-Datei zu verwenden, können Sie den Pfad zu dieser Datei angeben. Diese Einstellung kann auch nützlich sein, wenn Sie Ihre YAML-Datei verschieben/umbenennen müssen.

  • In dieser Ausführung enthaltene Arbeitselemente automatisch verknüpfen: Bei den Änderungen, die einer bestimmten Pipelineausführung zugeordnet sind, sind möglicherweise Arbeitselemente zugeordnet. Wählen Sie diese Option aus, um diese Arbeitselemente mit der Ausführung zu verknüpfen. Wenn In dieser Ausführung enthaltene Arbeitselemente automatisch verknüpfen ausgewählt ist, müssen Sie entweder einen bestimmten Branch oder * für alle Branches (die Standardeinstellung) angeben. Wenn Sie einen Branch angeben, werden Arbeitselemente nur Ausführungen dieses Branches zugeordnet. Wenn Sie * angeben, werden Arbeitselemente für alle Ausführungen zugeordnet.

    Screenshot: Einstellung „In dieser Ausführung enthaltene Arbeitselemente automatisch verknüpfen“.

Sicherheit verwalten

Sie können die Pipelinesicherheit auf Projektebene über Weitere Aktionen auf der Zielseite der Pipelines und auf Pipelineebene auf der Seite mit den Pipelinedetails konfigurieren.

Screenshot der Optionen des Pipelinesicherheitsmenüs.

Zur Unterstützung der Sicherheit Ihrer Pipelinevorgänge können Sie Benutzer einer integrierten Sicherheitsgruppe hinzufügen, individuelle Berechtigungen für einen Benutzer oder eine Gruppe festlegen oder Benutzer vordefinierten Rollen hinzufügen. Die Sicherheit für die folgenden Objekte aus Azure Pipelines wird über das Webportal verwaltet (entweder im Benutzer- oder im Administratorkontext). Weitere Informationen zum Konfigurieren der Sicherheit von Pipelines finden Sie unter Pipelineberechtigungen und Sicherheitsrollen.

Erstellen eines Arbeitselements bei Fehlern

YAML-Pipelines verfügen, anders als klassische Buildpipelines, nicht über die Einstellung Bei Fehler Arbeitselement erstellen. Klassische Buildpipelines nutzen eine Einzelphase und die Option Bei Fehler Arbeitselement erstellen gilt für die gesamte Pipeline. YAML-Pipelines können mehrstufige Pipelines sein und Einstellungen auf Pipelineebene sind möglicherweise nicht geeignet. Zum Implementieren von Bei Fehler Arbeitselement erstellen in einer YAML-Pipeline können Sie Methoden wie den REST API-Aufruf Work Items – Create oder den Azure DevOps CLI-Befehl az boards work-item create am gewünschten Punkt in Ihrer Pipeline verwenden.

Im nachfolgenden Beispiel sind zwei Aufträge vorhanden. Der erste Auftrag stellt die Arbeit der Pipeline dar, wenn er jedoch fehlschlägt, wird der zweite Auftrag ausgeführt und ein Fehler im selben Projekt wie die Pipeline erstellt.

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      az boards work-item create \
        --title "Build $(build.buildNumber) failed" \
        --type bug \
        --org $(System.TeamFoundationCollectionUri) \
        --project $(System.TeamProject)
    env: 
      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
    displayName: 'Create work item on failure'

Hinweis

Mit Azure Boards können Sie Ihre Arbeitselementnachverfolgung mit verschiedenen Prozessen konfigurieren, z. B. Agile oder Basic. Jeder Prozess verfügt über unterschiedliche Arbeitselementtypen und nicht jeder Arbeitselementtyp ist in jedem Prozess verfügbar. Eine Liste der Arbeitselementtypen, die von den einzelnen Prozessen unterstützt werden, finden Sie unter Arbeitselementtypen (WITs).

Im vorherigen Beispiel werden Laufzeitparameter verwendet, um zu konfigurieren, ob die Pipeline erfolgreich ist oder fehlschlägt. Beim manuellen Ausführen der Pipeline können Sie den Wert des succeed-Parameters festlegen. Der zweite script-Schritt im ersten Auftrag der Pipeline wertet den succeed-Parameter aus und wird nur ausgeführt, wenn succeed auf „false“ festgelegt ist.

Der zweite Auftrag in der Pipeline hat eine Abhängigkeit vom ersten Auftrag und wird nur ausgeführt, wenn der erste Auftrag fehlschlägt. Der zweite Auftrag verwendet den azure DevOps CLI-Befehl az boards work-item create, um einen Fehler zu erstellen. Weitere Informationen zum Ausführen von Azure DevOps CLI-Befehlen aus einer Pipeline finden Sie unter Ausführen von Befehlen in einer YAML-Pipeline.

YAML-Pipelines verfügen, anders als klassische Buildpipelines, nicht über die Einstellung Bei Fehler Arbeitselement erstellen. Klassische Buildpipelines nutzen eine Einzelphase und die Option Bei Fehler Arbeitselement erstellen gilt für die gesamte Pipeline. YAML-Pipelines können mehrstufige Pipelines sein und Einstellungen auf Pipelineebene sind möglicherweise nicht geeignet. Zum Implementieren von Erstellen eines Arbeitselements bei Fehlern in einer YAML-Pipeline können Sie den REST-API-Aufruf Arbeitselemente – Erstellen an der gewünschten Stelle in Ihrer Pipeline verwenden.

Im nachfolgenden Beispiel sind zwei Aufträge vorhanden. Der erste Auftrag stellt die Arbeit der Pipeline dar, wenn er jedoch fehlschlägt, wird der zweite Auftrag ausgeführt und ein Fehler im selben Projekt wie die Pipeline erstellt.

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      curl \
        -X POST \
        -H 'Authorization: Basic $(System.AccessToken)' \
        -H 'Content-Type: application/json-patch+json' \
        -d '[
              {
                "op": "add",
                "path": "/fields/System.Title",
                "from": null,
                "value": "git clone failed"
              }
            ]' \
        "$(System.CollectionUri)$(System.TeamProject)/_apis//wit/workitems/$Bug?api-version=7.1-preview.3
"
    env:
        SYSTEM_ACCESSTOKEN: $(System.AccessToken)
    displayName: 'Create work item on failure'

Hinweis

Mit Azure Boards können Sie Ihre Arbeitselementnachverfolgung mit verschiedenen Prozessen konfigurieren, z. B. Agile oder Basic. Jeder Prozess verfügt über unterschiedliche Arbeitselementtypen und nicht jeder Arbeitselementtyp ist in jedem Prozess verfügbar. Eine Liste der Arbeitselementtypen, die von den einzelnen Prozessen unterstützt werden, finden Sie unter Arbeitselementtypen (WITs).

Im vorherigen Beispiel werden Laufzeitparameter verwendet, um zu konfigurieren, ob die Pipeline erfolgreich ist oder fehlschlägt. Beim manuellen Ausführen der Pipeline können Sie den Wert des succeed-Parameters festlegen. Der zweite script-Schritt im ersten Auftrag der Pipeline wertet den succeed-Parameter aus und wird nur ausgeführt, wenn succeed auf „false“ festgelegt ist.

Der zweite Auftrag in der Pipeline hat eine Abhängigkeit vom ersten Auftrag und wird nur ausgeführt, wenn der erste Auftrag fehlschlägt. Der zweite Auftrag verwendet den azure DevOps API-Befehl az boards work-item create, um einen Fehler zu erstellen.

In diesem Beispiel werden zwei Aufträge verwendet, aber dieser Ansatz kann über mehrere Phasen hinweg verwendet werden.

Hinweis

Sie können auch eine Marketplace-Erweiterung wie Create Bug on Release failure verwenden, die Unterstützung für mehrstufige YAML-Pipelines bietet.

Nächste Schritte

Sie haben nun die Grundlagen zur Anpassung Ihrer Pipeline kennengelernt. Als Nächstes sollten Sie mehr über das Anpassen einer Pipeline für die von Ihnen verwendete Sprache erfahren:

Um Ihre CI-Pipeline zu einer CI/CD-Pipeline zu erweitern, fügen Sie mithilfe von Schritten zum Bereitstellen Ihrer App in einer Umgebung einen Bereitstellungsauftrag hinzu.

Weitere Informationen zu den Themen in diesem Leitfaden finden Sie unter Aufträge, Aufgaben, Aufgabenkatalog, Variablen, Trigger oder Problembehandlung.

Informationen zu weiteren Möglichkeiten in YAML-Pipelines finden Sie in der YAML-Schemareferenz.