Použití šablon YAML v kanálech pro opakovaně použitelné a zabezpečené procesy

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

Šablony umožňují definovat opakovaně použitelný obsah, logiku a parametry v kanálech YAML. Abyste mohli efektivně pracovat se šablonami, musíte mít základní znalosti klíčových konceptů Azure Pipelines, jako jsou fáze, kroky a úlohy.

Existují dva hlavní typy šablon:

• Obsahuje šablony: Vložte opakovaně použitelný obsah do pipeliny. Pokud se šablona používá k zahrnutí obsahu, funguje jako direktiva include v mnoha programovacích jazycích. Obsah ze šablony je vložen do potrubí nebo šablony, která ji zahrnuje.
• Rozšiřuje šablony: Řiďte a definujte schéma pro to, co je povoleno v rourě. Při použití rozšiřující šablony se definuje logika a struktura, kterou musí potrubí dodržovat. To je užitečné pro vynucování standardů zabezpečení, dodržování předpisů nebo organizace.

Šablony vám můžou pomoct urychlit vývoj. V šabloně můžete mít například řadu stejných úloh a pak šablonu zahrnout vícekrát do různých fází kanálu YAML.

Šablony vám také můžou pomoct zabezpečit váš proces. Když šablona určuje, co je v kanálu povolené, šablona definuje logiku, kterou musí následovat jiný soubor. Můžete například chtít omezit, které úlohy se můžou spouštět. V tomto scénáři můžete pomocí šablony zabránit tomu, aby někdo úspěšně spustil úlohu, která porušuje zásady zabezpečení vaší organizace.

Pokud chcete plně využít výhod šablon, měli byste také použít výrazy šablon a parametry šablony.

Požadavky

produkt	Požadavky
Azure DevOps	– Projekt Azure DevOps. – Možnost spouštět pipeliny na agentech hostovaných Microsoftem. Můžete si buď koupit paralelní úlohu, nebo si můžete vyžádat bezplatnou úroveň. – Základní znalost YAML a Azure Pipelines. Další informace naleznete v Vytvoření vašeho prvního potrubí. - Oprávnění:      – Chcete-li vytvořit pipeline: musíte být ve skupině Přispěvatelé a skupina musí mít oprávnění Vytvořit sestavení pipeline nastavená na hodnotu Povolit. Členové skupiny Správci projektů můžou spravovat kanály.     - Chcete-li vytvořit připojení služeb: Pro připojení služeb musíte mít roli Správce nebo Tvůrce.
GitHub	– Účet GitHubu . – Připojení ke službě GitHub pro autorizaci Azure Pipelines.
Azure	Předplatné služby Azure.

Vynucená omezení pro aktualizace šablon

Šablony a výrazy šablon můžou způsobit explozivní růst velikosti a složitosti kanálu. Aby se zabránilo nechtěnému růstu, Azure Pipelines ukládá následující omezení:

• Není možné zahrnout více než 100 samostatných souborů YAML (přímo nebo nepřímo).
• Maximálně 100 úrovní vnoření šablon (šablony včetně jiných šablon)
• Při analýze YAML není využito více než 20 megabajtů paměti (v praxi se obvykle jedná o 600 kB až 2 MB YAML na disku v závislosti na použitých konkrétních funkcích).

Rozšířit ze šablony

Pokud chcete zvýšit zabezpečení, můžete vynutit, aby pipelina vycházela z konkrétní šablony. Soubor start-extends-template.yml definuje parametr buildSteps, který se pak použije v kanálu azure-pipelines.yml. Pokud se v start-extends-template.ymlpředá buildStep s krokem skriptu, je odmítnut a sestavení pipeline selže. Při rozšiřování šablony můžete zvýšit zabezpečení přidáním požadovaného schválení šablony.

# File: start-extends-template.yml
parameters:
- name: buildSteps # the name of the parameter is buildSteps
  type: stepList # data type is StepList
  default: [] # default value of buildSteps
stages:
- stage: secure_buildstage
  pool:
    vmImage: windows-latest
  jobs:
  - job: secure_buildjob
    steps:
    - script: echo This happens before code 
      displayName: 'Base: Pre-build'
    - script: echo Building
      displayName: 'Base: Build'

    - ${{ each step in parameters.buildSteps }}:
      - ${{ each pair in step }}:
          ${{ if ne(pair.value, 'CmdLine@2') }}:
            ${{ pair.key }}: ${{ pair.value }}       
          ${{ if eq(pair.value, 'CmdLine@2') }}: 
            # Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
            '${{ pair.value }}': error         

    - script: echo This happens after code
      displayName: 'Base: Signing'

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: start-extends-template.yml
  parameters:
    buildSteps:  
      - bash: echo Test #Passes
        displayName: succeed
      - bash: echo "Test"
        displayName: succeed
      # Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
      - task: CmdLine@2
        inputs:
          script: echo "Script Test"
      # Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
      - script: echo "Script Test"

Rozšíření ze šablony pomocí prostředků

Můžete také použít extends k rozšíření ze šablony ve vašem Azure potrubí, která obsahuje prostředky.

# File: azure-pipelines.yml
trigger:
- none

extends:
  template: resource-extends-template.yml

# File: resource-extends-template.yml
resources:
  pipelines:
  - pipeline: my-pipeline 
    source: sourcePipeline

steps:
- script: echo "Testing resource template"

Vložení šablony

Můžete vložit obsah z jednoho YAML a znovu ho použít v jiném YAML. Vložení obsahu z jednoho YAML do jiného vám ušetří, abyste museli ručně zahrnout stejnou logiku na více místech. Šablona insert-npm-steps.yml souboru obsahuje kroky, které se znovu používají v azure-pipelines.ymlsouboru .

Poznámka:

Soubory šablony musí existovat v systému souborů na začátku spuštění pipelinu. Na šablony v artefaktu nemůžete odkazovat.

# File: templates/insert-npm-steps.yml

steps:
- script: npm install
- script: yarn install
- script: npm run compile

# File: azure-pipelines.yml

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - template: templates/insert-npm-steps.yml  # Template reference
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - template: templates/insert-npm-steps.yml  # Template reference

Opakované použití kroků napříč několika úlohami

Šablonu můžete vložit a znovu použít jeden nebo více kroků napříč několika úlohami. Kromě kroků ze šablony může každá úloha definovat další kroky.

# File: templates/insert-npm-steps.yml
steps:
- script: npm install
- script: npm test

# File: azure-pipelines.yml

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - template: templates/insert-npm-steps.yml  # Template reference

- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - template: templates/insert-npm-steps.yml  # Template reference

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo This script runs before the template's steps, only on Windows.
  - template: templates/insert-npm-steps.yml  # Template reference
  - script: echo This step runs after the template's steps.

Opakované použití úloh napříč několika šablonami

Podobně jako u kroků je možné úlohy opakovaně používat se šablonami.

# File: templates/insert-jobs.yml
jobs:
- job: Ubuntu
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello Ubuntu"

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - bash: echo "Hello Windows"

# File: azure-pipelines.yml

jobs:
- template: templates/insert-jobs.yml  # Template reference

Při práci s více úlohami nezapomeňte odebrat název úlohy v souboru šablony, aby nedocházelo ke konfliktům.

# File: templates/insert-multiple-jobs.yml
jobs:
- job: 
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello Ubuntu"

- job:
  pool:
    vmImage: 'windows-latest'
  steps:
  - bash: echo "Hello Windows"

# File: azure-pipelines.yml

jobs:
- template: templates/insert-multiple-job.yml  # Template reference
- template: templates/insert-multiple-jobs.yml  # Template reference
- template: templates/insert-multiple-jobs.yml  # Template reference

Opakované použití fází napříč několika šablonami

Fáze lze také opakovaně používat se šablonami.

# File: templates/insert-stage1.yml
stages:
- stage: Angular
  jobs:
  - job: angularinstall
    steps:
    - script: npm install angular

# File: templates/insert-stage2.yml
stages:
- stage: Build
  jobs:
  - job: build
    steps:
    - script: npm run build

# File: azure-pipelines.yml
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: Install
  jobs: 
  - job: npminstall
    steps:
    - task: Npm@1
      inputs:
        command: 'install'
- template: templates/insert-stage1.yml # Template reference
- template: templates/insert-stage2.yml # Template reference

Přidání parametrů do šablon úloh, fází a kroků

V následujících šablonách:

• templates/npm-with-params.yml definuje dva parametry: name a vmImage vytvoří úlohu s parametrem name pro název úlohy a parametrem vmImage pro image virtuálního počítače.
• Kanál (azure-pipelines.yml) třikrát odkazuje na šablonu s různými hodnotami parametrů odkazujícími na názvy operačních systémů a imagí virtuálních počítačů.
• Vytvořený kanál běží na jiném obrazu virtuálního počítače a je pojmenován podle zadaného operačního systému. Každá úloha provádí instalaci npm a testovací kroky npm.

# File: templates/npm-with-params.yml

parameters:
- name: name  # defaults for any parameters that aren't specified
  default: ''
- name: vmImage
  default: ''

jobs:
- job: ${{ parameters.name }}
  pool: 
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

Při použití šablony ve vašem pracovním procesu zadejte hodnoty parametrů šablony.

# File: azure-pipelines.yml

jobs:
- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: Linux
    vmImage: 'ubuntu-latest'

- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: macOS
    vmImage: 'macOS-latest'

- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: Windows
    vmImage: 'windows-latest'

Šablony fází s více parametry

V následujících šablonách:

• Šablona stage-template.yml definuje čtyři parametry: stageName, jobName, vmImagea scriptPath, všechny řetězce typu. Šablona vytvoří fázi pomocí parametru stageName k nastavení názvu fáze, definuje úlohu s jobNamea obsahuje krok pro spuštění skriptu.
• Potrubí azure-pipeline.yml poté dynamicky definuje etapy a úkoly pomocí parametrů a spustí úkol, který provádí skript, build-script.sh.

# stage-template.yml

parameters:
  - name: stageName
    type: string
  - name: jobName
    type: string
  - name: vmImage
    type: string
  - name: scriptPath
    type: string

stages:
  - stage: ${{ parameters.stageName }}
    jobs:
      - job: ${{ parameters.jobName }}
        pool:
          vmImage: ${{ parameters.vmImage }}
        steps:
          - script: ./${{ parameters.scriptPath }}

# azure-pipelines.yml
trigger:
- main

stages:
- template: stage-template.yml
  parameters:
    stageName: 'BuildStage'
    jobName: 'BuildJob'
    scriptPath: 'build-script.sh' # replace with script in your repository
    vmImage: 'ubuntu-latest'

Šablony s kroky a parametry

Parametry můžete použít také se šablonami kroků nebo fází.

V následujících šablonách:

• Šablona (templates/steps-with-params.yml) definuje parametr s výchozí runExtendedTests hodnotou false.
• Potrubí (azure-pipelines.yml) se spustí npm test a npm test --extended, protože je parametr runExtendedTests pravdivý.

# File: templates/steps-with-params.yml

parameters:
- name: 'runExtendedTests'  # defaults for any parameters that aren't specified
  type: boolean
  default: false

steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, true) }}:
  - script: npm test --extended

Při používání šablony v pipeline zadejte hodnoty parametrů šablony.

# File: azure-pipelines.yml

steps:
- script: npm install

- template: templates/steps-with-params.yml  # Template reference
  parameters:
    runExtendedTests: 'true'

Poznámka:

Skalární parametry bez zadaného typu se považují za řetězce. Předpokládejme, že eq(true, parameters['myparam']) vrátí true, i když parametr myparam je slovo false, pokud myparam není explicitně nastaveno boolean. Neprázdné řetězce se v logickém kontextu převádějí na true. Tento výraz lze přepsat tak, aby explicitně porovnával řetězce: eq(parameters['myparam'], 'true').

Parametry nejsou omezeny na skalární řetězce. Podívejte se na seznam datových typů. Například pomocí object typu:

# azure-pipelines.yml
jobs:
- template: process.yml
  parameters:
    pool:   # this parameter is called `pool`
      vmImage: ubuntu-latest  # and it's a mapping rather than a string

# process.yml
parameters:
- name: 'pool'
  type: object
  default: {}

jobs:
- job: build
  pool: ${{ parameters.pool }}

Opakované použití proměnné

Proměnné lze definovat v jednom JAZYCE YAML a zahrnout do jiné šablony. To může být užitečné, pokud chcete uložit všechny proměnné do jednoho souboru. Pokud k zahrnutí proměnných do kanálu používáte šablonu, můžete ji použít jenom k definování proměnných. Při rozšiřování šablony můžete použít kroky a složitější logiku.

Poznámka:

Místo proměnných použijte parametry pro přidání zabezpečení, jako je zadání typu. Další informace o důležitosti použití parametrů pro úlohy prostředí najdete v dokumentaci k ověření parametrů pro povolení argumentů úloh prostředí.

V tomto příkladu je proměnná favoriteVeggie zahrnuta do azure-pipelines.yml.

# File: insert-vars.yml
variables:
  favoriteVeggie: 'brussels sprouts'

# File: azure-pipelines.yml

variables:
- template: insert-vars.yml  # Template reference

steps:
- script: echo My favorite vegetable is ${{ variables.favoriteVeggie }}.

Šablony proměnných s parametry

Parametry můžete předat proměnným pomocí šablon. V tomto příkladu předáváte parametr DIRECTORY do proměnné RELEASE_COMMAND.

# File: templates/package-release-with-params.yml

parameters:
- name: DIRECTORY 
  type: string
  default: "." # defaults for any parameters that specified with "." (current directory)

variables:
- name: RELEASE_COMMAND
  value: grep version ${{ parameters.DIRECTORY }}/package.json | awk -F \" '{print $4}'  

Při používání šablony v pipeline zadejte hodnoty parametrů šablony.

# File: azure-pipelines.yml

variables: # Global variables
  - template: package-release-with-params.yml # Template reference
    parameters:
      DIRECTORY: "azure/checker"

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: Release_Stage 
  displayName: Release Version
  variables: # Stage variables
  - template: package-release-with-params.yml  # Template reference
    parameters:
      DIRECTORY: "azure/todo-list"
  jobs: 
  - job: A
    steps: 
    - bash: $(RELEASE_COMMAND) #output release command

Rozšíření pomocí šablony a použití šablony s proměnnými

Jedním z běžných scénářů je mít pipelinu s fázemi pro vývoj, testování a produkci, která používá jak šablonu zahrnující proměnné, tak šablonu rozšiřující pro fáze a úlohy.

V následujícím příkladu variables-template.yml definuje sadu proměnných virtuálního počítače, které se pak používají v azure-pipeline.yml.

# variables-template.yml

variables:
- name: devVmImage
  value: 'ubuntu-latest'
- name: testVmImage
  value: 'ubuntu-latest'
- name: prodVmImage
  value: 'ubuntu-latest'

Následující soubor stage-template.yml definuje opakovaně použitelnou konfiguraci fáze se třemi parametry (name, vmImage, steps) a úlohou s názvem Build.

# stage-template.yml
parameters:
- name: name
  type: string
  default: ''
- name: vmImage
  type: string
  default: ''
- name: steps
  type: stepList
  default: []

stages:
- stage: ${{ parameters.name }}
  jobs:
  - job: Build
    pool:
      vmImage: ${{ parameters.vmImage }}
    steps: ${{ parameters.steps }}

Následující kanál importuje azure-pipelines.ymlproměnné z variables-template.ymla pak použije stage-template.yml šablonu pro každou fázi. Každá fáze (vývoj, testování, prod) je definována se stejnou šablonou, ale s různými parametry, což vede k konzistenci napříč fázemi a zároveň umožňuje přizpůsobení. Fáze "Prod" obsahuje proměnnou prostředí například k použití při autentizaci. Další informace o definování parametrů najdete v tématu Parametry šablony.

# azure-pipelines.yml
trigger:
- main

variables:
- template: variables-template.yml

stages:
- template: stage-template.yml
  parameters:
    name: Dev
    vmImage: ${{ variables.devVmImage }}
    steps:
      - script: echo "Building in Dev"
- template: stage-template.yml
  parameters:
    name: Test
    vmImage: ${{ variables.testVmImage }}
    steps:
      - script: echo "Testing in Test"
- template: stage-template.yml
  parameters:
    name: Prod
    vmImage: ${{ variables.prodVmImage }}
    steps:
      - script: echo "Deploying to Prod"
        env:
          SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Cesty k referenční šabloně

Cesty k šablonám mohou být absolutní, v rámci úložiště, nebo relativní k souboru, který je připojuje.

Chcete-li použít absolutní cestu, musí cesta šablony začínat na ./ Všechny ostatní cesty jsou považovány za relativní.

Tady je příklad vnořené hierarchie.

|
+-- fileA.yml
|
+-- dir1/
     |
     +-- fileB.yml
     |
     +-- dir2/
          |
          +-- fileC.yml

Pak můžete v fileA.yml odkazovat na fileB.yml a fileC.yml takto.

steps:
- template: dir1/fileB.yml
- template: dir1/dir2/fileC.yml

Pokud fileC.yml je vaším výchozím bodem, můžete zahrnout fileA.yml a fileB.yml takto.

steps:
- template: ../../fileA.yml
- template: ../fileB.yml

Pokud je fileB.yml váš výchozí bod, můžete zahrnout fileA.yml a fileC.yml tímto způsobem.

steps:
- template: ../fileA.yml
- template: dir2/fileC.yml

Alternativně lze fileB.yml použít k odkazu na fileA.yml a fileC.yml pomocí absolutních cest, jako je tato.

steps:
- template: /fileA.yml
- template: /dir1/dir2/fileC.yml

Ukládání šablon v jiných úložištích

Šablony můžete uchovávat v jiných úložištích. Předpokládejme například, že máte základní kanál, který chcete, aby používaly všechny vaše aplikační kanály. Šablonu můžete umístit do základního úložiště a pak na ni odkazovat z každého úložiště vaší aplikace:

# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
- name: 'vmImage'
  default: 'ubuntu-22.04'
  type: string

jobs:
- job: Build
  pool:
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

Teď můžete tuto šablonu znovu použít v několika kanálech. resources Pomocí specifikace zadejte umístění základního úložiště. Když odkazujete na základní úložiště, použijte @ a název, který resourcesjste mu dali .

# Repo: Contoso/LinuxProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates

jobs:
- template: common.yml@templates  # Template reference

# Repo: Contoso/WindowsProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates
      ref: refs/tags/v1.0 # optional ref to pin to

jobs:
- template: common.yml@templates  # Template reference
  parameters:
    vmImage: 'windows-latest'

Pro type: githubje name<identity>/<repo> jako v předchozím příkladu. Pro type: git (Azure Repos) name je <project>/<repo>. Pokud je tento projekt v samostatné organizaci Azure DevOps, musíte nakonfigurovat připojení služby typu Azure Repos/Team Foundation Server s přístupem k projektu a zahrnout ho do YAML:

resources:
  repositories:
  - repository: templates
    name: Contoso/BuildTemplates
    endpoint: myServiceConnection # Azure DevOps service connection
jobs:
- template: common.yml@templates

Úložiště se vyřeší jen jednou, když se potrubí spustí. Potom se stejný prostředek použije během spuštění kanálu. Používají se jenom soubory šablon. Jakmile se šablony plně rozšíří, spustí se poslední pipeline, jako by byla definována zcela ve zdrojovém úložišti. To znamená, že nemůžete použít skripty z úložiště šablony ve vaší pipelině.

Pokud chcete použít konkrétní, pevnou verzi šablony, nezapomeňte ji připnout k ref. refs jsou buď větve (refs/heads/<name>) nebo značky (refs/tags/<name>). Pokud chcete připnout konkrétní potvrzení, nejprve vytvořte značku odkazující na toto potvrzení a pak na tuto značku připněte.

Poznámka:

Pokud není zadán žádný ref, kanál ve výchozím nastavení používá refs/heads/main.

Můžete také připnout na konkrétní commit v Gitu pomocí hodnoty SHA pro zdroj úložiště. Hodnota SHA je 40znakový hashovací kontrolní součet, který jednoznačně identifikuje commit.

resources:
  repositories:
    - repository: templates
      type: git
      name: Contoso/BuildTemplates
      ref: 1234567890abcdef1234567890abcdef12345678

Můžete také použít @self k odkazování na úložiště, kde byl nalezen původní kanál. To je vhodné pro použití v extends šablonách, pokud chcete odkazovat na obsah v úložišti rozšiřujícího se datového toku. Příklad:

# Repo: Contoso/Central
# File: template.yml
jobs:
- job: PreBuild
  steps: []

  # Template reference to the repo where this template was
  # included from - consumers of the template are expected
  # to provide a "BuildJobs.yml"
- template: BuildJobs.yml@self

- job: PostBuild
  steps: []

# Repo: Contoso/MyProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: git
      name: Contoso/Central

extends:
  template: template.yml@templates

# Repo: Contoso/MyProduct
# File: BuildJobs.yml
jobs:
- job: Build
  steps: []

časté otázky

Jak se používají proměnné v šablonách?

Někdy je užitečné nastavit parametry na hodnoty na základě proměnných. Parametry se rozšiřují v rané fázi zpracování běhu pipeline, takže nejsou k dispozici všechny proměnné. Informace o předdefinovaných proměnných, které jsou k dispozici v šablonách, najdete v tématu Používání předdefinovaných proměnných.

V tomto příkladu se předdefinované proměnné Build.SourceBranchBuild.Reason používají v podmínkách v template.yml.

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: template.yml

# File: template.yml
steps:
- script: echo Build.SourceBranch = $(Build.SourceBranch) # outputs refs/heads/main
- script: echo Build.Reason = $(Build.Reason) # outputs IndividualCI
- ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}: 
  - script: echo I run only if Build.SourceBranch = refs/heads/main 
- ${{ if eq(variables['Build.Reason'], 'IndividualCI') }}: 
  - script: echo I run only if Build.Reason = IndividualCI 
- script: echo I run after the conditions