Azure Pipelines の基本|トリガー・変数・条件・マトリックス・キャッシュと PR のビルド検証を実機で検証(DevOps 編 6)

DevOps

はじめに

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

前回:CI/CD とは

CI/CD とは|Azure Pipelines から App Service への自動デプロイとテスト失敗時の停止を実機で検証(DevOps 編 5)
CI と CD の違い、パイプラインの部品、Azure Pipelines と GitHub Actions の比較を整理し、push から App Service への自動デプロイと、テスト失敗時にデプロイが止まる動きを実機で確かめた。

YAML パイプラインの構造

YAML パイプラインは、リポジトリに置いた azure-pipelines.yml に書く。
YAML ファイルはアプリのコードと一緒にバージョン管理され、同じブランチ構造に従う。

パイプラインは 1 つ以上のステージ、ステージは 1 つ以上のジョブ、ジョブは 1 つ以上のステップでできている。
ステップはタスク(事前にパッケージ化されたスクリプト)かスクリプトのどちらか。
ジョブはエージェントで実行され、エージェントは一度に 1 つのジョブを実行する。

YAML パイプラインの書き方
キーワード内容
triggerどのブランチ・パスへの push で動くか
parametersランタイム パラメーター。手動実行の画面で選べる値
variables変数。ルート、ステージ、ジョブのレベルで定義できる
poolジョブを実行するエージェント(vmImage: ubuntu-latest など)
stages / jobs / stepsステージは既定で 1 つずつ順に実行される。
同じステージのジョブは、dependsOn がなければ並列で実行される
strategymatrix で変数の組ごとにジョブを複数回実行する。
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 の schedulescron 式の時刻(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 つの書き方があり、値が決まるタイミングが違う。

変数の 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@2PublishPipelineArtifact@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 の両方が成功した。

push で始まった実行
番号項目説明
1StagesTest(2 jobs completed)と Package(1 artifact)。
Package は Test の成功を待ってから動いた

「Jobs」タブを見ると、マトリックスで test node22 と test node24 の 2 つのジョブができている。

マトリックスでできたジョブ
番号項目説明
1test node22 / test node24 / packageマトリックスの名前(node22、node24)がジョブ名に付く。
実行記録では、test node22 が終わってから約 11 秒後に test node24 が始まった(並列ジョブが 1 つのため)

test node22 の「npm のキャッシュ」のログでは、キーが package-lock.json のハッシュから計算され、まだキャッシュがないので「There is a cache miss.」になった。

キャッシュがない 1 回目
番号項目説明
1npm のキャッシュCache@2 のステップ。
下の「Post-job: npm のキャッシュ」が保存する役
2There 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 すると、実行が始まった。

コミットとパイプラインの状態
番号項目説明
1README に動かし方を追記Status が空。パイプラインが動いていない
2in progresssrc を変えたコミットでは、パイプラインが動いている
実行の一覧
番号項目説明
1#20261114.5src を変えたコミット(86322fec)の実行。
README のコミットの実行はない

2 回目の実行では、test node22 も test node24 も、キャッシュが復元された。

キャッシュが復元された 2 回目
番号項目説明
1There is a cache hit1 回目と同じキー(package-lock.json が同じ)で見つかった
2Downloaded 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」で動かなかった。

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

④ main にビルド検証のポリシーを付ける

「Repos」⇒「Branches」で main の「…」⇒「Branch policies」を開き、「Build Validation」の「+」から追加した。

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

保存すると、Build Validation にポリシーが 1 つ追加された。

追加したポリシー
番号項目説明
1PR のテストRequired、Automatic、Expires after 12 hours

画面の注記のとおり、必須のポリシーがあるブランチは削除できず、変更は PR でしか入れられない。
試しに main へ直接 push すると、TF402455 で拒否された(「実機でつまずいた点」)。

⑤ テストが通らない PR は完了できない

作業用のブランチ feature/greeting で、表示を「Hello, CI/CD (v1.3.1)」に変え、テストは直さずに push して PR を作った。
PR を作るとビルド検証が自動で動き、テストが失敗した。

ビルド検証が失敗した PR
番号項目説明
11 required check failed必須のチェック「PR のテスト」が失敗。
失敗したステップ(test node24 / テスト)とBash exited with code '1'. が出る

「Complete」を開くと、「PR のテスト failed」と表示され、「Complete merge」は押せなかった。

完了できない PR
番号項目説明
1PR のテスト failed必須のポリシーを満たしていない
2Complete merge押せない状態

PR の実行のログでは、テストが失敗したので、「失敗したときだけ動く」ステップが動いて警告を出した。

失敗したときだけ動くステップ
番号項目説明
1テスト失敗したステップ
2失敗したときだけ動く条件 failed() を満たしたので実行された
3##[warning]task.logissue で出した警告
PR の実行の実行情報
番号項目説明
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」を押せるようになった。

ビルド検証が成功した PR
番号項目説明
1Required check succeeded必須のチェックが成功
2CompletePR を完了(マージ)できる

Squash commit でマージすると、main への push になるので CI トリガーでもう一度実行された。

実行の一覧
番号項目説明
1#20261114.9マージ後の main の実行(Individual CI)
2#20261114.7 / .8PR の実行(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 が必要な人には、ポリシーをバイパスするアクセス許可を付ける方法があるが、付ける範囲は絞る。

main に直接 push できなくなった

推奨構成

項目推奨
パイプラインの種類YAML パイプライン(コードと一緒にバージョン管理する)
トリガーmain への push で CI。
ドキュメントだけの変更などはパス フィルターで外す
PRmain にビルド検証のポリシー(必須)を付け、テストが通らない変更を入れない
値の渡し方実行前に人が選ぶ値はランタイム パラメーター(型と選択肢を決める)、実行中に使う値やシークレットは変数
項目推奨
条件後続のステージは 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 の再利用と統制

Azure Pipelines の再利用と統制|テンプレート・変数グループ・環境と承認/ブランチ制御/必須テンプレートを実機で検証(DevOps 編 7)
Azure Pipelines のテンプレート(挿入と extends)、変数グループとセキュア ファイル、環境とデプロイ ジョブ、承認とチェックを整理。本番の環境を承認・ブランチ制御・必須テンプレートで守る動きを実機で確かめた。

コメント

タイトルとURLをコピーしました