テンプレートの種類 & の使用法

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

テンプレートを使用すると、再利用可能なコンテンツ、ロジック、およびパラメーターを定義できます。 テンプレートは 2 つの方法で機能します。 再利用可能なコンテンツをテンプレートで挿入することも、テンプレートを使用してパイプラインで許可される内容を制御することもできます。 2 つ目の方法は、 テンプレートを使用してセキュリティで保護されたパイプラインを構築する場合に便利です。

テンプレートを使用してコンテンツを含める場合は、多くのプログラミング言語で include ディレクティブのように機能します。 あるファイルのコンテンツが別のファイルに挿入されます。 テンプレートがパイプラインで許可される内容を制御する場合、テンプレートは別のファイルが従う必要があるロジックを定義します。

テンプレートを使用してロジックを 1 回定義し、それを複数回再利用します。 テンプレートは、複数の YAML ファイルの内容を 1 つのパイプラインにまとめます。 親パイプラインからテンプレートにパラメーターを渡すことができます。

パラメーター

テンプレートでパラメーターとそのデータ型を指定し、それらのパラメーターをパイプラインに渡すことができます。 テンプレートの外部でパラメーターを使用することもできます。 パラメーターの既定値にはリテラルのみを使用できます。

パラメーターを渡す

パラメーターには、名前とデータ型が含まれている必要があります。 では azure-pipelines.yml、 パラメーター yesNo がブール値に設定されている場合、ビルドは成功します。 が などのapples文字列に設定されている場合yesNo、ビルドは失敗します。

# File: simple-param.yml
parameters:
- name: yesNo # name of the parameter; required
  type: boolean # data type of the parameter; required
  default: false

steps:
- script: echo ${{ parameters.yesNo }}
# File: azure-pipelines.yml
trigger:
- main

extends:
  template: simple-param.yml
  parameters:
      yesNo: false # set to a non-boolean value to have the build fail

実行時にテンプレートを選択するためのパラメーター

条件に応じて、パイプライン YAML から異なるテンプレートを呼び出すことができます。 この例では、 パラメーターexperimentalTemplateexperimental.yml true の場合、YAML が実行されます。

#azure-pipeline.yml
parameters:
- name: experimentalTemplate
  displayName: 'Use experimental build process?'
  type: boolean
  default: false

steps:
- ${{ if eq(parameters.experimentalTemplate, true) }}:
  - template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:
  - template: stable.yml

パラメーター データ型

データ型 Notes
string string
number は に values:制限される場合があります。それ以外の場合は、任意の数値に似た文字列が受け入れられます
boolean true または false
object 任意の YAML 構造体
step 1 つのステップ
stepList 一連の 手順
job 1 つのジョブ
jobList ジョブのシーケンス
deployment 1 つのデプロイ ジョブ
deploymentList デプロイ ジョブのシーケンス
stage 1 つのステージ
stageList ステージのシーケンス

step、stepList、job、jobList、deployment、deploymentList、stage、stageList のデータ型はすべて、標準の YAML スキーマ形式を使用します。 この例には、string、number、boolean、object、step、stepList が含まれています。

parameters:
- name: myString
  type: string
  default: a string
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true
- name: myObject
  type: object
  default:
    foo: FOO
    bar: BAR
    things:
    - one
    - two
    - three
    nested:
      one: apple
      two: pear
      count: 3
- name: myStep
  type: step
  default:
    script: echo my step
- name: mySteplist
  type: stepList
  default:
    - script: echo step one
    - script: echo step two

trigger: none

jobs: 
- job: stepList
  steps: ${{ parameters.mySteplist }}
- job: myStep
  steps:
    - ${{ parameters.myStep }}

オブジェクトを反復処理し、オブジェクト内の各文字列を出力できます。

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

テンプレートから拡張する

セキュリティを強化するために、パイプラインが特定のテンプレートから拡張されることを強制できます。 ファイル start.yml によって パラメーター buildStepsが定義され、パイプライン azure-pipelines.ymlで使用されます。 では start.ymlbuildStep がスクリプト ステップで渡されると、拒否され、パイプラインのビルドは失敗します。 テンプレートから拡張する場合は、 必要なテンプレート承認を追加することでセキュリティを強化できます。

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

リソースを使用してテンプレートから拡張する

を使用 extends して、リソースを含む Azure パイプラインのテンプレートから拡張することもできます。

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

templateContext を使用してテンプレートにプロパティを渡す

を使用 templateContext して、テンプレートのパラメーターとして使用されるステージ、ステップ、ジョブに追加のプロパティを渡すことができます。 具体的には、または stageList パラメーターのデータ型内で deploymentListjobListを指定templateContextできます。

を使用 templateContext すると、各ジョブを処理するときに環境を簡単に設定できます。 ジョブとその環境プロパティ オブジェクトをバンドルすることで、 templateContext YAML をより保守しやすく理解しやすくなります。

この例では、 の testing-template.yml パラメーターtestSetのデータ型jobListは です。 テンプレートtesting-template.yml、各キーワードを使用して新しい変数testJobを作成します。 その後、テンプレートは を testJob.templateContext.expectedHTTPResponseCode参照します。これは に azure-pipeline.yml 設定され、テンプレートに渡されます。

応答コードが 200 の場合、テンプレートは REST 要求を行います。 応答コードが 500 の場合、テンプレートはデバッグ用のすべての環境変数を出力します。

templateContext プロパティを含めることができます。

#testing-template.yml

parameters: 
- name: testSet
  type: jobList

jobs:
- ${{ each testJob in parameters.testSet }}:
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}:
    - job:
      steps: 
      - powershell: 'Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ | Format-Table -Property Title, pubDate'
      - ${{ testJob.steps }}    
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}:
    - job:
      steps:
      - powershell: 'Get-ChildItem -Path Env:\'
      - ${{ testJob.steps }}
#azure-pipeline.yml

trigger: none

pool:
  vmImage: ubuntu-latest

extends:
  template: testing-template.yml
  parameters:
    testSet:
    - job: positive_test
      templateContext:
        expectedHTTPResponseCode: 200
      steps:
      - script: echo "Run positive test" 
    - job: negative_test
      templateContext:
        expectedHTTPResponseCode: 500
      steps:
      - script: echo "Run negative test" 

テンプレートを挿入する

1 つの 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

ステップの再利用

テンプレートを挿入して、複数のジョブで 1 つ以上のステップを再利用できます。 各ジョブでは、テンプレートの手順に加えて、より多くのステップを定義できます。

# 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: templates/stages2.yml

パラメーターを含むジョブ、ステージ、ステップのテンプレート

# 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'

ステップ テンプレートまたはステージ テンプレートでパラメーターを使用することもできます。 たとえば、パラメーターを含むステップは次のようになります。

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

変数の再利用

変数は、1 つの YAML で定義し、別のテンプレートに含めることができます。 これは、すべての変数を 1 つのファイルに格納する場合に便利です。 テンプレートを使用してパイプラインに変数を含める場合、含まれるテンプレートは変数の定義にのみ使用できます。 テンプレートから拡張する場合は、ステップとより複雑なロジックを使用できます。 型を制限する場合は、変数の代わりに パラメーター を使用します。

この例では、 変数 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 }}.

パラメーターを持つ変数テンプレート

テンプレートを使用して変数にパラメーターを渡すことができます。 この例では、 パラメーターを変数にDIRECTORYRELEASE_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

参照テンプレート のパス

テンプレート パスは、 を含めるファイルに対する相対パスである必要があります。 入れ子になった階層の例を次に示します。

|
+-- 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は、次のように をfileB.ymlfileA.ymlめることができます。

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

が出発点の場合fileB.ymlは、次のように をfileC.ymlfileA.ymlめることができます。

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

他のリポジトリを使用する

テンプレートは他のリポジトリに保持できます。 たとえば、すべてのアプリ パイプラインで使用するコア パイプラインがあるとします。 テンプレートをコア リポジトリに配置し、各アプリ リポジトリから参照できます。

# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
- name: 'vmImage'
  default: 'ubuntu 16.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

リポジトリは、パイプラインの起動時に 1 回だけ解決されます。 その後、パイプラインの期間中は同じリソースが使用されます。 テンプレート ファイルのみが使用されます。 テンプレートが完全に展開されると、最終的なパイプラインは、ソース リポジトリで完全に定義されているかのように実行されます。 つまり、パイプラインでテンプレート リポジトリのスクリプトを使用することはできません。

特定の固定バージョンのテンプレートを使用する場合は、 に refピン留めしてください。 はrefsブランチ () またはタグ (refs/heads/<name>refs/tags/<name>) です。 特定のコミットをピン留めする場合は、まずそのコミットを指すタグを作成してから、そのタグにピン留めします。

注意

が指定されていない ref 場合、パイプラインは既定で を使用 refs/heads/mainします。

を使用 @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: []

テンプレート式

テンプレート 式を 使用して、パイプラインの初期化中に値を動的に解決する方法を指定します。 次の構文内でテンプレート式をラップします: ${{ }}

テンプレート式では、テンプレート パラメーターと変数を展開できます。 パラメーターを使用して、テンプレートの展開方法に影響を与えることができます。 オブジェクトは parameters 、式の variables オブジェクト と同様に機能します。 テンプレート式では、定義済みの変数のみを使用できます。

注意

式は、、、、および containers (内resources) でのみ展開されますstagesstepsjobs たとえば、 内 trigger の式や などの repositoriesリソースを使用することはできません。 さらに、Azure DevOps 2020 RTW では、 内 containersでテンプレート式を使用することはできません。

たとえば、テンプレートを定義します。

# File: steps/msbuild.yml

parameters:
- name: 'solution'
  default: '**/*.sln'
  type: string

steps:
- task: msbuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}  # property dereference syntax

次に、テンプレートを参照し、省略可能な solution パラメーターを渡します。

# File: azure-pipelines.yml

steps:
- template: steps/msbuild.yml
  parameters:
    solution: my.sln

Context

テンプレート式内では、渡されたパラメーターの値を parameters 含むコンテキストにアクセスできます。 さらに、YAML ファイルで指定されたすべての変数に加えて、(そのトピックの各変数に記載されている) 定義済みの変数の多くを含むコンテキストにアクセスvariablesできます。 重要なのは、パイプラインに格納されているランタイム変数や、実行の開始時に指定されたランタイム変数が含まれていない点です。 テンプレートの展開は 実行の非常に早い段階で行われるため、これらの変数は使用できません。

必須のパラメーター

テンプレートの先頭に検証ステップを追加して、必要なパラメーターを確認できます。

Bash を使用して パラメーターを solution チェックする例を次に示します (これにより、任意のプラットフォームで動作できます)。

# File: steps/msbuild.yml

parameters:
- name: 'solution'
  default: ''
  type: string

steps:
- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi
  env:
    SOLUTION: ${{ parameters.solution }}
  displayName: Check for required parameters
- task: msbuild@1
  inputs:
    solution: ${{ parameters.solution }}
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}

必要なパラメーターがない場合にテンプレートが失敗することを示すには、次のようにします。

# File: azure-pipelines.yml

# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml

テンプレート式関数

テンプレートで 一般的な関数 を使用できます。 いくつかのテンプレート式関数を使用することもできます。

format

  • 単純な文字列トークンの置換
  • 最小パラメーター: 2。 最大パラメーター: N
  • 例: ${{ format('{0} Build', parameters.os) }}'Windows Build'

coalesce

  • 最初の空でない null 以外の文字列引数に評価されます
  • 最小パラメーター: 2。 最大パラメーター: N
  • 例:
parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

steps:
- script: echo ${{ coalesce(parameters.foo, parameters.bar, 'Nothing to see') }}

挿入

テンプレート式を使用して、YAML パイプラインの構造を変更できます。 たとえば、 をシーケンスに挿入するには、次のようにします。

# File: jobs/build.yml

parameters:
- name: 'preBuild'
  type: stepList
  default: []
- name: 'preTest'
  type: stepList
  default: []
- name: 'preSign'
  type: stepList
  default: []

jobs:
- job: Build
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: cred-scan
  - ${{ parameters.preBuild }}
  - task: msbuild@1
  - ${{ parameters.preTest }}
  - task: vstest@2
  - ${{ parameters.preSign }}
  - script: sign
# File: .vsts.ci.yml

jobs:
- template: jobs/build.yml
  parameters:
    preBuild:
    - script: echo hello from pre-build
    preTest:
    - script: echo hello from pre-test

配列が配列に挿入されると、入れ子になった配列がフラット化されます。

マッピングに挿入するには、特殊な プロパティ を使用します ${{ insert }}

# Default values
parameters:
- name: 'additionalVariables'
  type: object
  default: {}

jobs:
- job: build
  variables:
    configuration: debug
    arch: x86
    ${{ insert }}: ${{ parameters.additionalVariables }}
  steps:
  - task: msbuild@1
  - task: vstest@2
jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

条件付き挿入

テンプレート内のシーケンスまたはマッピングに条件付きで挿入する場合は、挿入と式の評価を使用します。 テンプレート構文を使用 if する限り 、テンプレートの外部 でステートメントを使用することもできます。

たとえば、テンプレート内のシーケンスにを挿入するには、次のようにします。

# File: steps/build.yml

parameters:
- name: 'toolset'
  default: msbuild
  type: string
  values:
  - msbuild
  - dotnet

steps:
# msbuild
- ${{ if eq(parameters.toolset, 'msbuild') }}:
  - task: msbuild@1
  - task: vstest@2

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: dotnet@1
    inputs:
      command: build
  - task: dotnet@1
    inputs:
      command: test
# File: azure-pipelines.yml

steps:
- template: steps/build.yml
  parameters:
    toolset: dotnet

たとえば、テンプレート内のマッピングにを挿入するには、次のようにします。

# File: steps/build.yml

parameters:
- name: 'debug'
  type: boolean
  default: false

steps:
- script: tool
  env:
    ${{ if eq(parameters.debug, true) }}:
      TOOL_DEBUG: true
      TOOL_DEBUG_DIR: _dbg
steps:
- template: steps/build.yml
  parameters:
    debug: true

変数に条件付き挿入を使用することもできます。 この例では、常に を出力し、 startthis is a test 変数が foo と等しい場合にのみ出力します test

variables:
  - name: foo
    value: test

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.foo, 'test') }}:
  - script: echo "this is a test" # runs when foo=test

反復挿入

ディレクティブを each 使用すると、YAML シーケンス (配列) またはマッピング (キーと値のペア) に基づいて反復挿入できます。

たとえば、各ジョブのステップを他の事前ステップと事後ステップと共にラップできます。

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()
# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This will get sandwiched between SetupMyBuildTools and PublishMyTelemetry.
    - job: B
      steps:
      - script: echo So will this!

また、反復処理している内容のプロパティを操作することもできます。 たとえば、依存関係をさらに追加するには、次のようにします。

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- job: SomeSpecialTool                # Run your special tool in its own job first
  steps:
  - task: RunSpecialTool@1
- ${{ each job in parameters.jobs }}: # Then do each job
  - ${{ each pair in job }}:          # Insert all properties other than "dependsOn"
      ${{ if ne(pair.key, 'dependsOn') }}:
        ${{ pair.key }}: ${{ pair.value }}
    dependsOn:                        # Inject dependency
    - SomeSpecialTool
    - ${{ if job.dependsOn }}:
      - ${{ job.dependsOn }}
# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This job depends on SomeSpecialTool, even though it's not explicitly shown here.
    - job: B
      dependsOn:
      - A
      steps:
      - script: echo This job depends on both Job A and on SomeSpecialTool.

値をエスケープする

リテラルに を含む値をエスケープする必要がある場合は ${{、式文字列で値をラップします。 たとえば、${{ 'my${{value' }}${{ 'my${{value with a '' single quote too' }} のようにします。

適用される制限

テンプレートとテンプレート式により、パイプラインのサイズと複雑さが爆発的に増加する可能性があります。 暴走の増加を防ぐために、Azure Pipelines では次の制限が課されます。

  • 100 個以下の個別の YAML ファイルを含めることができます (直接または間接的に)
  • 20 レベル以下のテンプレートの入れ子 (他のテンプレートを含むテンプレート)
  • YAML の解析中に消費されるメモリは 10 MB 以下です (実際には、使用される特定の機能に応じて、通常は 600 KB から 2 MB のオンディスク YAML の間です)

テンプレート パラメーター

パラメーターはテンプレートに渡すことができます。 セクションでは parameters 、テンプレートで使用できるパラメーターとその既定値を定義します。 パイプラインが実行される直前にテンプレートが展開され、 で ${{ }} 囲まれた値が、外側のパイプラインから受け取るパラメーターに置き換えられます。 その結果、 定義済みの変数 のみをパラメーターで使用できます。

複数のパイプラインでパラメーターを使用するには、 変数グループを作成する方法に関するページを参照してください。

パラメーターを含むジョブ、ステージ、ステップのテンプレート

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

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

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-10.13'

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

ステップ テンプレートまたはステージ テンプレートでパラメーターを使用することもできます。 たとえば、パラメーターを含むステップは次のようになります。

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

parameters:
  runExtendedTests: 'false'  # defaults for any parameters that aren't specified

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(parameters['myparam'], true) は、パラメーターが という単語falseである場合でも、ほとんど常に myparam を返しますtrue。 空でない文字列は、ブール型のコンテキストで に true キャストされます。 そのを書き換えて、文字列を明示的に比較できます。 eq(parameters['myparam'], 'true')

パラメーターはスカラー文字列に限定されません。 パラメーターが展開される場所にマッピングが必要な限り、パラメーターはマッピングにすることができます。 同様に、シーケンスが必要な場合は、シーケンスを渡すことができます。 たとえば次のような点です。

# 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:
  pool: {}

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

他のリポジトリの使用

テンプレートは他のリポジトリに保持できます。 たとえば、すべてのアプリ パイプラインで使用するコア パイプラインがあるとします。 テンプレートをコア リポジトリに配置し、各アプリ リポジトリから参照できます。

# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
  vmImage: 'ubuntu 16.04'

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 プロジェクトは同じ組織に存在する必要があります。組織間参照はサポートされていません。

リポジトリは、パイプラインの起動時に 1 回だけ解決されます。 その後、パイプライン中に同じリソースが使用されます。 テンプレート ファイルのみが使用されます。 テンプレートが完全に展開されると、最終的なパイプラインはソース リポジトリで完全に定義されたかのように実行されます。 つまり、パイプラインでテンプレート リポジトリのスクリプトを使用することはできません。

特定の固定バージョンのテンプレートを使用する場合は、必ず ref にピン留めしてください。参照はブランチ () またはタグ (refs/heads/<name>refs/tags/<name>) です。 特定のコミットをピン留めする場合は、まずそのコミットを指すタグを作成してから、そのタグにピン留めします。

テンプレート 式を 使用して、パイプラインの初期化中に値を動的に解決する方法を指定します。 次の構文内でテンプレート式をラップします。 ${{ }}

テンプレート式では、テンプレート パラメーターと変数を展開できます。 パラメーターを使用して、テンプレートの展開方法に影響を与えることができます。 オブジェクトは parameters 、式内の variables オブジェクト と同様に動作します。

たとえば、テンプレートを定義します。

# File: steps/msbuild.yml

parameters:
  solution: '**/*.sln'

steps:
- task: msbuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}  # property dereference syntax

次に、テンプレートを参照し、省略可能な solution パラメーターを渡します。

# File: azure-pipelines.yml

steps:
- template: steps/msbuild.yml
  parameters:
    solution: my.sln

Context

テンプレート式内では、渡されたパラメーターの値を parameters 含むコンテキストにアクセスできます。 さらに、コンテキストに variables アクセスできます。このコンテキストには、YAML ファイルで指定されたすべての変数と システム変数が含まれます。 重要なのは、パイプラインに格納されたランタイム変数や、実行の開始時に指定されたランタイム変数が含まれていない点です。 テンプレートの展開は 実行の早い段階で行われるため、これらの変数は使用できません。

必須のパラメーター

テンプレートの先頭に検証手順を追加して、必要なパラメーターを確認できます。

Bash を使用して パラメーターを solution チェックする例を次に示します (これにより、任意のプラットフォームで動作できます)。

# File: steps/msbuild.yml

parameters:
  solution: ''

steps:
- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi
  env:
    SOLUTION: ${{ parameters.solution }}
  displayName: Check for required parameters
- task: msbuild@1
  inputs:
    solution: ${{ parameters.solution }}
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}

必要なパラメーターがない場合にテンプレートが失敗することを示すには:

# File: azure-pipelines.yml

# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml

テンプレート式関数

テンプレートで 一般的な関数 を使用できます。 いくつかのテンプレート式関数を使用することもできます。

format

  • 単純な文字列トークンの置換
  • 最小パラメーター: 2。 最大パラメーター: N
  • 例: ${{ format('{0} Build', parameters.os) }}'Windows Build'

coalesce

  • 空でない最初の null 以外の文字列引数に評価されます
  • 最小パラメーター: 2。 最大パラメーター: N
  • 例:
parameters:
  restoreProjects: ''
  buildProjects: ''

steps:
- script: echo ${{ coalesce(parameters.foo, parameters.bar, 'Nothing to see') }}

挿入

テンプレート式を使用して、YAML パイプラインの構造を変更できます。 たとえば、 をシーケンスに挿入するには、次のようにします。

# File: jobs/build.yml

parameters:
  preBuild: []
  preTest: []
  preSign: []

jobs:
- job: Build
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: cred-scan
  - ${{ parameters.preBuild }}
  - task: msbuild@1
  - ${{ parameters.preTest }}
  - task: vstest@2
  - ${{ parameters.preSign }}
  - script: sign
# File: .vsts.ci.yml

jobs:
- template: jobs/build.yml
  parameters:
    preBuild:
    - script: echo hello from pre-build
    preTest:
    - script: echo hello from pre-test

配列が配列に挿入されると、入れ子になった配列はフラット化されます。

マッピングに挿入するには、特別な プロパティ を使用します ${{ insert }}

# Default values
parameters:
  additionalVariables: {}

jobs:
- job: build
  variables:
    configuration: debug
    arch: x86
    ${{ insert }}: ${{ parameters.additionalVariables }}
  steps:
  - task: msbuild@1
  - task: vstest@2
jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

条件付き挿入

シーケンスまたはマッピングに条件付きで挿入する場合は、挿入と式の評価を使用します。

たとえば、 をシーケンスに挿入するには、次のようにします。

# File: steps/build.yml

parameters:
  toolset: msbuild

steps:
# msbuild
- ${{ if eq(parameters.toolset, 'msbuild') }}:
  - task: msbuild@1
  - task: vstest@2

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: dotnet@1
    inputs:
      command: build
  - task: dotnet@1
    inputs:
      command: test
# File: azure-pipelines.yml

steps:
- template: steps/build.yml
  parameters:
    toolset: dotnet

たとえば、マッピングに挿入するには、次のようにします。

# File: steps/build.yml

parameters:
  debug: false

steps:
- script: tool
  env:
    ${{ if eq(parameters.debug, 'true') }}:
      TOOL_DEBUG: true
      TOOL_DEBUG_DIR: _dbg
steps:
- template: steps/build.yml
  parameters:
    debug: true

反復挿入

ディレクティブを each 使用すると、YAML シーケンス (配列) またはマッピング (キーと値のペア) に基づいて反復挿入できます。

たとえば、各ジョブのステップを追加の事前ステップと事後ステップでラップできます。

# job.yml
parameters:
  jobs: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()
# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This will get sandwiched between SetupMyBuildTools and PublishMyTelemetry.
    - job: B
      steps:
      - script: echo So will this!

また、繰り返し処理しているもののプロパティを操作することもできます。 たとえば、依存関係をさらに追加するには、次のようにします。

# job.yml
parameters:
  jobs: []

jobs:
- job: SomeSpecialTool                # Run your special tool in its own job first
  steps:
  - task: RunSpecialTool@1
- ${{ each job in parameters.jobs }}: # Then do each job
  - ${{ each pair in job }}:          # Insert all properties other than "dependsOn"
      ${{ if ne(pair.key, 'dependsOn') }}:
        ${{ pair.key }}: ${{ pair.value }}
    dependsOn:                        # Inject dependency
    - SomeSpecialTool
    - ${{ if job.dependsOn }}:
      - ${{ job.dependsOn }}
# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This job depends on SomeSpecialTool, even though it's not explicitly shown here.
    - job: B
      dependsOn:
      - A
      steps:
      - script: echo This job depends on both Job A and on SomeSpecialTool.

エスケープ

リテラルに を含む値をエスケープする必要がある場合は ${{、式文字列で値をラップします。 たとえば、${{ 'my${{value' }}${{ 'my${{value with a '' single quote too' }} のようにします。

制限

テンプレートとテンプレート式により、パイプラインのサイズと複雑さが爆発的に増加する可能性があります。 暴走の増加を防ぐために、Azure Pipelines には次の制限があります。

  • 個別の YAML ファイルは 50 個以下 (直接的または間接的に) 含めることもできます。
  • YAML の解析中に消費されるメモリは 10 MB 以下です (実際には、使用される特定の機能に応じて、通常は 600 KB から 2 MB のオンディスク YAML の間です)
  • テンプレート式あたり 2,000 文字以内