Referenční informace k použití šablony

  • Článek

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

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

Š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áš kanál. 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.

Existují dva typy šablon: zahrnuje a rozšiřuje.

  • Obsahuje šablony , které umožňují vložit opakovaně použitelný obsah se šablonou. Pokud se šablona používá k zahrnutí obsahu, funguje jako direktiva include v mnoha programovacích jazycích. Obsah z jednoho souboru se vloží do jiného souboru.
  • Rozšiřuje ovládací prvek šablony , který je povolený v kanálu. Když rozšíření šablony určuje, co je povoleno v kanálu, šablona definuje logiku, kterou musí následovat jiný soubor.

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

Vynucená omezení

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

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

Pomocí šablon můžete definovat logiku jednou a pak ji několikrát znovu použít. Šablony spojují obsah více souborů YAML do jednoho kanálu. Parametry můžete předat do šablony z nadřazeného kanálu.

Rozšíření ze šablony

Pokud chcete zvýšit zabezpečení, můžete vynutit, aby se kanál rozšířil z konkrétní šablony. Soubor start.yml definuje parametr buildSteps, který se pak použije v kanálu azure-pipelines.yml. Pokud start.ymlse buildStep předá krok skriptu, zamítne se a sestavení kanálu 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.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.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 rozšíření ze šablony v kanálu Azure, který obsahuje prostředky.

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

extends:
  template: resource-template.yml

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

steps:
- script: echo "Testing resource template"

Vložení šablony

Obsah můžete zkopírovat z jednoho YAML a znovu ho použít v jiném YAML. Kopírování obsahu z jednoho YAML do jiného vám ušetří, že budete muset ručně zahrnout stejnou logiku na více místech. Šablona include-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í kanálu. Na šablony v artefaktu nemůžete odkazovat.

# File: templates/include-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/include-npm-steps.yml  # Template reference
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - template: templates/include-npm-steps.yml  # Template reference

Opakované použití kroku

Š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/npm-steps.yml
steps:
- script: npm install
- script: npm test

# File: azure-pipelines.yml

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

- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - template: templates/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/npm-steps.yml  # Template reference
  - script: echo This step runs after the template's steps.

Opakované použití úlohy

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

# File: templates/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/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/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/jobs.yml  # Template reference
- template: templates/jobs.yml  # Template reference
- template: templates/jobs.yml  # Template reference

Opětovné použití dílčí fáze

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

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

# File: templates/stages2.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/stages1.yml # Template reference
- template: templates/stages2.yml # Template reference

Šablony úloh, fází a kroků s parametry

# 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 využívání šablony v kanálu 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'

Parametry můžete použít také se šablonami kroků nebo fází. Například kroky s parametry:

# 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 využívání šablony v kanálu 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. Například eq(true, parameters['myparam']) vrátí true, i když myparam parametr je slovo false, pokud myparam není explicitně provedeno boolean. Neprázdné řetězce se přetypují do true logického kontextu. 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. Pokud chcete omezit typ, použijte místo proměnných parametry .

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

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

# File: azure-pipelines.yml

variables:
- template: vars.yml  # Template reference

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

Šablony proměnných s parametrem

Parametry můžete předat proměnným pomocí šablon. V tomto příkladu DIRECTORY předáváte parametr 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 využívání šablony v kanálu 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

Cesty k referenční šabloně

Cesty šablony můžou být absolutní cestou v úložišti nebo relativní vzhledem k souboru, který zahrnuje.

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 na fileA.yml tuto možnost odkazovat fileB.yml a fileC.yml tomuto typu.

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

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

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

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

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

Alternativně fileB.yml můžete odkazovat a fileA.ymlfileC.yml používat absolutní cesty, jako je tato.

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

Použití jiných úložišť

Š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 používat všechny kanály aplikace. Š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: github, name je <identity>/<repo> stejně jako v příkladech výše. Pro type: git (Azure Repos) name je <project>/<repo>. Pokud je tento projekt v samostatné organizaci Azure DevOps, budete muset 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 přeloží jenom jednou, když se kanál spustí. Potom se stejný prostředek použije po dobu trvání kanálu. Používají se jenom soubory šablon. Jakmile se šablony plně rozšíří, spustí se konečný kanál, jako by byl definován zcela ve zdrojovém úložišti. To znamená, že nemůžete použít skripty z úložiště šablony ve vašem kanálu.

Pokud chcete použít konkrétní, pevnou verzi šablony, nezapomeňte připnout na ref. Jedná se refs o 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ána žádná ref hodnota, kanál se ve výchozím nastavení použije refs/heads/main.

Můžete také připnout ke konkrétnímu potvrzení v Gitu s hodnotou SHA pro prostředek úložiště. Hodnota SHA je 40znaková hodnota hash kontrolního součtu, která jednoznačně identifikuje potvrzení.

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

Můžete také použít @self odkaz 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 rozšiřujícím úložišti kanálu. 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: []

Často kladené dotazy

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

Občas může být užitečné nastavit parametry na hodnoty založené na proměnných. Parametry se zvětšují v rané fázi zpracování spuštění kanálu, 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