Resurser i YAML-pipelines

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

I den här artikeln beskrivs resurser för YAML-pipelines. En resurs är allt som används av en pipeline som finns utanför pipelinen. När du har definierat en resurs kan du använda den var som helst i pipelinen.

Resurser ger fullständig spårning för de tjänster som din pipeline använder, inklusive version, artefakter, associerade incheckningar och arbetsobjekt. Du kan automatisera dina DevOps-arbetsflöden helt genom att prenumerera på utlösande händelser på dina resurser.

Resursschema

Resurser i YAML representerar källor till pipelines, byggen, lagringsplatser, containrar, paket och webhooks. Fullständig schemainformation finns i resursdefinitionen i YAML-schemareferensen för Azure Pipelines.

När en resurs utlöser en pipeline anges följande variabler:

resources.triggeringAlias
resources.triggeringCategory

Variabeln Build.Reason måste vara ResourceTrigger för att dessa värden ska kunna anges. Värdena är tomma om en resurs inte utlöste pipelinekörningen.

Resursdefinition för pipelines

Om du har en pipeline som producerar artefakter kan du använda artefakterna genom att definiera en pipelines resurs. Endast Azure Pipelines kan använda resursen pipelines . Du kan ange utlösare för dina arbetsflöden för kontinuerlig distribution (CD) på en pipelineresurs.

I resursdefinitionen pipeline är ett unikt värde som du kan använda för att referera till pipelineresursen senare i pipelinen. source är namnet på pipelinen som producerade pipelineartefakten. Fullständig schemainformation finns i definitionen resources.pipelines.pipeline.

Du använder etiketten som definieras av pipeline för att referera till pipelineresursen från andra delar av pipelinen, till exempel när du använder pipelineresursvariabler eller laddar ned artefakter. Ett annat sätt att ladda ned pipelineartefakter finns i Ladda ned artefakter.

Exempel på pipelineresursdefinitioner

I följande exempel används artefakter från en pipeline i samma projekt.

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

Om du vill använda en pipeline från ett annat projekt inkluderar du projektnamnet och källnamnet. I följande exempel används branch för att matcha standardversionen när pipelinen utlöses manuellt eller schemaläggs. Grenindata kan inte ha jokertecken.

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

I följande exempel visas en pipelineresurs med en enkel utlösare.

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

I följande exempel visas en pipelineresurs trigger med grenvillkor.

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

I följande exempel används stages filter för att utvärdera utlösarvillkor för CD-pipelines. Faser använder operatorn AND . När alla angivna steg har slutförts utlöses CD-pipelinen.

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

I följande exempel används tags filter för standardversionsutvärdering och för utlösare. Taggar använder operatorn AND .

tags Är inställda på den kontinuerliga integreringen (CI) eller CD-pipelinen. De här taggarna skiljer sig från taggarna som anges på grenar i Git-lagringsplatsen.

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

Utvärdering av pipelinesartefaktversion

Resurspipelinens artefaktversion beror på hur pipelinen utlöses.

Manuell eller schemalagd utlösare

Om pipelinekörningen utlöses eller schemaläggs manuellt definierar värdena för versionegenskaperna , branchoch tags artefaktversionen. Indata branch kan inte ha jokertecken. Egenskaperna tags använder operatorn AND .

Följande pipeline resursdefinition använder branch egenskaperna och tags för att utvärdera standardversionen när pipelinen utlöses manuellt eller schemaläggs. När du manuellt utlöser pipelinen som ska köras MyCIAlias är pipelineartefaktversionen den senaste versionen som gjorts på grenen main som har taggarna Production och PrepProduction .

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

Utlösare för slutförande av resurspipeline

När en pipeline utlöses på grund av att en av dess resurspipelines har slutförts är artefaktversionen versionen av den utlösande pipelinen. Värdena för versionegenskaperna , branchoch tags ignoreras.

Följande pipeline körs när SmartHotel-CI resurspipelinen:

• Körs på en av grenarna releases eller på grenen main
• Är taggad med både Verified och Signed
• Slutför både faserna Production och PreProduction

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

Nedladdning av pipelineartefakt

Steget download laddar ned artefakter som är associerade med den aktuella körningen eller med en annan pipelineresurs.

Alla artefakter från den aktuella pipelinen och alla dess pipeline resurser laddas ned automatiskt och görs tillgängliga i början av varje distributionsjobb. Du kan åsidosätta det här beteendet genom att ange download till eller genom att noneange en annan pipelineresursidentifierare.

Vanliga jobbartefakter laddas inte ned automatiskt. Använd download explicit när det behövs.

Artefakter från resursen pipeline laddas ned till $(PIPELINE. WORKSPACE)/<pipeline-identifier>/<artifact-identifier> folder. Mer information finns i Publicera och ladda ned pipelineartefakter.

Den valfria artifact egenskapen anger artefaktnamn. Om det inte anges laddas alla tillgängliga artefakter ned. Den valfria patterns egenskapen definierar mönster som representerar filer som ska inkluderas. Fullständig schemainformation finns i definitionen steps.download.

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

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)

Skapar resursdefinition

Om du har ett externt CI-byggsystem som producerar artefakter kan du använda artefakter med builds resurser. En build resurs kan komma från valfritt externt CI-system som Jenkins, TeamCity eller CircleCI.

Kategorin builds är utökningsbar. Du kan skriva ett tillägg för att använda artefakter från byggtjänsten och introducera en ny typ av tjänst som en del av builds.

build I definitionen version är standardvärdet för den senaste lyckade versionen. trigger Är inte aktiverat som standard och måste anges uttryckligen. Fullständig schemainformation finns i definitionen resources.builds.build.

I följande exempel är Jenkins resursen type.

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

DownloadBuild-uppgiften

Resursartefakterna build laddas inte ned automatiskt i dina jobb/distributionsjobb. Om du vill använda artefakter från resursen build som en del av dina jobb måste du uttryckligen downloadBuild lägga till uppgiften. Du kan anpassa nedladdningsbeteendet för varje distribution eller jobb.

Den här aktiviteten matchas automatiskt med motsvarande nedladdningsaktivitet för den typ av build resurs som körningen definierar. Artefakter från resursen build laddas ned till $(PIPELINE. WORKSPACE)/<build-identifier>/ folder.

downloadBuild I definitionen anger du resursen som du vill ladda ned artefakter från. Den valfria artifact egenskapen anger artefakter som ska laddas ned. Om det inte anges laddas alla artefakter som är associerade med resursen ned.

Den valfria patterns egenskapen definierar en minimatchningssökväg eller lista över sökvägar för minimatchning som ska laddas ned. Om den är tom laddas hela artefakten ned. Följande kodfragment laddar till exempel bara ned *.zip-filerna .

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

Fullständig schemainformation finns i definitionen steps.downloadBuild.

Resursdefinition för lagringsplats

Med nyckelordet repository kan du ange en extern lagringsplats. Du kan använda den här resursen om pipelinen har mallar på en annan lagringsplats eller om du vill använda utcheckning med flera lagringsplatser med en lagringsplats som kräver en tjänstanslutning. Du måste meddela systemet om dessa lagringsplatser.

Till exempel:

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

Fullständig schemainformation finns i definitionen resources.repositories.repository.

Resurstyper för lagringsplats

Azure Pipelines stöder följande värden för lagringsplatsens typ: git, github, githubenterpriseoch bitbucket.

• Typen git refererar till Azure Repos Git-lagringsplatser.
• GitHub Enterprise-lagringsplatser kräver en GitHub Enterprise-tjänstanslutning för auktorisering.
• Bitbucket Cloud-lagringsplatser kräver en Bitbucket Cloud-tjänstanslutning för auktorisering.

Resursvariabler för lagringsplats

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

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

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

Nyckelord för utcheckning för lagringsplatser

Lagringsplatser från resursen repository synkroniseras inte automatiskt i dina jobb. Använd nyckelordet checkout för att hämta en lagringsplats som definierats som en del av resursen repository . Fullständig schemainformation finns i definitionen steps.checkout.

Mer information finns i Kolla in flera lagringsplatser i pipelinen.

Resursdefinition för containrar

Om du behöver använda containeravbildningar som en del av dina CI/CD-pipelines kan du använda containers resurser. En container resurs kan vara ett offentligt eller privat Docker-register eller en Azure Container Registry-instans.

Du kan använda en allmän containerresursavbildning som en del av jobbet eller använda resursen för containerjobb. Om din pipeline kräver stöd för en eller flera tjänster måste du skapa och ansluta till tjänstcontainrar. Du kan använda volymer för att dela data mellan tjänster.

Om du behöver använda avbildningar från ett Docker-register som en del av pipelinen kan du definiera en allmän containerresurs. Inget type nyckelord krävs. Till exempel:

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

Fullständig schemainformation finns i definitionen resources.containers.container.

Resurstyp för Azure Container Registry

Om du vill använda dina Azure Container Registry-avbildningar kan du använda den förstklassiga containerresurstypen acr. Du kan använda den här resurstypen som en del av dina jobb och aktivera automatiska pipelineutlösare.

Du behöver behörigheter som deltagare eller ägare för att Azure Container Registry ska kunna använda automatiska pipelineutlösare. Mer information finns i Roller och behörigheter för Azure Container Registry.

Om du vill använda acr resurstypen måste du ange azureSubscriptionvärdena , resourceGroupoch repository för ditt Azure-containerregister. Till exempel:

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

Containerresursvariabler

När du har definierat en container som en resurs skickas metadata för containeravbildningar till pipelinen som variabler. Information som avbildning, register och anslutningsinformation är tillgänglig för alla jobb som används i dina containerdistributionsuppgifter.

Containerresursvariabler fungerar med Docker och Azure Container Registry. Du kan inte använda containerresursvariabler för lokala avbildningscontainrar. Variabeln location gäller endast för acr typen av containerresurser.

I följande exempel finns en Azure Resource Manager-tjänstanslutning med namnet arm-connection. Mer information finns i Azure-containerregister, lagringsplatser och avbildningar.

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)

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

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

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

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

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

Manuell versionsväljare för resurser

När du manuellt utlöser en CD YAML-pipeline utvärderar Azure Pipelines automatiskt standardversionerna för de resurser som definierats i pipelinen baserat på de indata som tillhandahålls. Azure Pipelines anser dock endast att ci-körningar har slutförts när standardversionen utvärderas för schemalagda utlösare, eller om du inte väljer en version manuellt.

Du kan använda resursversionsväljaren för att manuellt välja en annan version när du skapar en körning. Resursversionsväljaren stöds för pipeline-, bygg-, lagringsplats-, container- och paketresurser.

För pipelineresurser kan du se alla tillgängliga körningar i alla grenar, söka efter dem baserat på pipelinenumret eller grenen och välja en körning som lyckas, misslyckades eller pågår. Den här flexibiliteten säkerställer att du kan köra cd-pipelinen om du är säker på att en körning har skapat alla artefakter du behöver. Du behöver inte vänta tills en CI-körning har slutförts eller köra den igen på grund av ett orelaterat fasfel.

Om du vill använda resursversionsväljaren går du till fönstret Kör pipeline , väljer Resurser och väljer sedan en resurs och väljer en specifik version i listan över tillgängliga versioner.

För resurser där du inte kan hämta tillgängliga versioner, till exempel GitHub-paket, tillhandahåller versionsväljaren ett textfält så att du kan ange den version som körningen ska välja.

Resursauktorisering i YAML-pipelines

Resurser måste auktoriseras innan de kan användas i pipelines. Resursägare styr de användare och pipelines som kan komma åt deras resurser. Det finns flera sätt att auktorisera en YAML-pipeline för att använda resurser.

• Använd resursadministrationsmiljön för att auktorisera alla pipelines för åtkomst till resursen. Till exempel hanteras variabelgrupper och säkra filer på sidan Bibliotek under Pipelines, och agentpooler och tjänstanslutningar hanteras i Projektinställningar. Den här auktoriseringen är praktisk om du inte behöver begränsa åtkomsten till resurser, till exempel för testresurser.

• När du skapar en pipeline godkänns alla resurser som refereras i YAML-filen automatiskt för användning av pipelinen om du har användarrollen för dessa resurser.

• Om du lägger till en resurs i en YAML-fil och bygget misslyckas med ett fel som Could not find a <resource> with name <resource-name>. The <resource> does not exist or has not been authorized for use.visas ett alternativ för att auktorisera resurserna i den misslyckade versionen.

  Om du är medlem i användarrollen för resursen kan du välja det här alternativet och auktorisera resursen i den misslyckade versionen. När resursen har auktoriserats kan du starta en ny version.

• Kontrollera att agentpoolens säkerhetsroller för projektet är korrekta.

Godkännandekontroller för resurser

Du kan använda godkännandekontroller och mallar för att manuellt styra när en resurs körs. Med den nödvändiga godkännandekontrollen för mallar kan du kräva att alla pipelines med hjälp av en resurs eller miljö utökas från en specifik YAML-mall.

Om du anger ett obligatoriskt mallgodkännande ser du till att resursen endast används under specifika förhållanden och förbättrar säkerheten. Mer information om hur du förbättrar pipelinesäkerhet med mallar finns i Använda mallar för säkerhet.

Spårbarhet

Azure Pipelines ger fullständig spårbarhet för alla resurser som förbrukas på en pipeline- eller distributionsjobbnivå.

Pipelinespårning

Azure Pipelines visar följande information för varje pipelinekörning:

• Om en resurs utlöste pipelinen utlöses den resurs som utlöste pipelinen.
• Resursversionen och de artefakter som används.
• Incheckningar som är associerade med varje resurs.
• Arbetsobjekt som är associerade med varje resurs.

Miljöspårbarhet

När en pipeline distribueras till en miljö kan du se en lista över resurser som förbrukas. Vyn innehåller resurser som förbrukas som en del av distributionsjobben och deras associerade incheckningar och arbetsobjekt.

Information om associerade CD-pipelines i CI-pipelines

För att tillhandahålla spårbarhet från slutpunkt till slutpunkt kan du spåra vilka CD-pipelines som använder en specifik CI-pipeline via resursen pipelines . Om andra pipelines använder din CI-pipeline visas fliken Associerade pipelines i körningsvyn. Vyn visar alla CD YAML-pipelinekörningar som förbrukade din CI-pipeline och artefakterna från den.

Problem med resursutlösare

Resursutlösare kan inte köras eftersom:

• Källan för den tillhandahållna tjänstanslutningen är ogiltig, det finns syntaxfel i utlösaren eller så är utlösaren inte konfigurerad.
• Utlösarvillkor matchas inte.

Om du vill se varför pipelineutlösare inte kunde köras väljer du menyalternativet Utlösa problem på sidan för pipelinedefinition. Utlösarproblem är endast tillgängliga för icke-lagringsresurser.

På sidan Utlösarproblem beskriver fel- och varningsmeddelandena varför utlösaren misslyckades.

Vanliga frågor

När ska jag använda pipelineresurser, nedladdningsgenvägen eller uppgiften Ladda ned pipelineartefakter?

Att använda en pipelines resurs är ett sätt att använda artefakter från en CI-pipeline och även konfigurera automatiserade utlösare. En resurs ger dig fullständig insyn i processen genom att visa den version som används, artefakter, incheckningar och arbetsobjekt. När du definierar en pipelineresurs hämtas de associerade artefakterna automatiskt i distributionsjobb.

Du kan använda download genvägen för att ladda ned artefakterna i byggjobb eller för att åsidosätta nedladdningsbeteendet i distributionsjobb. Mer information finns i definitionen steps.download.

Uppgiften Ladda ned pipelineartefakter ger inte spårbarhet eller utlösare, men ibland är det klokt att använda den här uppgiften direkt. Du kan till exempel ha en skriptuppgift lagrad i en annan mall som kräver att artefakter från en version laddas ned. Eller så kanske du inte vill lägga till en pipelineresurs i en mall. För att undvika beroenden kan du använda uppgiften Ladda ned pipelineartefakter för att skicka all bygginformation till en uppgift.

Hur utlöser jag en pipelinekörning när min Docker Hub-avbildning uppdateras?

Containerresursutlösaren är inte tillgänglig för Docker Hub för YAML-pipelines, så du måste konfigurera en klassisk versionspipeline.

1. Skapa en ny Docker Hub-tjänstanslutning.
2. Skapa en klassisk versionspipeline och lägg till en Docker Hub-artefakt. Ange tjänstanslutningen och välj namnrymd, lagringsplats, version och källalias.
3. Välj utlösaren och växla den kontinuerliga distributionsutlösaren till Aktivera. Varje Docker-push som sker till den valda lagringsplatsen skapar en version.
4. Skapa en ny fas och ett nytt jobb. Lägg till två uppgifter, Docker-inloggning och Bash.
   • Docker-aktiviteten har åtgärden login och loggar in dig på Docker Hub.
   • Bash-aktiviteten kör docker pull <hub-user>/<repo-name>[:<tag>].

Hur kan jag verifiera och felsöka min webhook?

1. Skapa en tjänstanslutning.

2. Referera till tjänstanslutningen och ge webhooken namnet i avsnittet webhooks .

   resources:
     webhooks:
       - webhook: MyWebhookTriggerAlias
         connection: MyServiceConnection
   

3. Kör din pipeline. Webhooken skapas i Azure som en distribuerad uppgift för din organisation.

4. Utför ett POST API-anrop med giltig JSON i brödtexten till https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion>. Om du får ett 200-statuskodsvar är webhooken redo att användas av din pipeline.

Om du får ett 500-statuskodsvar med felet Cannot find webhook for the given webHookId ...kan koden finnas i en gren som inte är din standardgren. Så här löser du problemet:

1. Välj Redigera på pipelinesidan.
2. På menyn Fler åtgärder väljer du Utlösare.
3. Välj fliken YAML och välj sedan Hämta källor.
4. Under Standardgren för manuella och schemalagda versioner uppdaterar du funktionsgrenen.
5. Välj Spara och kö.
6. När pipelinen har körts utför du ett POST API-anrop med giltig JSON i brödtexten till https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion>. Nu bör du få ett 200-statuskodsvar.

Relaterat innehåll

• Om resurser för Azure Pipelines
• Definiera variabler
• Lägga till och använda variabelgrupper
• Skapa och målinrikta en miljö
• Använda YAML-pipelineredigeraren
• YAML-schemareferens