はじめに
DevOps 編の 6 回目は、Azure Pipelines の基本。
前回は push からテスト、App Service へのデプロイまでを一通り動かした。
今回は YAML パイプラインの書き方を細かく見ていく。
トリガー、変数と式、条件、マトリックスと並列ジョブ、キャッシュと成果物、クラシック パイプラインとの違いを押さえ、PR のビルド検証まで実機で確かめる。
前回:CI/CD とは

YAML パイプラインの構造
YAML パイプラインは、リポジトリに置いた azure-pipelines.yml に書く。
YAML ファイルはアプリのコードと一緒にバージョン管理され、同じブランチ構造に従う。
パイプラインは 1 つ以上のステージ、ステージは 1 つ以上のジョブ、ジョブは 1 つ以上のステップでできている。
ステップはタスク(事前にパッケージ化されたスクリプト)かスクリプトのどちらか。
ジョブはエージェントで実行され、エージェントは一度に 1 つのジョブを実行する。

| キーワード | 内容 |
|---|---|
| trigger | どのブランチ・パスへの push で動くか |
| parameters | ランタイム パラメーター。手動実行の画面で選べる値 |
| variables | 変数。ルート、ステージ、ジョブのレベルで定義できる |
| pool | ジョブを実行するエージェント(vmImage: ubuntu-latest など) |
| stages / jobs / steps | ステージは既定で 1 つずつ順に実行される。 同じステージのジョブは、dependsOn がなければ並列で実行される |
| strategy | matrix で変数の組ごとにジョブを複数回実行する。 maxParallel で同時に動かす数を制限できる |
| condition / dependsOn | 実行する条件と、待つ相手 |
公式ドキュメント:
主要なAzure Pipelinesの概念 | Microsoft Learn
パイプラインにジョブを指定する | Microsoft Learn
ステージ、依存関係、条件を追加する | Microsoft Learn
トリガー
トリガーは、パイプラインを動かすきっかけ。
Azure Repos のリポジトリでは、CI トリガー、PR 検証、スケジュール、パイプライン トリガー、手動がある。
どのトリガーで動いたかは、定義済み変数 Build.Reason でわかる。

| トリガー | 書く場所 | 動くとき |
|---|---|---|
| CI トリガー | YAML の trigger | ブランチへの push。branches と paths で絞れる |
| PR 検証 | ブランチ ポリシーのビルド検証 | PR を開いたときと、PR のソース ブランチに push したとき |
| スケジュール | YAML の schedules | cron 式の時刻(UTC) |
| パイプライン トリガー | YAML の resources: pipelines | 別のパイプラインが正常に完了したとき |
| 手動 | ポータルの Run pipeline など | 人が実行したとき |
trigger を書かないと、すべてのブランチへの push で動く。
trigger を書くと、含めると書いたブランチへの push だけになる。
パス フィルターは、リポジトリのルートからのパスで書き、大文字と小文字を区別する。
パス フィルターだけではパイプラインは動かず、ブランチ フィルターも要る。
trigger、パス、スケジュールには変数を使えない(変数は実行時に評価されるため)。
Azure Repos Git では、PR 検証を YAML の pr ではなく、ターゲット ブランチのブランチ ポリシー(ビルド検証)で設定する。
ドラフトの PR では、ブランチ ポリシーを構成してもパイプラインは動かない。
公式ドキュメント:
Azure Repos Git または TFS Git リポジトリをビルドする | Microsoft Learn
パイプラインのスケジュールを構成する | Microsoft Learn
パイプラインを 1 つずつトリガーする | Microsoft Learn
定義済み変数の使用 | Microsoft Learn
変数と式
変数は、パイプラインの実行中に使う値。
自分で定義するユーザー定義変数と、Build.SourceBranch のような定義済み変数(システム変数)がある。
変数は、スクリプトの中では環境変数としても使え、名前は大文字になり、ピリオドはアンダースコアになる(Build.Reason なら BUILD_REASON)。
変数の参照には 3 つの書き方があり、値が決まるタイミングが違う。

| 書き方 | 処理されるとき | 主な使い道 |
|---|---|---|
| ${{ variables.var }}(テンプレート式) | コンパイル時(実行の開始前) | パラメーターや、YAML の一部を組み立てるとき |
| $[ variables.var ](ランタイム式) | 実行時(ジョブやステージの実行前) | 条件や、変数の動的な割り当て。定義の右側全体に書く |
| $(var)(マクロ構文) | 実行時(各タスクの実行前) | タスクの入力やスクリプト |
ランタイム パラメーターは、parameters に名前、型、既定値、選択肢を書く。
手動実行の画面に表示されて実行前に選べるが、キューに入ったあとは変更できず、シークレットには使えない。
実行中ずっと使いたい値や、シークレットは変数にする。
公式ドキュメント:
変数の定義 | Microsoft Learn
ランタイム パラメーター | Microsoft Learn
式 | Microsoft Learn
条件と依存関係
何も書かなければ、ステージやジョブは依存先がすべて成功したときに動く。
ステップは、ジョブ内でまだ何も失敗しておらず、直前のステップが完了したときに動く。
condition を書くと、この既定の条件を上書きする。

| 条件 | 動くとき |
|---|---|
| succeeded() | 前の依存関係がすべて成功したとき(既定) |
| succeededOrFailed() | 前の依存関係が失敗しても動く。取り消されたときは動かない |
| always() | 前の依存関係が失敗しても、実行が取り消されても動く |
| failed() | 前の依存関係が失敗したときだけ |
| 独自の条件 | and()、eq() などの関数を組み合わせる。 前の結果も見るなら succeeded() なども入れる |
ステージ間やジョブ間の依存関係は dependsOn で決める。
今回の Package ステージは「dependsOn: Test」とand(succeeded(), eq('${{ parameters.mode }}', 'package'))で、Test が成功し、かつ mode が package のときだけ動くようにした。
公式ドキュメント:
パイプラインの条件 | Microsoft Learn
ステージ、依存関係、条件を追加する | Microsoft Learn
ジョブの並列化とマトリックス
strategy の matrix を使うと、変数の組ごとに同じジョブを複数回実行できる。
Node.js のバージョン違いや OS 違いで同じテストを回すときに使う。
ただし、同時に動くジョブの数は組織の並列ジョブの数で決まる。
並列ジョブは組織単位で、組織内のすべてのパイプラインで共有する。
並列ジョブが 1 つなら、パイプラインをいくつ始めても、一度に動くジョブは 1 つだけで、残りは空きを待つ。
| レベル(Microsoft ホステッド) | 1 回の実行時間 | 月の上限 |
|---|---|---|
| Free(プライベート プロジェクト) | 最大 60 分(並列ジョブ 1 つ) | 1,800 分(30 時間) |
| 有料 | 最大 360 分 | なし |
Free レベルで 1 つ目の並列ジョブを購入しても、並列ジョブは 1 つのままで、時間の上限がなくなるだけ。
2 つのジョブを同時に動かすには、並列ジョブを 2 つ購入する。
公式ドキュメント:
パイプラインにジョブを指定する | Microsoft Learn
並列ジョブの構成と支払い | Microsoft Learn
キャッシュと成果物
パイプライン キャッシュは、前の実行でダウンロードした依存関係(npm のパッケージなど)を再利用して、ビルド時間を短くする仕組み。
パイプライン成果物は、あるジョブで作ったファイルを、あとのジョブに渡す仕組み。
どちらも無料・有料のすべてのレベルで使える。

| 項目 | パイプライン キャッシュ | パイプライン成果物 |
|---|---|---|
| 目的 | ビルド時間を短くする | ジョブ間でファイルを渡す |
| ないとき | ジョブはそのまま動く(時間がかかるだけ) | あとのジョブが失敗することがある |
| タスク | Cache@2 | PublishPipelineArtifact@1 / DownloadPipelineArtifact@2 |
| 消えるとき | 7 日間使われないと期限切れ | パイプラインの実行を削除すると、その実行の成果物も削除される |
キャッシュは key で探し、見つからなければ restoreKeys の前方一致で最後に作られたものを探す。
ジョブのすべてのステップが成功すると、「Post-job」のステップで path のフォルダーが保存される。
キャッシュは作成後に変更できない。
キャッシュはパイプラインとブランチごとのスコープに保存される。
PR の実行は、ターゲット ブランチ(main など)のキャッシュを読めるが、そこには書き込めない。
公式ドキュメント:
パイプライン キャッシュ | Microsoft Learn
パイプライン成果物を発行してダウンロードする | Microsoft Learn
クラシック パイプラインと YAML
Azure Pipelines には、YAML パイプラインと、ポータルの画面で組み立てるクラシック パイプライン(ビルド用)とクラシック リリース(デプロイ用)がある。
初めて使うなら YAML から始めることが推奨されていて、既存のクラシック パイプラインは YAML に移行することもできる。
| 機能 | YAML | クラシック パイプライン | クラシック リリース |
|---|---|---|---|
| トリガー、変数、条件、タスク | ○ | ○ | ○ |
| ステージ、依存関係 | ○ | × | ○ |
| 承認 | ○ | × | ○ |
| キャッシュ | ○ | ○ | × |
| テンプレート | ○ | × | × |
| コンテナー ジョブ、デプロイ ジョブ | ○ | × | × |
| ゲート | × | × | ○ |
| タスク グループ | × | ○ | ○ |
| 方式 | メリット | デメリット |
|---|---|---|
| YAML | コードと一緒にバージョン管理され、ブランチごとに変えられる。 問題を起こした変更をコードの履歴から探せる | YAML の書き方を覚える必要がある |
| クラシック | 画面で組み立てられる | パイプラインの定義がコードと一緒にバージョン管理されない。 テンプレートなど使えない機能がある |
公式ドキュメント:
YAML とクラシック パイプラインの比較 | Microsoft Learn
クラシック パイプラインを YAML に移行する | Microsoft Learn
構築手順
今回の構成と実施すること

| 手順 | 実施すること | 確かめること |
|---|---|---|
| ① | azure-pipelines.yml を書き換えて main に push する | Node.js 22 と 24 のジョブが 1 本ずつ動く。 1 本目はキャッシュなし |
| ② | README だけを変えて push し、次に src を変えて push する | README だけでは動かず、src の変更で動く。キャッシュが復元される |
| ③ | 手動実行で mode に test-only を選ぶ | Package ステージが動かない |
| ④ | main にビルド検証のブランチ ポリシーを付ける | main に直接 push できなくなる |
| ⑤ | テストが通らない PR を作り、直してからマージする | 失敗すると PR を完了できない。失敗時だけ動くステップが動く |
リポジトリとパイプラインは前回の cicd-demo をそのまま使い、デプロイはしない。
依存パッケージのキャッシュを試すため、ESLint を devDependencies に入れて npm run lint を足した。
① マトリックスとキャッシュを入れて push する
azure-pipelines.yml を次のように書き換えた。
trigger:
branches:
include:
- main
paths:
include:
- src
parameters:
- name: mode
displayName: 実行モード
type: string
default: package
values:
- package
- test-only
variables:
npm_config_cache: $(Pipeline.Workspace)/.npm
isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]
pool:
vmImage: ubuntu-latest
stages:
- stage: Test
jobs:
- job: test
strategy:
matrix:
node22:
nodeVersion: '22.x'
node24:
nodeVersion: '24.x'
steps:
- task: UseNode@1
inputs:
version: $(nodeVersion)
displayName: Node.js $(nodeVersion) を入れる
- task: Cache@2
inputs:
key: 'npm | "$(Agent.OS)" | src/package-lock.json'
restoreKeys: |
npm | "$(Agent.OS)"
path: $(npm_config_cache)
displayName: npm のキャッシュ
- script: npm ci
workingDirectory: src
displayName: 依存パッケージを入れる
- script: npm run lint
workingDirectory: src
displayName: ESLint
- script: npm test
workingDirectory: src
displayName: テスト
- script: echo "##vso[task.logissue type=warning]テストが失敗しました(Node $(nodeVersion))"
condition: failed()
displayName: 失敗したときだけ動く
- script: |
echo "Node: $(nodeVersion)"
echo "mode: ${{ parameters.mode }}"
echo "isMain: $(isMain)"
echo "Build.Reason: $(Build.Reason)"
condition: always()
displayName: 常に動く(実行情報)
- stage: Package
dependsOn: Test
condition: and(succeeded(), eq('${{ parameters.mode }}', 'package'))
jobs:
- job: package
steps:
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: src
includeRootFolder: false
archiveType: zip
archiveFile: $(Build.ArtifactStagingDirectory)/app.zip
displayName: zip にまとめる
- task: PublishPipelineArtifact@1
inputs:
targetPath: $(Build.ArtifactStagingDirectory)
artifact: drop
displayName: 成果物を発行
npm のキャッシュ フォルダーは、npm_config_cache 変数で $(Pipeline.Workspace)/.npm に変えている。
キーは「npm」「OS」「package-lock.json のハッシュ」の 3 つで、package-lock.json が変われば別のキャッシュになる。
main に push すると、CI トリガーで実行が始まり、Test と Package の両方が成功した。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | Stages | Test(2 jobs completed)と Package(1 artifact)。 Package は Test の成功を待ってから動いた |
「Jobs」タブを見ると、マトリックスで test node22 と test node24 の 2 つのジョブができている。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | test node22 / test node24 / package | マトリックスの名前(node22、node24)がジョブ名に付く。 実行記録では、test node22 が終わってから約 11 秒後に test node24 が始まった(並列ジョブが 1 つのため) |
test node22 の「npm のキャッシュ」のログでは、キーが package-lock.json のハッシュから計算され、まだキャッシュがないので「There is a cache miss.」になった。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | npm のキャッシュ | Cache@2 のステップ。 下の「Post-job: npm のキャッシュ」が保存する役 |
| 2 | There is a cache miss. | キーにも restoreKeys にも一致するキャッシュがなかった |
このあと Post-job のステップで、約 2.8 MB がアップロードされ「Cache item created.」と出た。
あとから動いた test node24 は、このキャッシュを「There is a cache hit」で使った。
「常に動く(実行情報)」のログでは、3 つの書き方の値が出ている。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 失敗したときだけ動く | テストが成功したので、条件 failed() を満たさずスキップされた |
| 2 | 出力 | Node: 22.x(マクロ構文)、mode: package(テンプレート式)、isMain: True(ランタイム式)、Build.Reason: IndividualCI |
② パス フィルターとキャッシュの復元を確かめる
README.md だけを変えて main に push した。
trigger の paths は src だけなので、パイプラインは動かなかった。
続けて src/app.js のバージョンを 1.3.1 に変えて push すると、実行が始まった。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | README に動かし方を追記 | Status が空。パイプラインが動いていない |
| 2 | in progress | src を変えたコミットでは、パイプラインが動いている |

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | #20261114.5 | src を変えたコミット(86322fec)の実行。 README のコミットの実行はない |
2 回目の実行では、test node22 も test node24 も、キャッシュが復元された。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | There is a cache hit | 1 回目と同じキー(package-lock.json が同じ)で見つかった |
| 2 | Downloaded 3.0 MB | キャッシュをダウンロードして復元した |
今回の依存パッケージは 78 個と少なく、npm ci の表示はキャッシュの有無にかかわらず「added 78 packages … in 2s」だった。
キャッシュは、復元と保存にかかる時間がファイルを作り直す時間より短いときに効く。
依存パッケージが少ないうちは、効果は小さい。
③ ランタイム パラメーターで Package を止める
パイプラインの画面で「Run pipeline」を押すと、parameters に書いた「実行モード」が選択肢として出た。
test-only を選んで実行した。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 実行モード | displayName が見出しになり、values が選択肢になる。 既定は default の package |
Test ステージは成功し、Package ステージは「Skipped due to conditions」で動かなかった。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | Parameters | 実行に使ったパラメーターを確認できる |
| 2 | Package | Skipped due to conditions。eq('${{ parameters.mode }}', 'package') が満たされなかった |

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | mode | test-only で実行された |
④ main にビルド検証のポリシーを付ける
「Repos」⇒「Branches」で main の「…」⇒「Branch policies」を開き、「Build Validation」の「+」から追加した。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | Build pipeline | PR で動かすパイプライン。cicd-demo を選んだ |
| 2 | Trigger | Automatic は、PR のソース ブランチが更新されるたびに動く。 Manual は人がキューに入れる |
| 3 | Policy requirement | Required は、ビルドが成功しないと PR を完了できない。 Optional は、失敗しても完了を止めない |
| 4 | Build expiration | main が更新されたとき、ビルドの結果をいつ無効にするか。既定は 12 時間 |
| 5 | Display name | PR の画面に出る名前 |
保存すると、Build Validation にポリシーが 1 つ追加された。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | PR のテスト | Required、Automatic、Expires after 12 hours |
画面の注記のとおり、必須のポリシーがあるブランチは削除できず、変更は PR でしか入れられない。
試しに main へ直接 push すると、TF402455 で拒否された(「実機でつまずいた点」)。
⑤ テストが通らない PR は完了できない
作業用のブランチ feature/greeting で、表示を「Hello, CI/CD (v1.3.1)」に変え、テストは直さずに push して PR を作った。
PR を作るとビルド検証が自動で動き、テストが失敗した。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 1 required check failed | 必須のチェック「PR のテスト」が失敗。 失敗したステップ(test node24 / テスト)と Bash exited with code '1'. が出る |
「Complete」を開くと、「PR のテスト failed」と表示され、「Complete merge」は押せなかった。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | PR のテスト failed | 必須のポリシーを満たしていない |
| 2 | Complete merge | 押せない状態 |
PR の実行のログでは、テストが失敗したので、「失敗したときだけ動く」ステップが動いて警告を出した。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | テスト | 失敗したステップ |
| 2 | 失敗したときだけ動く | 条件 failed() を満たしたので実行された |
| 3 | ##[warning] | task.logissue で出した警告 |

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | 出力 | isMain: False、Build.Reason: PullRequest。 PR の実行では Build.SourceBranch が refs/pull/3/merge になる |
この PR の実行のキャッシュは、作業用ブランチのスコープでは見つからず、main のスコープのキャッシュが使われた(ログに「Missed on the following scopes: …refs/heads/feature/greeting…」と出た)。
テストを新しい表示に合わせて、同じブランチに push した。
ビルド検証がもう一度動いて成功し、「Complete」を押せるようになった。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | Required check succeeded | 必須のチェックが成功 |
| 2 | Complete | PR を完了(マージ)できる |
Squash commit でマージすると、main への push になるので CI トリガーでもう一度実行された。

| 番号 | 項目 | 説明 |
|---|---|---|
| 1 | #20261114.9 | マージ後の main の実行(Individual CI) |
| 2 | #20261114.7 / .8 | PR の実行(PR automated)。.7 はテストが失敗、.8 は成功 |
実機でつまずいた点
TF402455: Pushes to this branch are not permitted; you must use a pull request to update this branch.
main にビルド検証のポリシー(必須)を付けたあと、手元で作ったコミットを main に直接 push すると、「[remote rejected]」で拒否された。
必須のポリシーがあるブランチは、PR でしか更新できない。
作業用のブランチに push して PR を作り、ビルド検証が通ってからマージした。
どうしても直接 push が必要な人には、ポリシーをバイパスするアクセス許可を付ける方法があるが、付ける範囲は絞る。

推奨構成
| 項目 | 推奨 |
|---|---|
| パイプラインの種類 | YAML パイプライン(コードと一緒にバージョン管理する) |
| トリガー | main への push で CI。 ドキュメントだけの変更などはパス フィルターで外す |
| PR | main にビルド検証のポリシー(必須)を付け、テストが通らない変更を入れない |
| 値の渡し方 | 実行前に人が選ぶ値はランタイム パラメーター(型と選択肢を決める)、実行中に使う値やシークレットは変数 |
| 項目 | 推奨 |
|---|---|
| 条件 | 後続のステージは succeeded() を基本にする。 後片付けや結果の記録は always()、失敗時の通知は failed() |
| マトリックス | バージョン違いのテストに使う。並列ジョブの数を超える分は順番待ちになる |
| キャッシュ | キーに lock ファイルのハッシュを入れ、restoreKeys で近いキャッシュも使う |
| ジョブ間のファイル | キャッシュではなくパイプライン成果物で渡す |
注意事項
| 項目 | 内容 |
|---|---|
| 並列ジョブ | Free レベルは並列ジョブ 1 つ。 マトリックスや複数のパイプラインは 1 本ずつ動く |
| 実行時間 | Free レベルは 1 回最大 60 分、月 1,800 分。 並列ジョブを購入すると 1 回最大 360 分 |
| トリガーと変数 | trigger、パス、スケジュールには変数を使えない |
| パス フィルター | 大文字と小文字を区別する。ブランチ フィルターと組み合わせる |
| 項目 | 内容 |
|---|---|
| condition | 書くと既定の条件を上書きする。always() は実行を取り消しても動く |
| PR 検証 | Azure Repos Git では YAML の pr ではなくブランチ ポリシーで設定する。 ドラフトの PR では動かない |
| 直接 push | 必須のポリシーを付けたブランチには直接 push できない(TF402455) |
| ubuntu-latest | 実行時に「The ubuntu-latest label will migrate to Ubuntu 26 beginning October 19, 2026.」の警告が出た |
公式ドキュメント:
Azure Repos Git または TFS Git リポジトリをビルドする | Microsoft Learn
並列ジョブの構成と支払い | Microsoft Learn
ブランチ ポリシーの設定と管理 | Microsoft Learn
まとめ
・YAML パイプラインは trigger、parameters、variables、pool、stages(jobs、steps)の順に書き、コードと一緒にバージョン管理する。
・パス フィルターで、README だけの push では動かず、src の変更で動いた。
・${{ }} はコンパイル時、$[ ] はジョブやステージの前、$( ) は各タスクの前に評価され、ランタイム パラメーターで Package ステージを止められた。
・マトリックスで Node.js 22 と 24 のジョブができたが、並列ジョブが 1 つなので 1 本ずつ動いた。
・Cache@2 は 1 回目に miss して保存し、次からは復元した。
PR の実行は main のキャッシュを読んだ。
・ビルド検証のポリシーで、テストが通らない PR は完了できず、failed() のステップだけが動いた。
次回:Azure Pipelines の再利用と統制




コメント