パイプライン実行シーケンス

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

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

実行は、パイプラインの 1 つの実行を表します。実行中にパイプラインが処理され、エージェントは 1 つ以上のジョブを処理します。パイプライン実行には、ジョブ、ステップ、タスクが含まれます。実行により、継続的インテグレーション (CI) と継続的デリバリー (CD) パイプラインの両方が強化されます。

パイプラインの概要

パイプラインを実行すると、さまざまなことが内部で起こります。多くの場合、それらについて知る必要はありませんが、全体像を把握しておくと便利な場合もあります。大まかに言えば、Azure Pipelines では次のようになります。

パイプラインを処理する
ジョブの実行を 1 つ以上のエージェントに要求する
エージェントにジョブを引き渡して結果を収集する

エージェント側では、ジョブごとに、エージェントは次を行います。

ジョブの準備をする
ジョブの各ステップを実行する
結果を Azure Pipelines にレポートする

ジョブは、成功することも、失敗することも、キャンセルされることもあります。また、ジョブが完了しない場合もあります。これがどのように起こるかを理解すると、問題のトラブルシューティングに役立ちます。

各アクションを 1 つずつ分解してみましょう。

パイプラインを処理する

YAML テンプレートを展開する

パイプラインを実行に変換するために、Azure Pipelines では次の順序でいくつかのステップを実行します。

まず、テンプレートを展開し、テンプレート式を評価します。
次に、ステージレベルで依存関係を評価して、実行する最初のステージを選択します。
実行するように選択されたステージごとに、次の 2 つが行われます。
- すべてのジョブで使用されるすべてのリソースが収集され、実行のための認可が検証されます。
- ジョブレベルで依存関係を評価して、最初に実行するジョブを選択します。
実行するように選択したジョブごとに、複数構成 (YAML では strategy: matrix または strategy: parallel) を複数のランタイムジョブに展開します。
各ランタイムジョブについて、条件を評価して、そのジョブが実行対象かどうかを判断します。
対象となる各ランタイムジョブのエージェントを要求します。

ランタイムジョブが完了すると、Azure Pipelines は実行可能な新しいジョブがあるかどうかを確認します。その場合は、新しいジョブについて手順 4 から 6 を繰り返します。同様に、ステージが完了すると、新しいステージに対して手順 2 から 6 が繰り返されます。

この順序付けは、一般的な質問に答えるのに役立ちます。テンプレートパラメーターで特定の変数を使用できないのはなぜですか? 手順 1. テンプレートの拡張は、YAML ドキュメントのテキストに対してのみ動作します。その手順実行中は、ランタイム変数は存在しません。手順 1 の後、テンプレートパラメーターは解決され、存在しなくなりました。

また、もう 1 つの一般的な問題、つまり「サービス接続名や環境名を解決するために変数を使用できないのはなぜですか?」という問題にも答えます。ステージの実行を開始する前にリソースが承認されるため、ステージとジョブレベルの変数は使用できません。パイプラインレベルの変数は使用できますが、パイプラインに明示的に含まれている変数のみを使用できます。変数グループ自体は、認証の対象となるリソースであるため、リソースの認証を確認するときにデータは同様に使用できません。

エージェントを要求する

Azure Pipelines でジョブを実行する必要がある場合は常に、プールにエージェントを要求します。 (サーバージョブは、Azure Pipelines サーバー自体で実行されるため、例外です)。 Microsoft がホストするエージェントプールとセルフホステッドエージェントプールの動作は若干異なります。

Microsoft がホストするエージェントプールの要求

最初に、サービスは組織の並列ジョブを確認します。すべての Microsoft がホストするエージェントで実行中のすべてのジョブが加算され、購入した並列ジョブの数と比較されます。使用可能な並列スロットがない場合、ジョブはスロットが解放されるまで待機する必要があります。

並列スロットが使用可能になると、ジョブは要求されたエージェントの種類にルーティングされます。概念的には、Microsoft がホストするプールは、マシンの巨大なグローバルプールの 1 つです。 (実際には、地理とオペレーティングシステムの種類によって分割された多くの異なる物理プールです。) 要求された vmImage (YAML の場合) またはプール名 (クラシックエディターの場合) に基づいて、エージェントが選択されます。

プールの選択

MiMicrosoft プール内のすべてのエージェントは、これまでパイプラインを実行したことがない、新しい仮想マシンです。ジョブが完了すると、エージェント VM は破棄されます。

セルフホステッドエージェントプールの要求

Microsoft がホストするプールと同様に、サービスは最初に組織の並列ジョブを確認します。すべてのセルフホステッドエージェントで実行中のすべてのジョブが加算され、購入した並列ジョブの数と比較されます。使用可能な並列スロットがない場合、ジョブはスロットが解放されるまで待機する必要があります。

並列スロットが使用可能になると、セルフホステッドプールで互換性のあるエージェントが調べられます。セルフホステッドエージェントは、特定のソフトウェアがインストールされているか、設定が構成されていることを示す文字列である機能を提供します。パイプラインには、ジョブの実行に必要な機能である要求があります。パイプラインの要求に一致する機能を持つ空きエージェントが見つからない場合、ジョブは待機を続けます。要求に一致する機能を持つエージェントがプールに存在しない場合、ジョブは失敗します。

セルフホステッドエージェントは、通常、実行ごとに再利用されます。セルフホステッドエージェントの場合、パイプラインジョブには、キャッシュのウォームアップや、ほとんどのコミットがローカルリポジトリで既に使用できるなどの副作用が発生する可能性があります。

ジョブを実行する準備

エージェントがジョブを受け入れると、いくつかの準備作業が行われます。エージェントは、ジョブの実行に必要なすべてのタスクをダウンロードします (そして次回のためにキャッシュします)。実行で使用されるソースコード、成果物、および出力を保持するための作業領域がディスク上に作成されます。その後、ステップの実行が開始されます。

各ステップを実行する

ステップは順番に実行されます。ステップを開始する前に、前のステップをすべて完了する (またはスキップする) 必要があります。

各タスクを実行する

ステップはタスクによって実装されています。タスク自体は、Node.js スクリプトまたは PowerShell スクリプトとして実装されます。タスクシステムは、入力と出力をバッキングスクリプトにルーティングします。また、システムパスの変更や新しいパイプライン変数の作成など、いくつかの一般的なサービスも提供します。

各ステップは独自のプロセスで実行され、前のステップで残された環境から分離されます。このステップごとのプロセスモデルのため、環境変数はステップ間で保持されません。ただし、タスクとスクリプトには、エージェントと通信するためのメカニズム (ログコマンド) があります。タスクまたはスクリプトがログコマンドを標準出力に書き込むと、エージェントは要求されたアクションを実行します。

新しいパイプライン変数を作成するエージェントコマンドがあります。パイプライン変数は、次のステップで環境変数に自動的に変換されます。新しい変数 myVar に値 myValue を設定するには、スクリプトでこれを実行できます。

echo '##vso[task.setVariable variable=myVar]myValue'

Write-Host "##vso[task.setVariable variable=myVar]myValue"

結果を報告して収集する

各ステップでは、警告、エラー、および失敗を報告できます。エラーと警告がパイプラインの概要ページに報告され、タスクが "成功 (問題あり)" とマークされます。失敗は概要ページにも報告されますが、タスクは "失敗" としてマークされます。ステップが明示的に失敗を報告するか (##vso コマンドを使用)、ゼロ以外の終了コードでスクリプトを終了する場合、そのステップは失敗です。

エージェントからサービスへのログと結果のフロー

ステップが実行されると、エージェントは常に出力行をサービスに送信します。そのため、コンソールのライブフィードが表示されます。各ステップの最後には、ステップからの出力全体もログファイルとしてアップロードされます。ログは、パイプラインが完了したらダウンロードできます。エージェントがアップロードできるその他の項目には、成果物やテスト結果が含まれます。これらは、パイプラインの完了後にも使用できます。

状態と条件

エージェントは、各ステップの成功または失敗を追跡します。問題または失敗したステップが成功すると、ジョブの状態が更新されます。ジョブには、各ステップからの "最悪" の結果が常に反映されます。ステップが失敗すると、ジョブも失敗します。

ステップを実行する前に、エージェントはそのステップの条件をチェックして、ステップを実行する必要があるかどうかを判断します。既定では、ステップはジョブの状態が成功または問題ありで成功した場合にのみ実行されます。多くのジョブには、他に何が起こっても実行する必要があるクリーンアップステップがあるため、"always()" という条件を指定できます。クリーンアップステップは、キャンセル時にのみ実行するように設定することもできます。後続のクリーンアップステップでは、ジョブの失敗を防ぐことはできません。ジョブは一度失敗すると、決して成功に戻ることはできません。

タイムアウトと切断

各ジョブにはタイムアウトがあります。指定された時間内にジョブが完了しなかった場合、サーバーはジョブをキャンセルします。エージェントに停止の通知が試行され、ジョブがキャンセル済みとしてマークされます。エージェント側では、これは残りのすべてのステップをキャンセルし、残りの結果をアップロードすることを意味します。

ジョブには、キャンセル処理を完了するためのキャンセルタイムアウトと呼ばれる猶予期間があります。 (ステップは、キャンセル時でも実行するようにマークできることに注意してください。) タイムアウトとキャンセルタイムアウトの後、エージェントが作業が停止したことを報告していない場合、サーバーはジョブを失敗としてマークします。

Azure Pipelines はエージェントマシンに作業を分散するため、エージェントがサーバーへの応答を停止する場合があります。これは、エージェントのホストマシンが停止した場合 (電源が失われたり、VM がオフになったりした場合)、またはネットワーク障害が発生した場合に発生する可能性があります。これらの条件を検出するために、エージェントは 1 分に 1 回ハートビートメッセージを送信して、まだ動作中であることをサーバーに通知します。サーバーが 5 分間連続してハートビートを受信しない場合、サーバーはエージェントが戻ってこないものとみなします。ジョブは失敗としてマークされ、パイプラインを再試行する必要があることをユーザーに知らせます。

CLI を使用して実行を管理する

Azure DevOps CLI を使用すると、プロジェクト内のパイプライン実行を一覧表示し、特定の実行に関する詳細を表示できます。パイプライン実行でタグを追加および削除することもできます。

前提条件

「Azure DevOps CLI の概要」の説明に従って、Azure DevOps CLI 拡張機能をインストールしている必要があります。
az login を使用して、Azure DevOps にサインインします。
この記事の例では、az devops configure --defaults organization=YourOrganizationURL を使用して既定の組織を設定します。

パイプライン実行を一覧表示する

az pipelines run list コマンドを使用して、プロジェクト内のパイプライン実行を一覧表示します。開始するには、「Azure DevOps CLI の概要」を参照してください。

az pipelines runs list [--branch]
                       [--org]
                       [--pipeline-ids]
                       [--project]
                       [--query-order {FinishTimeAsc, FinishTimeDesc, QueueTimeAsc, QueueTimeDesc, StartTimeAsc, StartTimeDesc}]
                       [--reason {all, batchedCI, buildCompletion, checkInShelveset, individualCI, manual, pullRequest, schedule, triggered, userCreated, validateShelveset}]
                       [--requested-for]
                       [--result {canceled, failed, none, partiallySucceeded, succeeded}]
                       [--status {all, cancelling, completed, inProgress, none, notStarted, postponed}]
                       [--tags]
                       [--top]

省略可能なパラメーター

branch: このブランチのビルドでフィルター処理します。
org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。例: --org https://dev.azure.com/MyOrganizationName/.
pipeline-ids: ビルドを一覧表示する定義のスペース区切り ID。
project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。
query-order: パイプライン実行が一覧表示される順序を定義します。指定できる値は、FinishTimeAsc、FinishTimeDesc、QueueTimeAsc、QueueTimeDesc、StartTimeAsc、StartTimeDesc です。
reason: この指定された理由によるビルドのみを一覧表示します。指定できる値は、batchedCI、buildCompletion、checkInShelveset、individualCI、manual、pullRequest、schedule、triggered、userCreated、validateShelveset です。
requested-for: 指定したユーザーまたはグループに対して要求されたビルドに制限します。
result: 指定した結果のビルドに制限します。指定できる値は、canceled、failed、none、partiallySucceeded、succeeded です。
status: 指定した状態のビルドに制限します。指定できる値は、all、cancelling、completed、inProgress、none、notStarted、postponed です。
tags: 指定された各タグを使用するビルドに制限します。スペースを区切ります。
top: 一覧表示するビルドの最大数。

例

次のコマンドは、状態が completed で、結果が succeeded である最初の 3 つのパイプライン実行を一覧表示し、結果をテーブル形式で返します。

az pipelines runs list --status completed --result succeeded --top 3 --output table

Run ID    Number      Status     Result     Pipeline ID    Pipeline Name               Source Branch    Queued Time                 Reason
--------  ----------  ---------  ---------  -------------  --------------------------  ---------------  --------------------------  ------
125       20200124.1  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 18:56:10.067588  manual
123       20200123.2  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 11:55:56.633450  manual
122       20200123.1  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 11:48:05.574742  manual

パイプラインの実行の詳細を表示する

az pipelines runs show コマンドを使用して、プロジェクト内のパイプライン実行の詳細を表示します。開始するには、「Azure DevOps CLI の概要」を参照してください。

az pipelines runs show --id
                       [--open]
                       [--org]
                       [--project]

パラメーター

id: 必須。パイプライン実行の ID。
open: 省略可能。 Web ブラウザーでビルド結果ページを開きます。
org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。例: --org https://dev.azure.com/MyOrganizationName/.
project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。

例

次のコマンドによって、ID 123 で実行されたパイプラインの詳細が表示され、結果がテーブル形式で返されます。また、Web ブラウザーを開いてビルド結果ページに移動します。

az pipelines runs show --id 122 --open --output table

Run ID    Number      Status     Result     Pipeline ID    Pipeline Name               Source Branch    Queued Time                 Reason
--------  ----------  ---------  ---------  -------------  --------------------------  ---------------  --------------------------  --------
123       20200123.2  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 11:55:56.633450  manual

パイプライン実行にタグを追加する

az pipelines runs tag add コマンドを使用して、プロジェクト内のパイプライン実行にタグを追加します。開始するには、「Azure DevOps CLI の概要」を参照してください。

az pipelines runs tag add --run-id
                          --tags
                          [--org]
                          [--project]

パラメーター

run-id: 必須。パイプライン実行の ID。
tags: 必須。パイプライン実行に追加するタグ (コンマ区切りの値)。
org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。例: --org https://dev.azure.com/MyOrganizationName/.
project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。

例

次のコマンドにより、タグ YAML は ID 123 で実行されるパイプラインに追加され、結果が JSON 形式で返されます。

az pipelines runs tag add --run-id 123 --tags YAML --output json

[
  "YAML"
]

パイプラインの実行タグを一覧表示する

az pipelines runs tag list コマンドを使用して、プロジェクト内のパイプライン実行のタグを一覧表示します。開始するには、「Azure DevOps CLI の概要」を参照してください。

az pipelines runs tag list --run-id
                           [--org]
                           [--project]

パラメーター

run-id: 必須。パイプライン実行の ID。
org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。例: --org https://dev.azure.com/MyOrganizationName/.
project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。

例

次のコマンドにより、ID 123 で実行されるパイプラインのタグが一覧表示され、結果がテーブル形式で返されます。

az pipelines runs tag list --run-id 123 --output table

Tags
------
YAML

パイプライン実行からタグを削除する

az pipelines runs tag delete コマンドを使用して、プロジェクト内のパイプライン実行からタグを削除します。開始するには、「Azure DevOps CLI の概要」を参照してください。

az pipelines runs tag delete --run-id
                             --tag
                             [--org]
                             [--project]

パラメーター

run-id: 必須。パイプライン実行の ID。
tag: 必須。パイプライン実行から削除されるタグ。
org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。例: --org https://dev.azure.com/MyOrganizationName/.
project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成できます。既定として設定されていない場合、または git config を使用して取得された場合は必須です。

例

次のコマンドでは、ID 123 でパイプライン実行から YAML タグを削除します。

az pipelines runs tag delete --run-id 123 --tag YAML

パイプライン実行シーケンス

パイプラインを処理する

エージェントを要求する

Microsoft がホストするエージェントプールの要求

セルフホステッドエージェントプールの要求

ジョブを実行する準備

各ステップを実行する

結果を報告して収集する

状態と条件

タイムアウトと切断

CLI を使用して実行を管理する

前提条件

パイプライン実行を一覧表示する

省略可能なパラメーター

例

パイプラインの実行の詳細を表示する

パラメーター

例

パイプライン実行にタグを追加する

パラメーター

例

パイプラインの実行タグを一覧表示する

パラメーター

例

パイプライン実行からタグを削除する

パラメーター

例

フィードバック

フィードバック

その他のリソース

パイプライン実行シーケンス

パイプラインを処理する

エージェントを要求する

Microsoft がホストするエージェント プールの要求

セルフホステッド エージェント プールの要求

ジョブを実行する準備

各ステップを実行する

結果を報告して収集する

状態と条件

タイムアウトと切断

CLI を使用して実行を管理する

前提条件

パイプライン実行を一覧表示する

省略可能なパラメーター

例

パイプラインの実行の詳細を表示する

パラメーター

例

パイプライン実行にタグを追加する

パラメーター

例

パイプラインの実行タグを一覧表示する

パラメーター

例

パイプライン実行からタグを削除する

パラメーター

例

フィードバック

フィードバック

その他のリソース

Microsoft がホストするエージェントプールの要求

セルフホステッドエージェントプールの要求