YAML でリソースを定義する

[アーティクル]
06/16/2023

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

YAML のリソースとは、パイプライン、ビルド、リポジトリ、コンテナー、パッケージ、Webhook のソースです。また、リソースは、バージョン、成果物、関連付けられたコミット、作業項目など、パイプラインで使われるサービスの完全な追跡可能性も提供します。リソースを定義すると、パイプラインのどこででも使用できます。また、リソースのトリガーイベントにサブスクライブすることで、DevOps ワークフローを完全に自動化できます。

詳細については、「リソースについて」と「リソース YAML スキーマ定義」について」を参照してください。

スキーマ

resources:
  pipelines: [ pipeline ]  
  builds: [ build ]
  repositories: [ repository ]
  containers: [ container ]
  packages: [ package ]
  webhooks: [ webhook ]

変数

リソースでパイプラインがトリガーされるときに、次の変数が設定されます。

resources.triggeringAlias
resources.triggeringCategory

リソースがパイプライン実行をトリガーしない場合、これらの値は空です。これらの値が設定されるためには、変数 Build.Reason が ResourceTrigger である必要があります。

`pipelines` リソースを定義する

成果物を生成するパイプラインがある場合は、pipelines リソースを定義することでその成果物を使用できます。 pipelines は、Azure Pipelines 専用のリソースです。 CD ワークフロー用のパイプラインリソースにトリガーを設定することもできます。

リソース定義の pipeline は、後でパイプラインリソースを参照するために使用できる一意の値です。 source は、成果物を生成するパイプラインの名前です。パイプラインリソース変数を使うときや、成果物をダウンロードするときなど、パイプラインの他の部分からパイプラインリソースを参照するには、pipeline で定義されているラベルを使います。

パイプラインをダウンロードする別の方法については、パイプラインの成果物に関する記事をご覧ください。

[スキーマ]
例

resources:        # types: pipelines | builds | repositories | containers | packages
  pipelines:
  - pipeline: string  # identifier for the resource used in pipeline resource variables
    project: string # project for the source; optional for current project
    source: string  # name of the pipeline that produces an artifact
    version: string  # the pipeline run number to pick the artifact, defaults to latest pipeline successful across all stages; Used only for manual or scheduled triggers
    branch: string  # branch to pick the artifact, optional; defaults to all branches; Used only for manual or scheduled triggers
    tags: [ string ] # list of tags required on the pipeline to pickup default artifacts, optional; Used only for manual or scheduled triggers
    trigger:     # triggers aren't enabled by default unless you add trigger section to the resource
      branches:  # branch conditions to filter the events, optional; Defaults to all branches.
        include: [ string ]  # branches to consider the trigger events, optional; Defaults to all branches.
        exclude: [ string ]  # branches to discard the trigger events, optional; Defaults to none.
      tags: [ string ]  # list of tags to evaluate for trigger event, optional
      stages: [ string ] # list of stages to evaluate for trigger event, optional

同じプロジェクト内のパイプラインから成果物を使うには、次のスキーマを使います。

resources:
  pipelines:
  - pipeline: SmartHotel-resource # identifier for the resource (used in pipeline resource variables)
    source: SmartHotel-CI # name of the pipeline that produces an artifact

別のプロジェクトからパイプラインを使うには、プロジェクト名とソース名を含めます。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    branch: releases/M142   # This branch is used for resolving default version when the pipeline is triggered manually or scheduled. The branch input should not have wild cards

単純なトリガーを含むパイプラインリソース。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger: true

分岐条件を含むパイプラインリソーストリガー。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
      - releases/*
      - resources.triggeringAlias

トリガーのステージフィルター。

resources:
  pipelines:
  - pipeline: MyCIAlias  
    project: Fabrikam  
    source: Farbrikam-CI  
    trigger:    
      stages:            ### This stage filter is used when evaluating conditions for triggering your CD pipeline
      - PreProduction    ### stages are AND'ed. On successful completion of all the stages provided, your CD pipeline gets triggered. 
      - Production

既定のバージョン評価とトリガーのタグフィルター。

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    tags:               ### tags are used for resolving default version when the pipeline is triggered manually or scheduled
    - Production        ### Tags are AND'ed
    trigger:
      tags:             ### This filter is used for triggering the pipeline run
      - Production      ### Tags are AND'ed
      - Signed

これらの例は、継続的インテグレーション (CI) パイプラインで設定されるタグです。これらのタグは、git リポジトリのブランチで設定されるタグとは異なります。

重要

リソーストリガーを定義するとき、そのパイプラインリソースが現在のパイプラインと同じリポジトリ (self など) からのものである場合、トリガーはイベントが発生したのと同じブランチとコミットに従います。一方、パイプラインリソースが別のリポジトリのものである場合は、現在のパイプラインは self リポジトリの既定のブランチでトリガーされます。

成果物のバージョンの評価

リソースパイプラインの成果物のバージョンは、パイプラインのトリガー方法によって異なります。

手動トリガーまたはスケジュールされた実行によってパイプラインが実行される場合、成果物のバージョンは version、branch、tags プロパティの値によって定義されます。

指定されたプロパティ	成果物のバージョン
`version`	指定された実行番号を持つビルドからの成果物
`branch`	指定されたブランチで実行された最新のビルドからの成果物
`tags` リスト	指定されたタグをすべて持つ最新のビルドからの成果物
`branch` と `tags` リスト	指定されたブランチで実行され、"かつ"、指定されたタグをすべて持つ、最新のビルドからの成果物
なし	すべてのブランチで最新のビルドからの成果物

例を見てみましょう。パイプラインに次のリソース定義が含まれているとします。

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    branch: main      ### This branch input cannot have wild cards. It is used for evaluating default version when pipeline is triggered manually or scheduled.
    tags:               ### These tags are used for resolving default version when the pipeline is triggered manually or scheduled
    - Production        ### Tags are AND'ed
    - PreProduction

パイプラインの実行を手動でトリガーする場合、MyCIAlias パイプラインの成果物のバージョンは、main ブランチで実行され、Production タグと PrepProduction タグを持っている、最新のビルドのバージョンです。

いずれかのリソースパイプラインが完了したためにパイプラインがトリガーされたときは、成果物のバージョンはトリガー元のパイプラインのバージョンです。 version、branch、tags プロパティの値は無視されます。

指定されたトリガー	結果
`branches`	`include` ブランチでリソースパイプラインの実行が正常に完了するたびに、現在のパイプラインの新しい実行がトリガーされます
`tags`	指定された "すべての" タグでタグ付けされたリソースパイプラインの実行が正常に完了するたびに、現在のパイプラインの新しい実行がトリガーされます
`stages`	指定された `stages` をリソースパイプラインが正常に実行するたびに、現在のパイプラインの新しい実行がトリガーされます
`branches`、`tags`、`stages`	リソースパイプライン実行がブランチ、タグ、ステージの "すべての" 条件を満たすたびに、現在のパイプラインの新しい実行がトリガーされます
`trigger: true`	リソースパイプラインの実行が正常に完了するたびに、現在のパイプラインの新しい実行がトリガーされます
なし	リソースパイプラインの実行が正常に完了したときは、現在のパイプラインの新しい実行はトリガーされません

例を見てみましょう。パイプラインに次のリソース定義が含まれているとします。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
        include:
        - releases/*
        - main
        exclude:
        - topic/*
      tags: 
      - Verified
      - Signed
      stages:
      - Production
      - PreProduction

Verified と Signed の両方でタグ付けされた SmartHotel-CI パイプラインが、releases ブランチの 1 つまたは main ブランチで実行され、Production と PreProduction 両方のステージを完了するたびに、ユーザーのパイプラインが実行されます。

パイプラインの `download`

現在のパイプラインおよびすべての pipeline リソースからのすべての成果物は、自動的にダウンロードされて、各 deployment ジョブの開始時には使用できるようになります。この動作はオーバーライドできます。詳しくは、パイプライン成果物に関する記事をご覧ください。通常の "ジョブ" 成果物は自動的にはダウンロードされません。必要なときは、明示的に download を使います。

[スキーマ]
例

steps:
- download: [ current | pipeline resource identifier | none ] # disable automatic download if "none"
  artifact: string ## artifact name, optional; downloads all the available artifacts if not specified
  patterns: string # patterns representing files to include; optional

- job: deploy_windows_x86_agent
  steps:
  - download: SmartHotel   # pipeline resource identifier.
    artifact: WebTier1  # artifact to download, optional; defaults to all the artifacts from the resource.
    patterns: '**/*.zip'  # mini match pattern to download specific files, optional; defaults to all files.

または、いずれかの成果物がダウンロードされないようにするには:

- download: none

pipeline リソースからの成果物が、$(PIPELINE.WORKSPACE)/<pipeline-identifier>/<artifact-identifier> フォルダーにダウンロードされます。

パイプラインリソース変数

各実行では、パイプラインリソースのメタデータを、定義済み変数の形式ですべてのジョブから使用できます。 <Alias> は、ユーザーがパイプラインリソースに対して指定した識別子です。パイプラインリソース変数は、実行時にのみ使用できます。

[スキーマ]
例

resources.pipeline.<Alias>.projectID
resources.pipeline.<Alias>.pipelineName
resources.pipeline.<Alias>.pipelineID
resources.pipeline.<Alias>.runName
resources.pipeline.<Alias>.runID
resources.pipeline.<Alias>.runURI
resources.pipeline.<Alias>.sourceBranch
resources.pipeline.<Alias>.sourceCommit
resources.pipeline.<Alias>.sourceProvider
resources.pipeline.<Alias>.requestedFor
resources.pipeline.<Alias>.requestedForID

resources:
  pipelines:
  - pipeline: myresourcevars  # identifier for the pipeline resource
    source: mypipeline # source pipeline definition name
    trigger: true 

steps:
- script: |
    echo $(resources.pipeline.myresourcevars.pipelineID)
    echo $(resources.pipeline.myresourcevars.runName)
    echo $(resources.pipeline.myresourcevars.runID)
    echo $(resources.pipeline.myresourcevars.runURI)
    echo $(resources.pipeline.myresourcevars.sourceBranch)
    echo $(resources.pipeline.myresourcevars.sourceCommit)
    echo $(resources.pipeline.myresourcevars.sourceProvider)
    echo $(resources.pipeline.myresourcevars.requestedFor)
    echo $(resources.pipeline.myresourcevars.requestedForID)

詳しくは、「定義済み変数としてのパイプラインリソースメタデータ」をご覧ください。

`builds` リソースを定義する

成果物を生成する外部 CI ビルドシステムがある場合は、builds リソースを使って成果物を使用できます。 builds リソースは、Jenkins、TeamCity、CircleCI など、どのような外部 CI システムでもかまいません。

[スキーマ]
例

resources:        # types: pipelines | builds | repositories | containers | packages
  builds:
  - build: string   # identifier for the build resource
    type: string   # the type of your build service like Jenkins, circleCI etc.
    connection: string   # service connection for your build service.
    source: string   # source definition of the build
    version: string   # the build number to pick the artifact, defaults to Latest successful build
    trigger: boolean    # Triggers aren't enabled by default and should be explicitly set

builds は拡張可能なカテゴリです。ビルドサービスから成果物を使用する拡張機能を作成し、builds の一部として新しい種類のサービスを導入できます。 Jenkins は、builds でのリソースの一種です。

resources:
  builds:
  - build: Spaceworkz
    type: Jenkins
    connection: MyJenkinsServer 
    source: SpaceworkzProj   # name of the jenkins source project
    trigger: true

重要

トリガーは、Azure DevOps が Jenkins サーバーとの通信経路を持つホステッド Jenkins でのみサポートされます。

ビルドの `downloadBuild` タスク

downloadBuild タスクを使うことで、ジョブの一部として build リソースの成果物を使用できます。定義されている build リソースの種類に基づいて、このタスクは実行時にサービスの対応するダウンロードタスクに自動的に解決されます。

build リソースからの成果物が、$(PIPELINE.WORKSPACE)/<build-identifier>/ フォルダーにダウンロードされます。

重要

build リソース成果物は、ジョブとデプロイジョブには自動的にダウンロードされません。成果物を使うには、downloadBuild タスクを明示的に追加する必要があります。

[スキーマ]
例

- downloadBuild: string # identifier for the resource from which to download artifacts
  artifact: string # artifact to download; if left blank, downloads all artifacts associated with the resource provided
  patterns: string | [ string ] # a minimatch path or list of [minimatch paths](tasks/file-matching-patterns.md) to download; if blank, the entire artifact is downloaded

各デプロイまたはジョブのダウンロード動作をカスタマイズできます。

- job: deploy_windows_x86_agent
  steps:
  - downloadBuild: Spaceworkz   # build resource identifier.
    patterns: '**/*.zip'  # mini match pattern to download specific files, optional; defaults to all files.

`repositories` リソースを定義する

パイプラインに別のリポジトリのテンプレートがある場合、またはサービス接続を必要とするリポジトリで複数のリポジトリのチェックアウトを使う場合は、システムにそのリポジトリについて認識させる必要があります。 repository キーワードを使うと、外部リポジトリを指定できます。

[スキーマ]
例

resources:
    repositories:
    - repository: string # Required as first property. Alias for the repository.
      endpoint: string # ID of the service endpoint connecting to this repository.
      trigger: none | trigger | [ string ] # CI trigger for this repository, no CI trigger if skipped (only works for Azure Repos).
      name: string # repository name (format depends on 'type'; does not accept variables).
      ref: string # ref name to checkout; defaults to 'refs/heads/main'. The branch checked out by default whenever the resource trigger fires.
      type: string # Type of repository: git, github, githubenterprise, and bitbucket.


resources:
  repositories:
  - repository: common
    type: github
    name: Contoso/CommonTools
    endpoint: MyContosoServiceConnection

型

パイプラインでは、リポジトリの種類の値として git、github、githubenterprise、bitbucket がサポートされています。種類 git は、Azure Repos Git リポジトリのことです。

指定された種類	結果	例
`type: git`	`name` の値は、同じプロジェクト内の別のリポジトリを参照します。	`name: otherRepo` 同じ組織内の別のプロジェクトのリポジトリを参照するには、名前の前にそのプロジェクトの名前を付けます。たとえば `name: OtherProject/otherRepo` です。
`type: github`	`name` の値は、GitHub リポジトリの完全な名前であり、ユーザーまたは組織が含まれます。	`name: Microsoft/vscode`
`type: githubenterprise`	`name` の値は、GitHub Enterprise リポジトリの完全な名前であり、ユーザーまたは組織が含まれます。	`name: Microsoft/vscode`
`type: bitbucket`	`name` の値は、Bitbucket Cloud リポジトリの完全な名前であり、ユーザーまたは組織が含まれます。	`name: MyBitbucket/vscode`

GitHub Enterprise リポジトリでは、承認のために GitHub Enterprise サービス接続が必要です。

Bitbucket Cloud リポジトリでは、承認のために Bitbucket Cloud サービス接続が必要です。

変数

各実行では、パイプラインリソースのメタデータを、定義済み変数の形式ですべてのジョブから使用できます。 <Alias> は、ユーザーがリポジトリリソースに対して指定した識別子です。

[スキーマ]
例

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url

次の例では、common のエイリアスを持つリポジトリリソースがあり、リポジトリリソース変数には resources.repositories.common.* を使用してアクセスします。

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url
resources.repositories.<Alias>.version

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]
  version: $[ resources.repositories.common.version ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"
    echo "version = $(version)"

`checkout` を使用してリポジトリを使用する

repository リソースの一部として定義されているリポジトリを使うには、checkout キーワードを使います。

スキーマ

steps:
- checkout: string # Required as first property. Configures checkout for the specified repository.
  clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  fetchDepth: string # Depth of Git graph to fetch.
  fetchTags: string # Set to 'true' to sync tags when fetching the repo, or 'false' to not sync tags. See remarks for the default behavior.
  lfs: string # Set to 'true' to download Git-LFS files. Default is not to download them.
  persistCredentials: string # Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
  submodules: string # Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
  path: string # Where to put the repository. The default is $(Build.SourcesDirectory).
  condition: string # Evaluate this condition expression to determine whether to run this task.
  continueOnError: boolean # Continue running even on failure?
  displayName: string # Human-readable name for the task.
  target: string | target # Environment in which to run this task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
  retryCountOnTaskFailure: string # Number of retries if the task fails.

repository リソースからのリポジトリは、ジョブ内では自動的に同期されません。 checkout を使って、ジョブの一部としてリポジトリをフェッチします。

詳しくは、「パイプラインで複数のリポジトリをチェックアウトする」をご覧ください。

`containers` リソースを定義する

継続的インテグレーションと継続的デリバリー (CI/CD) パイプラインの一部としてコンテナーイメージを使う必要がある場合は、containers を使って実現できます。コンテナーリソースには、パブリックまたはプライベートの Docker レジストリ、または Azure Container Registry を使用できます。

パイプラインの一部として Docker レジストリのイメージを使う必要がある場合は、汎用コンテナーリソースを定義できます (type キーワードは必要ありません)。

[スキーマ]
例

resources:
  containers:
  - container: string  # identifier (A-Z, a-z, 0-9, and underscore)
    image: string  # container image name
    options: string  # arguments to pass to container at startup
    endpoint: string  # reference to a service connection for the private registry
    env: { string: string }  # list of environment variables to add
    ports: [ string ] # ports to expose on the container
    volumes: [ string ] # volumes to mount on the container
    mapDockerSocket: bool # whether to map in the Docker daemon socket; defaults to true
    mountReadOnly:  # volumes to mount read-only - all default to false
      externals: boolean  # components required to talk to the agent
      tasks: boolean  # tasks required by the job
      tools: boolean  # installable tools like Python and Ruby
      work: boolean # the work directory

ジョブの一部として使われるイメージとして汎用コンテナーリソースを使うことも、コンテナージョブに使うこともできます。パイプラインで 1 つ以上のサービスのサポートが必要な場合は、サービスコンテナーを作成して接続する必要があります。ボリュームを使って、サービス間でデータを共有できます。

resources:         
  containers:
  - container: smartHotel 
    endpoint: myDockerRegistry
    image: smartHotelApp

Azure Container Registry (ACR) のファーストクラスコンテナーリソースの種類を使って、ACR イメージを使用できます。このリソースの種類は、ジョブの一部として使ったり、自動パイプライントリガーを有効にしたりするために使用できます。自動パイプライントリガーを使うには、ACR の共同作成者または所有者アクセス許可が必要です。詳細については、「Azure Container Registry のロールとアクセス許可」をご覧ください。

[スキーマ]
例

resources:          # types: pipelines | repositories | containers | builds | packages
  containers:
  - container: string # identifier for the container resource      
    type: string # type of the registry like ACR, GCR etc. 
    azureSubscription: string # Azure subscription (ARM service connection) for container registry;
    resourceGroup: string # resource group for your ACR
    registry: string # registry for container images
    repository: string # name of the container image repository in ACR
    trigger: # Triggers aren't enabled by default and need to be set explicitly
      enabled: boolean # set to 'true' to trigger on all image tags if 'tags' is unset.
      tags:
        include: [ string ]  # image tags to consider the trigger events, optional; defaults to any new tag
        exclude: [ string ]  # image tags on discard the trigger events, optional; defaults to none

Note

すべてのイメージタグでコンテナートリガーを有効にするために使われる構文は (enabled: 'true')、他のリソーストリガーに使われる構文とは異なります。特定のリソースの正しい構文を使うよう、細心の注意を払ってください。

Note

ワークロード ID フェデレーションを使用するサービス接続は azureSubscriptionでサポートされていません。

resources:         
  containers:
  - container: petStore      
    type: ACR  
    azureSubscription: ContosoARMConnection
    resourceGroup: ContosoGroup
    registry: petStoreRegistry
    repository: myPets
    trigger: 
      tags:
        include: 
        - production*

コンテナーリソース変数

コンテナーをリソースとして定義すると、コンテナーイメージメタデータが変数の形式でパイプラインに渡されます。イメージ、レジストリ、接続の詳細などの情報には、コンテナーデプロイタスクで使われるすべてのジョブからアクセスできます。

コンテナーリソース変数は、Docker とAzure Container Registry で動作します。ローカルイメージコンテナーにコンテナーリソース変数を使用することはできません。

[スキーマ]
例

resources.container.<Alias>.type
resources.container.<Alias>.registry
resources.container.<Alias>.repository
resources.container.<Alias>.tag 
resources.container.<Alias>.digest
resources.container.<Alias>.URI
resources.container.<Alias>.location

場所変数は、ACR の種類のコンテナーリソースにのみ適用されます。

この例には、arm-connection という名前の Azure Resource Manager サービス接続があります。詳しくは、Azure のコンテナーレジストリ、リポジトリ、イメージに関する記事をご覧ください。

resources:
  containers:
  - container: mycontainer # name of the container (Alias) 
    type: ACR # type of registry
    azureSubscription: arm-connection # name of the ARM service connection
    resourceGroup: rg-storage-eastus # Azure resource group with the container
    registry: mycontainerregistry # Azure container registry name
    repository: hello-world # name of the of container image collection
    trigger:
      tags:
      - latest # tag for the container image to use

steps:
- script: echo |
    echo $(resources.container.mycontainer.type)
    echo $(resources.container.mycontainer.registry)
    echo $(resources.container.mycontainer.repository)
    echo $(resources.container.mycontainer.tag)
    echo $(resources.container.mycontainer.digest)
    echo $(resources.container.mycontainer.URI)
    echo $(resources.container.mycontainer.location)

`packages` リソースを定義する

NuGet と npm GitHub パッケージは、YAML パイプラインでリソースとして使用できます。

package リソースを指定するときは、パッケージを NuGet または npm に設定します。新しいパッケージバージョンがリリースされたときの自動パイプライントリガーを有効にすることもできます。

GitHub パッケージを使うには、個人用アクセストークン (PAT) ベースの認証を使い、PAT を使う GitHub サービス接続を作成します。

既定では、パッケージはジョブに自動的にダウンロードされません。ダウンロードするには、getPackage を使います。

[スキーマ]
例

resources:
  packages:
    - package: myPackageAlias # alias for the package resource
      type: Npm # type of the package NuGet/npm
      connection: GitHubConnectionName # GitHub service connection with the PAT type
      name: nugetTest/nodeapp # <Repository>/<Name of the package>
      version: 1.0.1 # Version of the package to consume; Optional; Defaults to latest
      trigger: true # To enable automated triggers (true/false); Optional; Defaults to no triggers

この例では、contoso という名前の GitHub npm パッケージに対する pat-contoso という名前の GitHub サービス接続があります。詳しくは、GitHub パッケージに関するページをご覧ください。

resources:
  packages:
    - package: contoso
      type: npm
      connection: pat-contoso
      name: yourname/contoso 
      version: 7.130.88 
      trigger: true

pool:
  vmImage: 'ubuntu-latest'

steps:
- getPackage: contoso

`webhooks` リソースを定義する

Note

Webhook は、Azure DevOps Server 2020.1 でリリースされました。

他のリソース (パイプライン、コンテナー、ビルド、パッケージなど) では、成果物を使い、自動トリガーを有効にすることができます。ただし、他の外部イベントやサービスに基づいてデプロイプロセスを自動化することはできません。 webhooks リソースを使うと、パイプラインを任意の外部サービスと統合して、ワークフローを自動化できます。外部イベントの Webhook (GitHub、GitHub Enterprise、Nexus、Artifactory など) を介して任意の外部イベントにサブスクライブし、パイプラインをトリガーすることができます。

Webhook トリガーを構成するには、次の手順のようにします。

外部サービスで Webhook を設定します。自分の Webhook を作成するときは、次の情報を指定する必要があります。
- 要求 URL
```
https://dev.azure.com/<ADO Organization>/_apis/public/distributedtask/webhooks/<WebHook Name>?api-version=6.0-preview
```
- シークレット - 省略可能。 JSON ペイロードをセキュリティ保護する必要がある場合は、シークレットの値を指定します。
新しい "着信 Webhook" サービス接続を作成します。この接続は新しく導入されたサービス接続の種類で、次の重要な情報を定義できます。
- Webhook 名: Webhook の名前は、外部サービスで作成した Webhook と一致する必要があります。
- HTTP ヘッダー - 要求検証用のペイロードの HMAC-SHA1 ハッシュ値を含む要求での HTTP ヘッダーの名前。たとえば、GitHub の場合、要求ヘッダーは "X-Hub-Signature" です。
- シークレット - シークレットは、着信要求の検証に使われるペイロードの HMAC-SHA1 ハッシュを検証するために使われます (省略可能)。 Webhook の作成時にシークレットを使った場合は、同じシークレットキーを指定する必要があります。
webhooks という新しいリソースの種類が YAML パイプラインに導入されています。 Webhook イベントにサブスクライブするには、パイプラインで Webhook リソースを定義し、それで着信 Webhook サービス接続をポイントします。また、JSON ペイロードデータに基づいて Webhook リソースでさらにフィルターを定義し、各パイプライン用にトリガーをカスタマイズすることもできます。ペイロードのデータは、ジョブ内の変数の形式で使います。
着信 Webhook サービス接続が Webhook イベントを受信するたびに、その Webhook イベントにサブスクライブされているすべてのパイプラインで新しい実行がトリガーされます。ジョブでは、${{ parameters.<WebhookAlias>.<JSONPath>}} の形式を使って JSON ペイロードのデータを使用できます

[スキーマ]
例

resources:
  webhooks:
    - webhook: MyWebhookTriggerAlias           ### Webhook alias
      connection: IncomingWebhookConnection    ### Incoming webhook service connection
      filters:                                 ### List of JSON parameters to filter; Parameters are AND'ed
        - path: JSONParameterPath              ### JSON path in the payload
          value: JSONParameterExpectedValue    ### Expected value in the path provided

Webhook は、パイプライン、ビルド、コンテナー、パッケージなどのファーストクラスリソースでサポートされていない外部 Webhook イベントに基づいて、ワークフローを自動化します。また、Azure DevOps がプロセス内を認識できないオンプレミスサービスの場合は、サービスで Webhook を構成し、パイプラインを自動的にトリガーできます。

パイプラインは次のように定義できます。

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

steps:  
- script: echo ${{ parameters.WebHook.resource.message.title }}

Webhook を使用してパイプラインをトリガーするには、https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview に POST 要求を行う必要があります。このエンドポイントは一般公開されており、承認は必要ありません。要求には、次の本文が必要です。

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Webhook の要求本文からデータにアクセスする場合は、YAML が正しくない可能性があることに注意してください。たとえば、前のパイプラインでステップが - script: echo ${{ parameters.WebHook.resource.message }} を読み取り、Webhook を介してパイプラインをトリガーした場合、パイプラインは実行されません。これは、${{ parameters.WebHook.resource.message.title }} を次の JSON を含む message に置き換えるプロセスでは、生成された YAML が無効になるからです。

{
  "title": "Hello, world!",
  "subtitle": "I'm using WebHooks!"
}

生成された YAML が無効になるため、応答にキューに入れられるパイプラインはありません。

次のスニペットは、webhook フィルターを使用する別の例を示しています。

resources:
  webhooks:
    - webhook: MyWebhookTrigger          
      connection: MyWebhookConnection    
      filters:
        - path: repositoryName      
          value: maven-releases     
        - path: action
          value: CREATED
steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host ${{ parameters.MyWebhookTrigger.repositoryName}} ### JSON payload data is available in the form of ${{ parameters.<WebhookAlias>.<JSONPath>}}
      Write-Host ${{ parameters.MyWebhookTrigger.component.group}}

実行の作成ダイアログでのリソース用の手動バージョンピッカー

ユーザーが CD YAML パイプラインを手動でトリガーすると、指定された入力に基づいて、パイプラインで定義されているリソースの既定のバージョンが自動的に評価されます。ただし、実行を作成するときに、リソースバージョンピッカーで別のバージョンを選ぶこともできます。

[実行の作成] ペインで、[リソース] を選びます。このパイプラインで使われるリソースの一覧が表示されます。
リソースを選び、使用可能なバージョンの一覧から特定のバージョンを選びます。リソースバージョンピッカーは、パイプライン、ビルド、リポジトリ、コンテナー、パッケージの各リソースでサポートされています。

パイプラインリソースの場合は、すべてのブランチで使用可能なすべての実行を確認できます。パイプライン番号またはブランチに基づいてそれらを検索します。また、成功、失敗、または進行中の実行を選びます。この柔軟性により、ユーザーは必要なすべての成果物が自分の CD パイプラインで確実に生成される場合、それを実行できます。 CI の実行が完了まで待ったり、CI 実行での関係のないステージエラーのために再実行したりする必要はありません。ただし、スケジュールされたトリガーの既定バージョンを評価するときや、手動バージョンピッカーを使わない場合は、正常に完了した CI の実行のみが考慮されます。

GitHub パッケージのように使用可能なバージョンをフェッチできないリソースの場合は、選択する実行のバージョンを指定できるように、バージョンピッカーの一部としてテキストボックスが表示されます。

YAML パイプラインを承認する

リソースを使用できるようにするには、その前にそれを承認する必要があります。リソース所有者は、そのリソースにアクセスできるユーザーとパイプラインを制御します。パイプラインは、リソースの使用を承認される必要があります。 YAML パイプラインを承認する次の方法を参照してください。

リソースの管理エクスペリエンスに移動します。たとえば、変数グループとセキュアファイルは、[パイプライン] の [ライブラリ] ページで管理されます。エージェントプールとサービス接続は、[プロジェクトの設定] で管理されます。ここで、すべてのパイプラインがそのリソースにアクセスすることを承認できます。この承認は、リソース (テストリソースなど) へのアクセスを制限する必要がない場合に便利です。
ユーザーがパイプラインを初めて作成するとき、ユーザーがそのリソースのユーザー ロールのメンバーである場合は、YAML ファイル内で参照されているすべてのリソースがパイプラインによって自動的に使用の承認を受けます。そのため、パイプラインの作成時に YAML ファイルで参照されるリソースは自動的に承認されます。
YAML ファイルを変更してリソースを追加すると、ビルドは次のようなエラーで失敗します: Could not find a <resource> with name <resource-name>. The <resource> does not exist or has not been authorized for use.

この場合、失敗したビルドでリソースを承認するオプションが表示されます。リソースのユーザー ロールのメンバーであるユーザーは、このオプションを選択できます。リソースが承認されたら、新しいビルドを開始できます。
プロジェクトのエージェントプールのセキュリティロールが正しいことを確認します。

リソースの承認チェックを設定する

承認チェックとテンプレートを使って、リソースを実行するタイミングを手動で制御できます。必要なテンプレート承認チェックを使うと、リソースまたは環境を使用するパイプラインに、特定の YAML テンプレートを拡張することも要求できます。必要なテンプレート承認を設定すると、セキュリティが強化されます。リソースがテンプレートに関する特定の条件下でのみ使われることを確認します。テンプレートとリソースを使ってパイプラインのセキュリティを強化する方法の詳細を理解してください。

追跡可能性

パイプラインまたはデプロイジョブのレベルで使われるすべてのリソースについて、完全な追跡可能性が提供されています。

パイプラインの追跡可能性

すべてのパイプライン実行で、次の情報が表示されます。

パイプラインをトリガーしたリソース (リソースによってトリガーされる場合)。
リソースのバージョンと使われた成果物。
各リソースに関連付けられているコミット。
各リソースに関連付けられている作業項目。

環境の追跡可能性

パイプラインが環境にデプロイするたびに、使われているリソースの一覧を確認できます。次のビューには、デプロイジョブの一部として使われたリソースと、関連するコミットと作業項目が含まれます。

Commits in environment

CI パイプラインで関連付けられている CD パイプラインの情報を表示する

エンドツーエンドの追跡可能性を提供するため、特定の CI パイプラインを使っている CD パイプラインを追跡できます。 pipeline リソースを通して CI パイプライン実行が使われている CD YAML パイプライン実行の一覧を確認できます。他のパイプラインで自分の CI パイプラインが使われている場合、実行ビューに [関連付けられているパイプライン] タブが表示されます。ここでは、自分のパイプラインとそれからの成果物を使っているすべてのパイプライン実行を見つけることができます。

CD pipelines information in CI pipeline

YAML リソーストリガーの問題のサポートと追跡可能性

パイプライントリガーの実行が失敗したとき、混乱することがあります。パイプライン定義ページに追加された新しいメニュー項目 [トリガーの問題] では、トリガーが実行されない理由を確認できます。このページにアクセスするには、パイプライン履歴を開きます。 [トリガーの問題] は、リポジトリ以外のリソースでのみ使用できます。

リソーストリガーは、次の理由で実行できない場合があります。

提供されているサービス接続のソースが無効な場合、またはトリガーに構文エラーがある場合は、トリガーが構成されないため、エラーが発生します。
トリガーの条件が一致しない場合、トリガーは実行されません。条件が一致しなかった理由がわかるように、警告が表示されます。

次のステップ

変数グループの追加と使用

よく寄せられる質問

`download` ショートカットの代わりに `resources` パイプラインを使う必要があるのはなぜですか?

pipelines リソースを使うのは、CI パイプラインから成果物を使用し、自動トリガーを構成するための方法です。リソースにより、使われているバージョン、成果物、コミット、作業項目が表示され、プロセスの内容を完全に確認できます。パイプラインリソースを定義すると、関連付けられている成果物がデプロイジョブに自動的にダウンロードされます。

デプロイジョブで成果物をダウンロードするか、download を使ってデプロイジョブのダウンロード動作をオーバーライドするかを選択できます。詳細については、steps.download に関する記事を参照してください。

パイプライン成果物のダウンロードタスクの代わりに `resources` を使う必要があるのはなぜですか?

パイプライン成果物のダウンロードタスクを直接使うと、追跡可能性とトリガーが失われます。パイプライン成果物のダウンロードタスクを直接使うことに意味がある場合があります。たとえば、スクリプトタスクが別のテンプレートに格納されていて、スクリプトタスクでビルドからの成果物をダウンロードする必要がある場合があります。または、テンプレートを使っているユーザーがパイプラインリソースの追加を望んでいるかどうかわからない場合があります。依存関係を回避するには、パイプライン成果物のダウンロードタスクを使って、すべてのビルド情報をタスクに渡すことができます。

Docker Hub のイメージが更新されたときに、パイプライン実行をトリガーするにはどうすればよいですか?

コンテナーリソーストリガーは YAML パイプライン用の Docker Hub では使えないため、クラシックリリースパイプラインを設定する必要があります。

新しい Docker Hub サービス接続を作成します。
クラシックリリースパイプラインを作成し、Docker Hub 成果物を追加します。サービス接続を設定します。名前空間、リポジトリ、バージョン、ソースの別名を選びます。
トリガーを選んで、継続的デプロイトリガーを [有効] に切り替えます。選択したリポジトリに対して Docker のプッシュが発生するたびに、リリースを作成します。
新しいステージとジョブを作成します。 Docker ログインと Bash という 2 つのタスクを追加します。

Docker タスクには login アクションがあり、ユーザーを Docker Hub にログインさせます。
Bash タスクは docker pull <hub-user>/<repo-name>[:<tag>] を実行します。 hub-user、repo-name、tag を独自の値で置き換えます。

Webhook を検証してトラブルシューティングするにはどうすればよいですか?

サービス接続を作成します。

サービス接続を参照し、webhooks セクションで Webhook の名前を指定します。

resources:
  webhooks:
    - webhook: MyWebhookTriggerAlias
      connection: MyServiceConnection

パイプラインを実行する。パイプラインを実行すると、組織の分散タスクとして Webhook が Azure に作成されます。
本文で https://dev.azure.com/{organization}/_apis/public/distributedtask/webhooks/{webhook-name}?api-version={apiversion} への有効な JSON を使って、POST API 呼び出しを実行します。 200 状態コード応答を受け取る場合、Webhook はパイプラインで使用できる状態になっています。 500 状態コード応答とエラー Cannot find webhook for the given webHookId ... を受け取る場合は、コードが既定のブランチではないブランチに存在する可能性があります。
1. パイプラインを開きます。
2. [編集] を選択します。
3. [その他の操作] メニューを選びます。
4. [トリガー]>[YAML]>[ソースの取得] を選びます。
5. [手動のビルドとスケジュールされたビルドの既定のブランチ] に移動して、機能ブランチを更新します。
6. [保存してキューに登録] を選択します。
7. このパイプラインが正常に実行した後、本文で https://dev.azure.com/{organization}/_apis/public/distributedtask/webhooks/{webhook-name}?api-version={apiversion} への有効な JSON を使って POST API 呼び出しを実行します。これで、200 状態コード応答を受け取るようになるはずです。

YAML でリソースを定義する

スキーマ

変数

`pipelines` リソースを定義する

成果物のバージョンの評価

パイプラインの `download`

パイプラインリソース変数

`builds` リソースを定義する

ビルドの `downloadBuild` タスク

`repositories` リソースを定義する

型

変数

変数

`checkout` を使用してリポジトリを使用する

スキーマ

`containers` リソースを定義する

コンテナーリソース変数

`packages` リソースを定義する

`webhooks` リソースを定義する

実行の作成ダイアログでのリソース用の手動バージョンピッカー

YAML パイプラインを承認する

リソースの承認チェックを設定する

追跡可能性

パイプラインの追跡可能性

環境の追跡可能性

CI パイプラインで関連付けられている CD パイプラインの情報を表示する

YAML リソーストリガーの問題のサポートと追跡可能性

次のステップ

よく寄せられる質問

`download` ショートカットの代わりに `resources` パイプラインを使う必要があるのはなぜですか?

パイプライン成果物のダウンロードタスクの代わりに `resources` を使う必要があるのはなぜですか?

Docker Hub のイメージが更新されたときに、パイプライン実行をトリガーするにはどうすればよいですか?

Webhook を検証してトラブルシューティングするにはどうすればよいですか?

フィードバック

フィードバック

その他のリソース

YAML でリソースを定義する

スキーマ

変数

pipelines リソースを定義する

成果物のバージョンの評価

パイプラインの download

パイプライン リソース変数

builds リソースを定義する

ビルドの downloadBuild タスク

repositories リソースを定義する

型

変数

変数

checkout を使用してリポジトリを使用する

スキーマ

containers リソースを定義する

コンテナー リソース変数

packages リソースを定義する

webhooks リソースを定義する

実行の作成ダイアログでのリソース用の手動バージョン ピッカー

YAML パイプラインを承認する

リソースの承認チェックを設定する

追跡可能性

パイプラインの追跡可能性

環境の追跡可能性

CI パイプラインで関連付けられている CD パイプラインの情報を表示する

YAML リソース トリガーの問題のサポートと追跡可能性

次のステップ

よく寄せられる質問

download ショートカットの代わりに resources パイプラインを使う必要があるのはなぜですか?

パイプライン成果物のダウンロード タスクの代わりに resources を使う必要があるのはなぜですか?

Docker Hub のイメージが更新されたときに、パイプライン実行をトリガーするにはどうすればよいですか?

Webhook を検証してトラブルシューティングするにはどうすればよいですか?

関連記事

フィードバック

フィードバック

その他のリソース

`pipelines` リソースを定義する

パイプラインの `download`

パイプラインリソース変数

`builds` リソースを定義する

ビルドの `downloadBuild` タスク

`repositories` リソースを定義する

`checkout` を使用してリポジトリを使用する

`containers` リソースを定義する

コンテナーリソース変数

`packages` リソースを定義する

`webhooks` リソースを定義する

実行の作成ダイアログでのリソース用の手動バージョンピッカー

YAML リソーストリガーの問題のサポートと追跡可能性

`download` ショートカットの代わりに `resources` パイプラインを使う必要があるのはなぜですか?

パイプライン成果物のダウンロードタスクの代わりに `resources` を使う必要があるのはなぜですか?