템플릿 사용 참조
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
템플릿을 사용하면 YAML 파이프라인에서 재사용 가능한 콘텐츠, 논리 및 매개 변수를 정의할 수 있습니다. 템플릿을 효과적으로 사용하려면 단계, 단계 및 작업과 같은 Azure Pipelines 주요 개념을 기본적으로 이해해야 합니다.
템플릿을 사용하면 개발 속도를 높일 수 있습니다. 예를 들어 템플릿에 일련의 동일한 작업을 포함한 다음 YAML 파이프라인의 여러 단계에 템플릿을 여러 번 포함할 수 있습니다.
템플릿은 파이프라인을 보호하는 데도 도움이 될 수 있습니다. 템플릿이 파이프라인에서 허용되는 항목을 제어하는 경우 템플릿은 다른 파일이 따라야 하는 논리를 정의합니다. 예를 들어 실행할 수 있는 작업을 제한할 수 있습니다. 이 시나리오에서는 템플릿을 사용하여 누군가가 조직의 보안 정책을 위반하는 작업을 성공적으로 실행하지 못하도록 할 수 있습니다.
템플릿에는 포함 및 확장의 두 가지 유형이 있습니다.
- 템플릿을 포함하면 템플릿을 사용하여 재사용 가능한 콘텐츠를 삽입할 수 있습니다. 템플릿을 사용하여 콘텐츠를 포함하는 경우 많은 프로그래밍 언어의 include 지시문처럼 작동합니다. 한 파일의 콘텐츠가 다른 파일에 삽입됩니다.
- 파이프라인에서 허용되는 템플릿 컨트롤을 확장합니다. 확장 템플릿이 파이프라인에서 허용되는 항목을 제어하는 경우 템플릿은 다른 파일이 따라야 하는 논리를 정의합니다.
템플릿을 최대한 활용하려면 템플릿 식 및 템플릿 매개 변수도 사용해야 합니다.
적용된 제한
템플릿과 템플릿 식은 파이프라인의 크기와 복잡성을 폭발적으로 증가시킬 수 있습니다. 가출 증가를 방지하기 위해 Azure Pipelines는 다음과 같은 제한을 적용합니다.
- 100개 이하의 개별 YAML 파일을 포함할 수 있습니다(직접 또는 간접적으로).
- 20개 이하의 템플릿 중첩 수준(다른 템플릿을 포함한 템플릿)
- YAML을 구문 분석하는 동안 10MB 이하의 메모리가 소비되지 않습니다(실제로 사용되는 특정 기능에 따라 일반적으로 600KB ~ 2MB의 디스크 YAML 사이).
템플릿을 사용하여 논리를 한 번 정의한 다음 여러 번 다시 사용합니다. 템플릿은 여러 YAML 파일의 내용을 단일 파이프라인으로 결합합니다. 부모 파이프라인에서 템플릿에 매개 변수를 전달할 수 있습니다.
템플릿에서 확장
보안을 강화하기 위해 파이프라인이 특정 템플릿에서 확장되도록 적용할 수 있습니다. 이 파일 start.yml
은 매개 변수 buildSteps
를 정의한 다음, 파이프라인 azure-pipelines.yml
에서 사용됩니다.
buildStep
에서 start.yml
스크립트 단계와 함께 전달되면 거부되고 파이프라인 빌드가 실패합니다.
템플릿에서 확장할 때 필요한 템플릿 승인을 추가하여 보안을 강화할 수 있습니다.
# 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"
리소스를 사용하여 템플릿에서 확장
리소스가 포함된 Azure 파이프라인의 템플릿에서 확장하는 데 사용할 extends
수도 있습니다.
# 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"
템플릿 삽입
하나의 YAML에서 콘텐츠를 복사하고 다른 YAML에서 다시 사용할 수 있습니다. 한 YAML에서 다른 YAML로 콘텐츠를 복사하면 동일한 논리를 여러 위치에 수동으로 포함할 필요가 없도록 할 수 있습니다. include-npm-steps.yml
파일 템플릿에는 다시 사용하는 단계가 포함되어 있습니다azure-pipelines.yml
.
참고 항목
템플릿 파일은 파이프라인 실행이 시작될 때 파일 시스템에 있어야 합니다. 아티팩트에서 템플릿을 참조할 수 없습니다.
# 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
단계 재사용
템플릿을 삽입하여 여러 작업에서 하나 이상의 단계를 다시 사용할 수 있습니다. 템플릿의 단계 외에도 각 작업은 더 많은 단계를 정의할 수 있습니다.
# 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.
작업 재사용
단계와 마찬가지로 작업은 템플릿과 함께 다시 사용할 수 있습니다.
# 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
여러 작업으로 작업할 때 충돌을 방지하기 위해 템플릿 파일에서 작업의 이름을 제거해야 합니다.
# 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
스테이지 재사용
스테이지는 템플릿과 함께 다시 사용할 수도 있습니다.
# 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
매개 변수가 있는 작업, 단계 및 단계 템플릿
다음 템플릿에서:
templates/npm-with-params.yml
는 두 매개 변수name
를 정의하고vmImage
, 작업 이름에 대한 이름 매개 변수와 VM 이미지의 vmImage 매개 변수를 사용하여 작업을 만듭니다.- 파이프라인(
azure-pipelines.yml
)은 각각 운영 체제 및 VM 이미지 이름을 참조하는 서로 다른 매개 변수 값을 사용하여 템플릿을 세 번 참조합니다. - 빌드된 파이프라인은 다른 VM 이미지에서 실행되며 지정된 OS에 따라 이름이 지정됩니다. 각 작업은 npm 설치 및 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
파이프라인에서 템플릿을 사용하는 경우 템플릿 매개 변수에 대한 값을 지정합니다.
# 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'
여러 매개 변수가 있는 스테이징 템플릿
다음 템플릿에서:
- 템플릿은
stage-template.yml
네 개의stageName
매개 변수인 ,jobName
,vmImage
및scriptPath
모든 형식 문자열을 정의합니다. 템플릿은 매개 변수를 사용하여stageName
스테이지 이름을 설정하고, 작업을jobName
정의하며, 스크립트를 실행하는 단계를 포함합니다. - 파이프라인
azure-pipeline.yml
은 매개 변수를 사용하여 단계 및 작업을 동적으로 정의하고 스크립트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'
단계 및 매개 변수가 있는 템플릿
단계 또는 스테이지 템플릿에서 매개 변수를 사용할 수도 있습니다.
다음 템플릿에서:
- 템플릿(
templates/steps-with-params.yml
)은 기본값이 false인 매개runExtendedTests
변수를 정의합니다. - 파이프라인(
azure-pipelines.yml
)이 실행npm test
되고npm test --extended
매개 변수가runExtendedTests
true이기 때문입니다.
# 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
파이프라인에서 템플릿을 사용하는 경우 템플릿 매개 변수에 대한 값을 지정합니다.
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
참고 항목
지정된 형식이 없는 스칼라 매개 변수는 문자열로 처리됩니다.
예를 들어 eq(true, parameters['myparam'])
매개 변수가 단어false
인 경우에도 myparam
명시적으로 만들어boolean
지지 않은 경우 myparam
반환true
됩니다.
비어있지 않은 문자열은 부울 컨텍스트에서 캐스팅 true
됩니다.
문자열을 명시적으로 비교하기 위해 해당 식을 다시 작성할 수 있습니다. eq(parameters['myparam'], 'true')
매개 변수는 스칼라 문자열로 제한되지 않습니다.
데이터 형식 목록을 참조하세요.
예를 들어 다음 형식을 사용하세요.object
# 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 }}
변수 재사용
변수는 한 YAML에서 정의하고 다른 템플릿에 포함할 수 있습니다. 이 기능은 모든 변수를 한 파일에 저장하려는 경우에 유용할 수 있습니다. 템플릿을 사용하여 파이프라인에 변수를 포함하는 경우 포함된 템플릿은 변수를 정의하는 데만 사용할 수 있습니다. 템플릿에서 확장할 때 단계 및 더 복잡한 논리를 사용할 수 있습니다. 형식을 제한하려는 경우 변수 대신 매개 변수를 사용합니다.
이 예제에서는 변수 favoriteVeggie
가 .에 포함됩니다 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 }}.
매개 변수가 있는 변수 템플릿
템플릿을 사용하여 변수를 변수에 전달할 수 있습니다. 이 예제에서는 매개 변수를 DIRECTORY
변수에 전달합니다 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}'
파이프라인에서 템플릿을 사용하는 경우 템플릿 매개 변수에 대한 값을 지정합니다.
# 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
템플릿에서 확장하고 변수와 함께 포함 템플릿 사용
한 가지 일반적인 시나리오는 개발, 테스트 및 프로덕션을 위한 단계가 있는 파이프라인을 만드는 것입니다. 이 파이프라인은 변수에 템플릿을 사용하고 스테이지 또는 작업에 확장 템플릿을 모두 사용합니다.
다음 예제 variables-template.yml
에서는 다음에 사용되는 azure-pipeline.yml
가상 머신 변수 집합을 정의합니다.
# variables-template.yml
variables:
- name: devVmImage
value: 'ubuntu-latest'
- name: testVmImage
value: 'ubuntu-latest'
- name: prodVmImage
value: 'ubuntu-latest'
다음 파일 stage-template.yml
은 세 개의 매개 변수(name
, vmImage
, steps
) 및 이름이 지정된 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 }}
다음 파이프라인 azure-pipelines.yml
은 변수를 가져온 variables-template.yml
다음 각 단계에 템플릿을 stage-template.yml
사용합니다. 각 스테이지(개발, 테스트, Prod)는 동일한 템플릿으로 정의되지만 매개 변수가 다르면 여러 단계에서 일관성을 유지하면서 사용자 지정을 허용합니다. Prod 단계에는 인증에 사용할 수 있는 항목의 예로 환경 변수가 포함됩니다.
# 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)
참조 템플릿 경로
템플릿 경로는 리포지토리 내의 절대 경로이거나 포함을 수행하는 파일을 기준으로 할 수 있습니다.
절대 경로를 사용하려면 템플릿 경로가 .로 /
시작해야 합니다. 다른 모든 경로는 상대 경로로 간주됩니다.
다음은 중첩 계층의 예입니다.
|
+-- fileA.yml
|
+-- dir1/
|
+-- fileB.yml
|
+-- dir2/
|
+-- fileC.yml
그런 다음, fileA.yml
참조 fileB.yml
하고 fileC.yml
이와 같이 할 수 있습니다.
steps:
- template: dir1/fileB.yml
- template: dir1/dir2/fileC.yml
시작점인 경우 fileC.yml
이를 포함하고 fileA.yml
fileB.yml
좋아할 수 있습니다.
steps:
- template: ../../fileA.yml
- template: ../fileB.yml
시작 지점인 경우 fileB.yml
이를 포함하고 fileA.yml
fileC.yml
좋아할 수 있습니다.
steps:
- template: ../fileA.yml
- template: dir2/fileC.yml
fileB.yml
또는 이와 같은 절대 경로를 참조 fileA.yml
하고 fileC.yml
사용할 수 있습니다.
steps:
- template: /fileA.yml
- template: /dir1/dir2/fileC.yml
다른 리포지토리 사용
템플릿을 다른 리포지토리에 유지할 수 있습니다. 예를 들어 모든 앱 파이프라인을 사용할 핵심 파이프라인이 있다고 가정합니다. 템플릿을 핵심 리포지토리에 배치한 다음 각 앱 리포지토리에서 참조할 수 있습니다.
# 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
이제 여러 파이프라인에서 이 템플릿을 다시 사용할 수 있습니다.
사양을 resources
사용하여 코어 리포지토리의 위치를 제공합니다.
핵심 리포지토리 @
를 참조할 때 사용한 이름 및 이름을 입력합니다 resources
.
# 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'
name
의 경우 type: github
위 <identity>/<repo>
예제와 같습니다.
(Azure Repos)의 경우 type: git
는 .입니다<project>/<repo>
. name
해당 프로젝트가 별도의 Azure DevOps 조직에 있는 경우 프로젝트에 대한 액세스 권한이 있는 형식 Azure Repos/Team Foundation Server
의 서비스 연결을 구성하고 YAML에 포함해야 합니다.
resources:
repositories:
- repository: templates
name: Contoso/BuildTemplates
endpoint: myServiceConnection # Azure DevOps service connection
jobs:
- template: common.yml@templates
리포지토리는 파이프라인이 시작될 때 한 번만 확인됩니다. 그런 다음 파이프라인 기간 동안 동일한 리소스가 사용됩니다. 템플릿 파일만 사용됩니다. 템플릿이 완전히 확장되면 최종 파이프라인은 원본 리포지토리에 완전히 정의된 것처럼 실행됩니다. 즉, 파이프라인의 템플릿 리포지토리에서 스크립트를 사용할 수 없습니다.
특정 고정 버전의 템플릿을 사용하려면 에 고정해야 합니다 ref
.
분기 refs
(refs/heads/<name>
) 또는 태그(refs/tags/<name>
)입니다.
특정 커밋을 고정하려면 먼저 해당 커밋을 가리키는 태그를 만든 다음 해당 태그에 고정합니다.
참고 항목
지정되지 ref
않은 경우 파이프라인은 기본적으로 .를 사용 refs/heads/main
하게 됩니다.
리포지토리 리소스에 대한 SHA 값을 사용하여 Git의 특정 커밋에 고정할 수도 있습니다. SHA 값은 커밋을 고유하게 식별하는 40자 체크섬 해시입니다.
resources:
repositories:
- repository: templates
type: git
name: Contoso/BuildTemplates
ref: 1234567890abcdef1234567890abcdef12345678
원래 파이프라인이 발견된 리포지토리를 참조하는 데 사용할 @self
수도 있습니다.
확장 파이프라인 리포지토리의 콘텐츠를 다시 참조하려는 경우 템플릿에서 사용하기 extends
에 편리합니다.
예시:
# 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: []
FAQ
템플릿 내에서 어떻게 변수를 사용할 수 있나요?
매개 변수를 변수에 따라 값으로 설정하는 것이 유용한 경우가 있습니다. 매개 변수는 파이프라인 실행을 처리하는 초기에 확장되므로 모든 변수를 사용할 수 있는 것은 아닙니다. 템플릿에서 사용할 수 있는 미리 정의된 변수를 보려면 미리 정의된 변수 사용을 참조하세요.
이 예제에서는 미리 정의된 변수 Build.SourceBranch
이며 Build.Reason
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