Ressourcen in YAML-Pipelines

Artikel
08/26/2024

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

In diesem Artikel werden Ressourcen für YAML-Pipelines erläutert. Eine Ressource ist alles, was von einer Pipeline verwendet wird, die außerhalb der Pipeline vorhanden ist. Nachdem Sie eine Ressource definiert haben, können Sie sie überall in Ihrer Pipeline verwenden.

Ressourcen bieten Ihnen auch die vollständige Nachverfolgbarkeit für die in Ihrer Pipeline verwendeten Dienste, einschließlich der Version, Artefakte, zugeordneten Commits und Arbeitselemente. Sie können Ihre DevOps-Workflows vollständig automatisieren, indem Sie Triggerereignisse für Ihre Ressourcen abonnieren.

Schema der Ressourcen

Ressourcen in YAML stellen Quellen von Pipelines, Builds, Repositorys, Containern, Paketen und Webhooks dar. Vollständige Schemainformationen finden Sie in der Ressourcendefinition in der YAML-Schemareferenz für Azure Pipelines.

Wenn eine Ressource eine Pipeline auslöst, werden die folgenden Variablen festgelegt:

resources.triggeringAlias
resources.triggeringCategory

Die Variable Build.Reason muss ResourceTrigger sein, damit diese Werte festgelegt werden. Diese Werte sind leer, wenn eine Ressource keine Pipelineausführung auslöst.

Pipelines-Ressourcendefinition

Wenn Sie über eine Pipeline verfügen, die Artefakte erzeugt, können Sie die Artefakte nutzen, indem Sie eine pipelines-Ressource definieren. Nur Azure-Pipelines können die pipelines Ressource verwenden. Sie können Auslöser für Ihre Continuous Deployment (CD)-Workflows in einer Pipeline-Ressource festlegen.

In Ihrer Ressourcendefinition ist pipeline ein eindeutiger Wert, den Sie verwenden können, um die Pipeline-Ressource später in Ihrer Pipeline zu verweisen. Der source Name der Pipeline, die das Pipelineartefakt erzeugt hat. Vollständige Schemainformationen finden Sie in der Definition „resources.pipelines.pipeline”.

Sie verwenden die durch pipeline definierte Bezeichnung, um von anderen Teilen Ihrer Pipeline aus auf die Pipelineressource zu verweisen, z. B. beim Verwenden von Pipelineressourcenvariablen oder beim Herunterladen von Artefakten. Eine alternative Möglichkeit zum Herunterladen von Pipelineartefakten finden Sie unter Artefakte herunterladen.

Wichtig

Wenn Sie einen Pipelineressourcentrigger definieren:

Wenn die pipeline Ressource aus demselben Repository wie die aktuelle Pipeline stammt oder self die Auslösung demselben Branch und Commit folgt, in dem das Ereignis ausgelöst wird.
Wenn die Pipelineressource aus einem anderen Repository stammt, wird die aktuelle Pipeline auf dem Standardbranch der pipeline Ressource „Repository” ausgelöst.

Beispiel für Pipelineressourcendefinitionen

Das folgende Beispiel konsumiert Artefakte aus einer Pipeline innerhalb desselben Projekts.

resources:
  pipelines:
  - pipeline: SmartHotel-resource # identifier to use in pipeline resource variables
    source: SmartHotel-CI # name of the pipeline that produces the artifacts

Um eine Pipeline aus einem anderen Projekt zu nutzen, schließen Sie den Projektnamen und den Quellnamen ein. Im folgenden Beispiel wird branch die Standardversion aufgelöst, wenn die Pipeline manuell oder geplant ausgelöst wird. Die Verzweigungseingabe darf keine Wildcards enthalten.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    branch: releases/M142

Das folgende Beispiel zeigt eine Pipelineressource mit einem einfachen Trigger.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger: true

Das folgende Beispiel zeigt eine Pipelineressource trigger mit Verzweigungsbedingungen.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
      - releases/*
      - resources.triggeringAlias

Im folgenden Beispiel werden stages Filter zum Auswerten von Triggerbedingungen für CD-Pipelines verwendet. Stufen verwenden den AND Operator. Nach erfolgreichem Abschluss aller bereitgestellten Phasen löst die CD-Pipeline aus.

resources:
  pipelines:
  - pipeline: MyCIAlias  
    project: Fabrikam  
    source: Farbrikam-CI  
    trigger:    
      stages:
      - PreProduction
      - Production

Im folgenden Beispiel werden tags Filter für die Auswertung der Standardversion und für Trigger verwendet. Tags verwenden den AND Operator.

Sie tags sind auf der Continuous Integration (CI)- oder CD-Pipeline festgelegt. Diese Tags unterscheiden sich von den Tags, die Sie für die Branches im Git-Repository festlegen.

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    tags: 
    - Production 
    trigger:
      tags:
      - Production
      - Signed

Versionsauswertung der Pipelinesartefakte

Die Version der Artefakte der Ressourcenpipeline hängt davon ab, wie die Pipeline ausgelöst wird.

Manueller oder geplanter Trigger

Wenn die Pipelineausführung manuell ausgelöst oder geplant wird, definieren die Werte der version , branch und tags die Eigenschaften der Artefaktversion. Die branch Eingabe darf keine Wildcards haben. Die tags Eigenschaften verwenden den AND Operator.

Angegebene Eigenschaften	Artefaktversion
`version`	Die Artefakte aus dem Build mit der angegebenen Ausführungsnummer.
`branch`	Die Artefakte des letzten Builds aus dem angegebenen Branch
`tags`-Liste	Die Artefakte aus dem neuesten Build mit allen angegebenen Tags
Liste `branch` und `tags`	Die Artefakte des letzten Builds, der auf dem angegebenen Branch erstellt wurde und alle angegebenen Tags enthält
Keine	Die Artefakte aus dem neuesten Build in allen Branches.

In der folgenden pipeline Ressourcendefinition werden die Standardversion branch und tags die Eigenschaften verwendet, um die Standardversion zu bewerten, wenn die Pipeline manuell oder geplant ausgelöst wird. Wenn Sie die Ausführung der Pipeline manuell auslösen, entspricht die Version der Artefakte der MyCIAlias-Pipeline der des neuesten Builds, der für den main-Branch durchgeführt wurde und über die Tags Production und PrepProduction verfügt.

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    branch: main
    tags:
    - Production
    - PreProduction

Auslöser für den Abschluss der Ressourcenpipeline

Wenn eine Pipeline ausgelöst wird, da eine ihrer Ressourcenpipelines abgeschlossen ist, entspricht die Version der Artefakte derjenigen der auslösenden Pipeline. Die Werte der Eigenschaften version, branch und tags werden ignoriert.

Angegebene Trigger	Ergebnis
`branches`	Eine neue Ausführung der Pipeline wird ausgelöst, wenn die Ressourcenpipeline erfolgreich eine Ausführung auf einer der `include`-Branches abgeschlossen hat.
`tags`	Eine neue Ausführung der Pipeline wird ausgelöst, wenn die Ressourcenpipeline erfolgreich eine Ausführung abschließt, die mit allen angegebenen Tags markiert ist.
`stages`	Eine neue Ausführung der Pipeline wird ausgelöst, wenn die Ressourcenpipeline die angegebene `stages` erfolgreich ausgeführt hat.
`branches`, `tags` und `stages`	Eine neue Ausführung der Pipeline wird ausgelöst, wenn die Ausführung der Ressourcenpipeline alle Branch-, Tag- und Phasenbedingungen erfüllt.
`trigger: true`	Eine neue Ausführung der Pipeline wird ausgelöst, wenn die Ressourcenpipeline erfolgreich eine Ausführung abgeschlossen hat.
Nichts	Keine neue Ausführung der Pipeline wird ausgelöst, wenn die Ressourcenpipeline erfolgreich eine Ausführung abgeschlossen hat.

Die folgende Pipeline wird immer dann ausgeführt, wenn die SmartHotel-CI Ressourcenpipeline ausgeführt wird:

Wird auf einer der releases Zweige oder auf der main Verzweigung ausgeführt
Ist mit beiden Verified und Signed markiert
Schließt sowohl die Production als auch die PreProduction Phasen ab.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
        include:
        - releases/*
        - main
        exclude:
        - topic/*
      tags: 
      - Verified
      - Signed
      stages:
      - Production
      - PreProduction

Pipeline-Artefakt-Download

Der download Schritt lädt Artefakte herunter, die der aktuellen Ausführung oder einer anderen Pipelineressource zugeordnet sind.

Alle Artefakte aus der aktuellen Pipeline und aus allen seiner pipeline-Ressourcen werden automatisch heruntergeladen und zu Beginn eines jeden Bereitstellungsauftrags zur Verfügung gestellt. Sie können dieses Verhalten überschreiben, indem Sie diese Einstellung download auf nonefestlegen oder einen anderen Pipelineressourcenbezeichner angeben.

Reguläre Auftragsartefakte werden nicht automatisch heruntergeladen. Verwenden Sie bei Bedarf explizit download.

Artefakte aus der pipeline Ressource werden in den $(PIPELINE.WORKSPACE)/<pipeline-identifier>/<artifact-identifier> Ordner heruntergeladen. Weitere Informationen finden Sie unter Pipeline-Artefakte veröffentlichen und herunterladen.

Die optionale artifact Eigenschaft gibt Artefaktnamen an. Wenn nicht angegeben, werden alle verfügbaren Artefakte heruntergeladen. Die optionale patterns Eigenschaft definiert Muster, die enthaltende Dateien darstellen. Vollständige Schemainformationen finden Sie in der Definition „steps.download”.

- job: deploy_windows_x86_agent
  steps:
  - download: SmartHotel
    artifact: WebTier1
    patterns: '**/*.zip'

Variablen der Pipelineressource

In jeder Ausführung sind die Metadaten für eine Pipelineressource für alle Aufträge als vordefinierten Variablen verfügbar. Diese Variablen sind nur zur Laufzeit für Ihre Pipeline verfügbar und können daher nicht in Vorlagenausdrücken verwendet werden, die zur Pipelinekompilierungszeit ausgewertet werden.

Weitere Informationen finden Sie unter Metadaten der Pipelineressource als vordefinierte Variablen. Weitere Informationen zur Variablensyntax finden Sie unter Definieren von Variablen.

Im folgenden Beispiel werden die vordefinierten Variablenwerte für die myresourcevars Pipelineressource zurückgegeben.

resources:
  pipelines:
  - pipeline: myresourcevars
    source: mypipeline
    trigger: true 

steps:
- script: |
    echo $(resources.pipeline.myresourcevars.pipelineID)
    echo $(resources.pipeline.myresourcevars.runName)
    echo $(resources.pipeline.myresourcevars.runID)
    echo $(resources.pipeline.myresourcevars.runURI)
    echo $(resources.pipeline.myresourcevars.sourceBranch)
    echo $(resources.pipeline.myresourcevars.sourceCommit)
    echo $(resources.pipeline.myresourcevars.sourceProvider)
    echo $(resources.pipeline.myresourcevars.requestedFor)
    echo $(resources.pipeline.myresourcevars.requestedForID)

Erstellt die Ressourcendefinition

Wenn Sie über ein externes CI-Buildsystem verfügen, das Artefakte erzeugt, können Sie Artefakte mit builds-Ressourcen nutzen. Eine build-Ressource kann aus einem beliebigen externen CI-System wie Jenkins, TeamCity oder CircleCI sein.

Die builds Kategorie ist erweiterbar. Sie können eine Erweiterung schreiben, um Artefakte von Ihrem Builddienst zu nutzen und eine neue Art von Dienst als Teil von builds einzuführen.

In der build Definition version wird standardmäßig der neueste erfolgreiche Build verwendet. Die trigger Option ist standardmäßig nicht aktiviert und muss explizit festgelegt werden. Vollständige Schemainformationen finden Sie in der Definition „resources.builds.build”.

Im folgenden Beispiel ist Jenkins die Ressource type.

resources:
  builds:
  - build: Spaceworkz
    type: Jenkins
    connection: MyJenkinsServer 
    source: SpaceworkzProj   # name of the Jenkins source project
    trigger: true

Wichtig

Trigger werden nur für gehostetes Jenkins unterstützt, bei dem Azure DevOps eine Sichtverbindung mit dem Jenkins-Server hat.

Die downloadBuild-Aufgabe

Die build-Ressourcenartefakte werden nicht automatisch in Ihren Aufträgen/Bereitstellungsaufträgen heruntergeladen. Um Artefakte aus der build Ressource als Teil Ihrer Aufträge zu nutzen, müssen Sie den downloadBuild Vorgang explizit hinzufügen. Sie können das Downloadverhalten für jede Bereitstellung oder jeden Auftrag anpassen.

Diese Aufgabe wird automatisch in die entsprechende Download-Aufgabe für den von der Laufzeit definierten build Ressourcentyp aufgelöst. Artefakte aus der build Ressource werden in $(PIPELINE.WORKSPACE)/<build-identifier>/ Ordner heruntergeladen.

In der downloadBuild Definition geben Sie die Ressource an, aus der Artefakte heruntergeladen werden sollen. Die optionale artifact Eigenschaft gibt Artefakte an, die heruntergeladen werden sollen. Wenn nicht angegeben, werden alle Artefakte, die der Ressource zugeordnet sind, heruntergeladen.

Die optionale patterns Eigenschaft definiert einen Minimatch-Pfad oder eine Liste der minimatch-Pfade , die heruntergeladen werden sollen. Wenn leer, wird das gesamte Artefakt heruntergeladen. Der folgende Codeausschnitt lädt beispielsweise nur die Dateien *.zip herunter.

- job: deploy_windows_x86_agent
  steps:
  - downloadBuild: Spaceworkz
    patterns: '**/*.zip'

Vollständige Schemainformationen finden Sie in der Definition „steps.downloadBuild”.

Definition einer Repositoryressource

Mit dem repository-Schlüsselwort können Sie ein externes Repository angeben. Sie können diese Ressource verwenden, wenn Ihre Pipeline über Vorlagen in einem anderen Repository verfügt, oder Sie das Auschecken mehrerer Repositorys mit einem Repository verwenden möchten, das eine Dienstverbindung erfordert, müssen Sie das System über dieses Repository informieren. Sie müssen das System über diese Repositorys informieren.

Zum Beispiel:

resources:
  repositories:
  - repository: common
    type: github
    name: Contoso/CommonTools
    endpoint: MyContosoServiceConnection

Vollständige Schemainformationen finden Sie in der Definition „resources.repositories.repository”.

Repositoryressourcentypen

Azure Pipelines unterstützen die folgenden Werte für den Repositorytyp: git, github, githubenterprise und bitbucket.

Der git-Typ bezieht sich auf Azure Repos Git-Repositorys.
GitHub Enterprise-Repositorys benötigen zur Autorisierung eine GitHub Enterprise-Dienstverbindung.
Bitbucket Cloud-Repositorys benötigen eine Bitbucket Cloud-Dienstverbindung zur Autorisierung.

type	Wert des Namens	Beispiel
`type: git`	Ein anderes Repository im selben Projekt oder derselben Organisation.	Gleiches Projekt: `name: otherRepo` Ein weiteres Projekt in der gleichen Organisation: `name: otherProject/otherRepo`.
`type: github`	Vollständiger Name des GitHub-Repositorys, einschließlich des Benutzers oder der Organisation.	`name: Microsoft/vscode`
`type: githubenterprise`	Vollständiger Name des GitHub-Enterprise-Repositorys, einschließlich des Benutzers oder der Organisation.	`name: Microsoft/vscode`
`type: bitbucket`	Vollständiger Name des Bitbucket-Cloud-Repositorys, einschließlich des Benutzers oder der Organisation.	`name: MyBitbucket/vscode`

Repositoryressourcenvariablen

In jeder Ausführung sind die folgenden Metadaten für eine Repositoryressource für alle Aufträge in Form von Laufzeitvariablen verfügbar. Der <Alias> ist der Bezeichner, den Sie für Ihre Repositoryressource angegeben haben.

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url

Das folgende Beispiel enthält eine Repositoryressource mit dem Alias common, damit auf die Variable der Repositoryressource mithilfe von resources.repositories.common.* zugegriffen wird.

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url
resources.repositories.<Alias>.version

Das folgende Beispiel enthält eine Repositoryressource mit dem Alias common, damit auf die Variable der Repositoryressource mithilfe von resources.repositories.common.* zugegriffen wird.

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]
  version: $[ resources.repositories.common.version ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"
    echo "version = $(version)"

Auschecken des Schlüsselworts für Repositorys

Repositorys aus der repository-Ressource werden nicht automatisch in Ihren Aufträgen synchronisiert. Verwenden Sie das checkout Schlüsselwort, um ein Repository abzurufen, das als Teil der repository Ressource definiert ist. Vollständige Schemainformationen finden Sie in der Definition „steps.checkout”.

Weitere Informationen finden Sie im Artikel zum Auschecken mehrerer Repositorys in Ihrer Pipeline.

Containerressourcendefinition

Wenn Sie Containerimages als Teil Ihrer CI/CD-Pipelines verwenden müssen, können Sie Ressourcen verwenden containers . Eine container Ressource kann eine öffentliche oder private Docker-Registrierung oder eine Azure Containerregistrierungs-Instanz sein.

Sie können eine generische Containerressource als Image nutzen, das als Teil Ihres Auftrags genutzt wird, oder verwenden Sie die Ressource für Containeraufträge. Wenn Ihre Pipeline die Unterstützung eines oder mehrerer Dienste erfordert, sollten Sie Dienstcontainer erstellen und mit diesen eine Verbindung herstellen. Sie können Volumes verwenden, um Daten zwischen Diensten freizugeben.

Wenn Sie als Teil Ihrer Pipeline Images aus einer Docker-Registrierung verwenden möchten, können Sie eine generische Containerressource definieren. Es ist kein type Schlüsselwort erforderlich. Zum Beispiel:

resources:         
  containers:
  - container: smartHotel 
    endpoint: myDockerRegistry
    image: smartHotelApp

Vollständige Schemainformationen finden Sie in der Definition „resources.containers.container”.

Hinweis

Die enabled: 'true' Syntax, die zum Aktivieren von Containertriggern für alle Imagetags verwendet wird, unterscheidet sich von der Syntax, die für andere Ressourcentrigger verwendet wird. Achten Sie darauf, die richtige Syntax für bestimmte Ressourcen zu verwenden.

Azure Container Registry-Ressourcentyp

Um Ihre Azure Container Registry-Images zu nutzen, können Sie den Container-Ressourcentyp erster Klasse acr verwenden. Sie können diesen Ressourcentyp als Teil Ihrer Aufträge und zum Aktivieren automatischer Pipelinetrigger verwenden.

Sie benötigen die Berechtigungen Mitwirkender oder Besitzer für Azure Container Registry, um automatische Pipelinetrigger zu verwenden. Weitere Informationen finden Sie unter Azure Container Registry: Rollen und Berechtigungen.

Um den acr Ressourcentyp zu verwenden, müssen Sie die azureSubscriptionWerte resourceGroupund Werte repository für Ihre Azure-Containerregistrierung angeben. Zum Beispiel:

resources:         
  containers:
  - container: petStore      
    type: acr  
    azureSubscription: ContosoConnection
    resourceGroup: ContosoGroup
    registry: petStoreRegistry
    repository: myPets
    trigger: 
      tags:
        include: 
        - production*

Hinweis

Triggerauswertung tritt nur auf dem Standardbranch auf. Stellen Sie sicher, dass Sie die richtige Standardbranch festlegen oder die YAML-Datei in die aktuelle Standardbranch zusammenführen. Weitere Informationen zum Ändern der Pipeline Standardbranch finden Sie in der Pipeline Standardbranch.

Containerressourcenvariablen

Sobald Sie einen Container als Ressource definieren, werden Containerimage-Metadaten als Variablen an die Pipeline übergeben. Informationen wie Image, Registrierung und Verbindungsdetails sind für alle Aufträge zugänglich, die Sie für Ihre Aufgaben zur Bereitstellung von Containern verwenden.

Containerressourcenvariablen funktionieren mit Docker und Azure Container Registry. Sie können keine Containerressourcenvariablen für lokale Imagecontainer verwenden. Die location Variable gilt nur für den acr Typ der Containerressourcen.

Das folgende Beispiel hat eine Azure Resource Manager-Dienstverbindung namens arm-connection. Weitere Informationen finden Sie unter Azure-Containerregistrierungen, Repositorys und Images.

resources:
  containers:
  - container: mycontainer
    type: ACR
    azureSubscription: arm-connection
    resourceGroup: rg-storage-eastus
    registry: mycontainerregistry
    repository: hello-world
    trigger:
      tags:
      - latest

steps:
- script: echo |
    echo $(resources.container.mycontainer.type)
    echo $(resources.container.mycontainer.registry)
    echo $(resources.container.mycontainer.repository)
    echo $(resources.container.mycontainer.tag)
    echo $(resources.container.mycontainer.digest)
    echo $(resources.container.mycontainer.URI)
    echo $(resources.container.mycontainer.location)

Paketressourcendefinition

Sie können NuGet- und npm-GitHub-Pakete als Ressourcen in YAML-Pipelines nutzen. Um automatisierte Pipelinetrigger zu aktivieren, wenn eine neue Paketversion freigegeben wird, legen Sie die trigger Eigenschaft auf true.

Wenn Sie packageRessourcen definieren, geben Sie das Paket-<Repository>/<Name> in der name Eigenschaft an, und legen Sie das Paket type als NuGet oder npm fest. Um GitHub-Pakete zu verwenden, verwenden Sie eine Authentifizierung auf der Basis von persönlichen Zugriffstoken (Personal Access Token, PAT) und erstellen eine GitHub-Dienstverbindung, die PAT verwendet.

Vollständige Schemainformationen finden Sie in der Definition „resources.packages.package”.

Standardmäßig werden Pakete nicht automatisch in Aufträge heruntergeladen. Verwenden Sie getPackage, um es herunterzuladen.

Das folgende Beispiel enthält eine GitHub-Dienstverbindung mit dem Namen pat-contoso mit einem GitHub-npm-Paket namens contoso. Weitere Informationen finden Sie unter GitHub-Pakete.

resources:
  packages:
    - package: contoso
      type: npm
      connection: pat-contoso
      name: myname/contoso 
      version: 7.130.88 
      trigger: true

pool:
  vmImage: 'ubuntu-latest'

steps:
- getPackage: contoso

Webhooks-Ressourcendefinition

Hinweis

Webhooks wurden in Azure DevOps Server 2020.1 veröffentlicht.

Sie können Artefakte nutzen und automatische Auslöser mit Pipeline-, Container-, Build- und Paketressourcen aktivieren. Sie können diese Ressourcen jedoch nicht verwenden, um Ihre Bereitstellungen auf der Grundlage externer Ereignisse oder Dienste zu automatisieren.

Mit der webhooks Ressource in YAML-Pipelines können Sie Ihre Pipelines in externe Dienste wie GitHub, GitHub Enterprise, Nexus und Artifactory integrieren, um Workflows zu automatisieren. Sie können alle externen Ereignisse über Webhooks abonnieren und die Ereignisse verwenden, um Ihre Pipelines auszulösen.

Webhooks automatisieren Ihren Workflow auf der Grundlage eines externen Webhookereignisses, das nicht von erstklassigen Ressourcen wie Pipelines, Builds, Container oder Pakete unterstützt wird. Auch für lokale Dienste, bei denen Azure DevOps keinen Einblick in den Prozess hat, können Sie Webhooks für den Dienst konfigurieren, um Ihre Pipelines automatisch auszulösen.

Um ein Webhookereignis zu abonnieren, definieren Sie eine Webhookressource in Ihrer Pipeline, und verweisen sie auf eine eingehende Webhookdienstverbindung. Sie können auch weitere Filter für die Webhookressource definieren, die auf den JSON-Nutzdaten basieren, um die Trigger für die einzelnen Pipelines anzupassen.

Immer, wenn die eingehende Webhookdienstverbindung ein Webhookereignis empfängt, wird eine neue Ausführung für alle Pipelines ausgelöst, die das Webhookereignis abonniert haben. Sie können die JSON-Nutzdaten in Ihren Aufträgen als Variablen mithilfe des Formats ${{ parameters.<WebhookAlias>.<JSONPath>}} nutzen.

Vollständige Schemainformationen finden Sie in der Definition „resources.webhooks.webhook”.

Im folgenden Beispiel wird eine Webhookressource definiert:

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

steps:  
- script: echo ${{ parameters.WebHook.resource.message.title }}

Webhooktrigger

Um Webhook-Trigger zu konfigurieren, richten Sie zuerst einen Webhook für Ihren externen Dienst ein, und stellen die folgenden Informationen bereit:

Anforderung URL: https://dev.azure.com/<Azure DevOps organization>/_apis/public/distributedtask/webhooks/<webhook name>?api-version=6.0-preview
Secret (Optional): Wenn Sie Ihre JSON-Payload sichern müssen, geben Sie einen geheimen Wert an.

Als nächstes erstellen Sie eine neue eingehende Webhook-Dienstverbindung. Für diesen Dienstverbindungstyp definieren Sie die folgenden Informationen:

WebHook-Name: Identisch mit dem Webhook, der in Ihrem externen Dienst erstellt wurde.
Secret (Optional): Wird verwendet, um den HMAC-SHA1-Hash der Payload zur Überprüfung der eingehenden Anfrage zu verifizieren. Wenn Sie beim Erstellen Ihres Webhooks ein Geheimnis verwendet haben, müssen Sie dasselbe Geheimnis angeben.
HTTP-Header: Der HTTP-Header in der Anfrage, der den HMAC-SHA1-Hash-Wert der Payload zur Überprüfung der Anfrage enthält. Beispielsweise lautet der GitHub-Anforderungsheader X-Hub-Signature.

Screenshot, der die eingehende Webhookdienstverbindung zeigt.

Um Ihre Pipeline mithilfe eines Webhooks auszulösen, müssen Sie eine POST-Anforderung an https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview senden. Dieser Endpunkt ist öffentlich verfügbar, und benötigt keine Autorisierung. Die Anfrage sollte einen Text wie im folgenden Beispiel haben:

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Hinweis

Der Zugriff auf Daten aus dem Anforderungstext des Webhooks kann zu falschem YAML führen. Beispielsweise ruft der Pipelineschritt - script: echo ${{ parameters.WebHook.resource.message }} die gesamte JSON-Nachricht ab, die ungültige YAML generiert. Jede Pipeline, die über diesen Webhook ausgelöst wird, wird nicht ausgeführt, da das generierte YAML ungültig wurde.

Der folgende Codeschnipsel zeigt ein weiteres Beispiel für die Verwendung von Webhookfiltern an.

resources:
  webhooks:
    - webhook: MyWebhookTrigger          
      connection: MyWebhookConnection    
      filters:
        - path: repositoryName      
          value: maven-releases     
        - path: action
          value: CREATED
steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host ${{ parameters.MyWebhookTrigger.repositoryName}}
      Write-Host ${{ parameters.MyWebhookTrigger.component.group}}

Manuelle Versionsauswahl für Ressourcen

Wenn Sie eine CD-YAML-Pipeline manuell auslösen, werten Azure Pipelines automatisch die Standardversionen für die in der Pipeline definierten Ressourcen basierend auf den angegebenen Eingaben aus. Azure Pipelines berücksichtigen jedoch nur erfolgreich ausgeführte CI-Ausführungen, wenn wir die Standardversion für geplante Trigger auswerten oder wenn Sie keine manuelle Versionsauswahl verwenden.

Sie können die Ressourcenversionsauswahl verwenden, um manuell eine andere Version auszuwählen, wenn Sie eine Ausführung erstellen. Die Ressourcenversionsauswahl wird für Pipeline-, Build-, Repository-, Container- und Paketressourcen unterstützt.

Für Pipelineressourcen können Sie alle verfügbaren Vorgänge in allen Verzweigungen anzeigen, sie basierend auf der Pipelinenummer oder Verzweigung durchsuchen und eine Ausführung auswählen, die erfolgreich, fehlgeschlagen oder in Bearbeitung ist. Diese Flexibilität gewährleistet, dass Sie Ihre CD-Pipeline ausführen können, wenn Sie sicher sind, dass eine Ausführung alle erforderlichen Artefakte erzeugt hat. Sie müssen nicht warten, bis eine CI-Ausführung abgeschlossen oder erneut ausgeführt wird, da ein nicht verwandter Phasenfehler aufgetreten ist.

Um die Ressourcenversionsauswahl zu verwenden, wählen Sie im Bereich Pipeline ausführen die Option Ressourcen und dann eine Ressource und eine bestimmte Version aus der Liste der verfügbaren Versionen aus.

Screenshot der Repositoryressourcenversionsauswahl.

Für Ressourcen, von denen Sie keine verfügbaren Versionen abrufen können, z. B. GitHub-Pakete, stellt die Versionsauswahl ein Textfeld zur Verfügung, in das Sie die Version eingeben können, die für die Ausführung ausgewählt werden soll.

Ressourcenautorisierung in YAML-Pipelines

Ressourcen können erst dann in Pipelines verwendet werden, wenn sie autorisiert sind. Ressourcenbesitzer kontrollieren die Benutzer und Pipelines, die auf ihre Ressourcen zugreifen können. Es gibt mehrere Möglichkeiten, eine YAML-Pipeline für die Verwendung von Ressourcen zu autorisieren.

Verwenden Sie die Ressourcenverwaltungsoberfläche, um alle Pipelines für den Zugriff auf die Ressource zu autorisieren. Variablengruppen und sichere Dateien werden beispielsweise auf der Bibliotheksseite unter Pipelines verwaltet, und Agentpools und Dienstverbindungen werden in den Projekteinstellungen verwaltet. Diese Autorisierung ist praktisch, wenn Sie den Zugriff auf Ressourcen nicht einschränken müssen, wie z. B. bei Testressourcen.
Bei der Erstellung einer Pipeline werden alle Ressourcen, auf die in der YAML-Datei verwiesen wird, automatisch für die Nutzung durch die Pipeline autorisiert, wenn Sie die Benutzerrolle für diese Ressourcen haben.
Wenn Sie einer YAML-Datei eine Ressource hinzufügen und der Build mit einem Fehler fehlschlägt, wird Could not find a <resource> with name <resource-name>. The <resource> does not exist or has not been authorized for use.eine Option zum Autorisieren der Ressourcen für den fehlerhaften Build angezeigt.

Wenn Sie Mitglied der Benutzerrolle für die Ressource sind, können Sie diese Option auswählen und die Ressource für den fehlgeschlagenen Build autorisieren. Sobald die Ressource autorisiert ist, können Sie einen neuen Build starten.
Überprüfen Sie, ob die Agentpoolsicherheitsrollen für Ihr Projekt korrekt sind.

Genehmigungsüberprüfungen für Ressourcen

Sie können Genehmigungsprüfungen und Vorlagen verwenden, um manuell zu steuern, wann eine Ressource ausgeführt wird. Mit der erforderlichen Überprüfung zur Vorlagengenehmigung können Sie anfordern, dass jede Pipeline, die eine Ressource oder Umgebung verwendet, die von einer bestimmten YAML-Vorlage ausgeht.

Das Festlegen einer erforderlichen Vorlagengenehmigung stellt sicher, dass Ihre Ressource nur unter bestimmten Bedingungen verwendet wird und die Sicherheit verbessert. Weitere Informationen zur Verbesserung der Pipelinesicherheit mit Vorlagen finden Sie unter Verwenden von Vorlagen zur Sicherheit.

Nachverfolgbarkeit

Azure Pipelines bieten vollständige Nachverfolgbarkeit für jede Ressource, die auf Pipelineebene oder der Ebene des Bereitstellungsauftrags genutzt wird.

Nachverfolgbarkeit von Pipelines

Azure Pipelines zeigt die folgenden Informationen für jede Pipelineausführung:

Wenn eine Ressource die Pipeline ausgelöst hat, wird die Ressource, die die Pipeline ausgelöst hat, ausgelöst.
Die Version der Ressource und der verbrauchten Artefakte.
Den jeweiligen Ressourcen zugeordnete Commits.
Den jeweiligen Ressourcen zugeordnete Arbeitselemente.

Nachverfolgbarkeit von Umgebungen

Wenn eine Pipeline in einer Umgebung bereitgestellt wird, können Sie eine Liste der verbrauchten Ressourcen anzeigen. Die Ansicht enthält die im Rahmen der Bereitstellungsaufträge und ihrer zugeordneten Commits und Arbeitselemente verbrauchten Ressourcen.

Screenshot, der Commits in einer Umgebung zeigt.

Zugehörige CD-Pipelineinformationen in CI-Pipelines

Um eine End-to-End-Nachverfolgbarkeit zu gewährleisten, können Sie nachverfolgen, welche CD-Pipelines eine bestimmte CI-Pipeline über die pipelines Ressource verbrauchen. Wenn Ihre CI-Pipeline von anderen Pipelines genutzt wird, wird die Registerkarte Zugeordnete Pipelines in der Ausführungsansicht angezeigt. In der Ansicht werden alle CD-YAML-Pipelineausführungen angezeigt, die Ihre CI-Pipeline und die Artefakte davon genutzt haben.

Screenshot der Informationen zu CD-Pipelines in einer CI-Pipeline.

Ressourcenauslöserprobleme

Ressourcentrigger können nicht ausgeführt werden, weil:

Die Quelle der bereitgestellten Dienstverbindung ist ungültig oder der Trigger enthält Syntaxfehler oder der Trigger wird nicht konfiguriert.
Triggerbedingungen werden nicht übereinstimmen.

Um zu sehen, warum Pipelinetrigger nicht ausgeführt werden konnten, wählen Sie das Menüelement Probleme auslösen auf der Pipelinedefinitionsseite aus. Triggerprobleme ist nur für Nicht-Repositoryressourcen verfügbar.

Auf der Seite Triggerprobleme beschreiben die Fehlermeldungen und Warnmeldungen, warum der Trigger fehlgeschlagen ist.

Screenshot, der die Unterstützung von Triggerproblemen zeigt.

Häufig gestellte Fragen

Wann sollte ich Pipelineressourcen, die Downloadverknüpfung oder die Aufgabe „Pipelineartefakte herunterladen” verwenden?

Die Verwendung einer pipelines-Ressource ist eine Möglichkeit, Artefakte aus einer CI-Pipeline zu nutzen und auch automatisierte Trigger zu konfigurieren. Eine Ressource bietet Ihnen vollständige Einblicke in den Prozess, indem die verbrauchte Version, Artefakte, Commits und Arbeitselemente angezeigt werden. Wenn Sie eine Pipelineressource definieren, werden die zugehörigen Artefakte automatisch in Bereitstellungsaufträgen heruntergeladen.

Sie können die download Verknüpfung verwenden, um die Artefakte in Build-Aufträgen herunterzuladen oder um das Download-Verhalten in Bereitstellungsaufträgen außer Kraft zu setzen. Weitere Informationen finden Sie in der Definition „steps.download”.

Die Aufgabe „Pipelineartefakte herunterladen” bietet keine Rückverfolgbarkeit oder Trigger, aber manchmal ist es sinnvoll, diese Aufgabe direkt zu verwenden. Sie könnten z. B. eine Skriptaufgabe in einer anderen Vorlage, die das Herunterladen von Artefakten aus einem Build erfordert, gespeichert haben. Oder Sie möchten einer Vorlage möglicherweise keine Pipelineressource hinzufügen. Um Abhängigkeiten zu vermeiden, können Sie die Aufgabe „Pipelineartefakte herunterladen“ verwenden, um alle Buildinformationen an eine Aufgabe zu übergeben.

Wie kann ich eine Pipelineausführung auslösen, wenn mein Docker Hub-Image aktualisiert wird?

Der Container-Ressourcen-Trigger ist für Docker Hub für YAML-Pipelines nicht verfügbar, so dass Sie eine klassische Release-Pipeline einrichten müssen.

Erstellen Sie eine neue Docker Hub-Dienstverbindung.
Erstellen Sie eine klassische Releasepipeline, und fügen Sie ein Docker Hub-Artefakt hinzu. Legen Sie Ihre Dienstverbindung fest, und wählen Sie den Namespace, das Repository, die Version und den Quellalias aus.
Wählen Sie den Trigger aus, und schalten Sie den Continuous Deployment-Trigger auf Aktivieren um. Jeder Docker-Push, der in das ausgewählte Repository erfolgt, erzeugt ein Release.
Erstellen Sie eine neue Phase und einen neuen Auftrag. Fügen Sie zwei Aufgaben hinzu – Docker-Anmeldung und Bash.
- Die Docker-Aufgabe verfügt über die login-Aktion und meldet Sie bei Docker Hub an.
- Die Bash-Aufgabe führt docker pull <hub-user>/<repo-name>[:<tag>] aus.

Wie kann ich meine Webhooks überprüfen und mögliche Probleme beheben?

Erstellen Sie eine Dienstverbindung.

Verweisen Sie im Abschnitt webhooks auf Ihre Dienstverbindung, und benennen Sie Ihren Webhook.

resources:
  webhooks:
    - webhook: MyWebhookTriggerAlias
      connection: MyServiceConnection

Führen Sie Ihre Pipeline aus. Der Webhook wird in Azure als verteilte Aufgabe für Ihre Organisation erstellt.
Führen Sie einen POST-API-Aufruf mit gültigem JSON im Textkörper für https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion> aus. Wenn Sie eine Antwort mit dem Statuscode 200 erhalten, ist Ihr Webhook bereit, von Ihrer Pipeline genutzt zu werden.

Wenn Sie eine Antwort mit dem Statuscode 500 mit dem Fehler Cannot find webhook for the given webHookId ... erhalten, befindet sich Ihr Code möglicherweise in einem Branch, der nicht Ihr Standardbranch ist. Um dieses Problem zu lösen:

Wählen Sie Bearbeiten in Ihrer Pipelineseite.
Wählen Sie im Menü Weitere Aktionen die Option Auslöser aus.
Wählen Sie die Registerkarte YAML und dann Quellen abrufen.
Unter Standardbranch für manuelle und geplante Builds, aktualisieren Sie Ihren Featurebranch.
Wählen Sie Save & queue (Speichern und in Warteschlange einreihen) aus.
Nachdem diese Pipeline erfolgreich ausgeführt wurde, führen Sie einen POST-API-Aufruf mit gültigem JSON im Textkörper für https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion> aus. Sie sollten jetzt eine Antwort mit dem Statuscode 200 erhalten.

Freigeben über

Ressourcen in YAML-Pipelines

Schema der Ressourcen

Pipelines-Ressourcendefinition

Beispiel für Pipelineressourcendefinitionen

Versionsauswertung der Pipelinesartefakte

Manueller oder geplanter Trigger

Auslöser für den Abschluss der Ressourcenpipeline

Pipeline-Artefakt-Download

Variablen der Pipelineressource

Erstellt die Ressourcendefinition

Die downloadBuild-Aufgabe

Definition einer Repositoryressource

Repositoryressourcentypen

Repositoryressourcenvariablen

Auschecken des Schlüsselworts für Repositorys

Containerressourcendefinition

Azure Container Registry-Ressourcentyp

Containerressourcenvariablen

Paketressourcendefinition

Webhooks-Ressourcendefinition

Webhooktrigger

Manuelle Versionsauswahl für Ressourcen

Ressourcenautorisierung in YAML-Pipelines

Genehmigungsüberprüfungen für Ressourcen

Nachverfolgbarkeit

Nachverfolgbarkeit von Pipelines

Nachverfolgbarkeit von Umgebungen

Zugehörige CD-Pipelineinformationen in CI-Pipelines

Ressourcenauslöserprobleme

Häufig gestellte Fragen

Wann sollte ich Pipelineressourcen, die Downloadverknüpfung oder die Aufgabe „Pipelineartefakte herunterladen” verwenden?

Wie kann ich eine Pipelineausführung auslösen, wenn mein Docker Hub-Image aktualisiert wird?

Wie kann ich meine Webhooks überprüfen und mögliche Probleme beheben?

Feedback

Zusätzliche Ressourcen

Freigeben über

Ressourcen in YAML-Pipelines

Schema der Ressourcen

Pipelines-Ressourcendefinition

Beispiel für Pipelineressourcendefinitionen

Versionsauswertung der Pipelinesartefakte

Manueller oder geplanter Trigger

Auslöser für den Abschluss der Ressourcenpipeline

Pipeline-Artefakt-Download

Variablen der Pipelineressource

Erstellt die Ressourcendefinition

Die downloadBuild-Aufgabe

Definition einer Repositoryressource

Repositoryressourcentypen

Repositoryressourcenvariablen

Auschecken des Schlüsselworts für Repositorys

Containerressourcendefinition

Azure Container Registry-Ressourcentyp

Containerressourcenvariablen

Paketressourcendefinition

Webhooks-Ressourcendefinition

Webhooktrigger

Manuelle Versionsauswahl für Ressourcen

Ressourcenautorisierung in YAML-Pipelines

Genehmigungsüberprüfungen für Ressourcen

Nachverfolgbarkeit

Nachverfolgbarkeit von Pipelines

Nachverfolgbarkeit von Umgebungen

Zugehörige CD-Pipelineinformationen in CI-Pipelines

Ressourcenauslöserprobleme

Häufig gestellte Fragen

Wann sollte ich Pipelineressourcen, die Downloadverknüpfung oder die Aufgabe „Pipelineartefakte herunterladen” verwenden?

Wie kann ich eine Pipelineausführung auslösen, wenn mein Docker Hub-Image aktualisiert wird?

Wie kann ich meine Webhooks überprüfen und mögliche Probleme beheben?

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen