Referenční informace k použití šablony
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.yml
se 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.yml
souboru .
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.yml
fileC.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ý resources
jste 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.SourceBranch
Build.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