パイプラインの実行をトラブルシューティングする

2025-04-30

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

パイプラインの実行が完了しない場合は、パイプライン実行の概要ページの診断情報とログを使用して問題のトラブルシューティングを行います。このガイドでは、ログ、エラー分析ツール、および一般的なトラブルシューティング手法を使用してパイプラインエラーを診断する手順について説明します。根本原因を特定し、パイプラインをスムーズに実行し続けるソリューションを実装する方法について説明します。

ログを表示する

エラーメッセージを選択して、完了しなかったタスクのログを表示します。

パイプライン実行の概要ページのタスクエラーメッセージのスクリーンショット。

ログページには、選択したエラーが表示されます。この例では、 cmd-line タスクにエラーが発生し、 echo コマンドが echとして入力されます。

タスクの生ログを表示するには、[ 未加工ログの表示] を選択し、[ 検索] を使用してログを検索できます。

Azure DevOps のログビューオプションのスクリーンショット。

失敗したタスクのログをスキャンして、タスクが失敗した理由に関するエラー情報と手掛かりを確認します。既定では、詳細でないログがパイプライン実行によって生成されます。既定のログに問題の原因が示されていない場合は、詳細ログを構成することで詳細情報を取得できます。

エラー分析ページ

トラブルシューティングの支援は、 エラー分析 ページを使用して入手できます。エラー情報行の上にマウスを移動し、[ 分析の表示 ] アイコンを選択します。

パイプラインの実行に使用されるエージェントの詳細を表示するには、セルフホステッドエージェントのエージェントの表示 (または Microsoft ホステッド エージェントのホストエージェントイメージ について) を選択し、 ログを表示 してパイプラインの実行ログを表示します。

Azure DevOps ポータルのエラー分析ページのスクリーンショット。

[ 実行時の詳細 ] の下にあるタスクの名前を選択して、タスクに関する情報を表示します。

エラー分析のタスクの詳細のスクリーンショット。

この例では、ValueのScriptにエラーがあることがわかります。タスクのドキュメントを表示するには、[ このタスクについて ] を選択します。

パイプラインの実行の概要ページまたはログの参照から問題が明らかでない場合は、次の一般的な問題セクションを確認し、詳細な診断情報を含む完全なログのダウンロードに関する情報については、パイプラインの問題を診断するためのログの確認を参照してください。

一般的な問題

この実行を続行するには、このパイプラインにリソースにアクセスするためのアクセス許可が必要です
ジョブのタイムアウト
コードのダウンロードに関する問題
MSBUILD などのコマンドラインステップの実行中に、パイプラインが失敗しています
使用中のファイルまたはフォルダーのエラー
断続的または一貫性のない MSBuild エラー
プロセスが応答を停止する
複数のプラットフォームの行末
' (単一引用符) が追加された変数
サービス接続に関連する問題
パイプラインがエージェントからの聞き取りを停止しました

失敗したパイプライン実行のタスク分析情報

Azure DevOps には、 失敗したパイプライン実行の Task Insights 設定が用意されています。この設定を有効にすると、レポートを表示するためのリンクを含むビルドエラーのポップアップ通知が表示されます。

タスク分析情報メトリックのスクリーンショット。

この設定を構成するには、プレビュー機能に移動し、 失敗したパイプライン実行の Task Insights を見つけて、目的の設定を選択します。

失敗したパイプライン実行設定のタスク分析情報のスクリーンショット。

失敗した実行の通知

Azure DevOps には、失敗したパイプラインの実行に関する組み込み通知が含まれています。通知を有効にするには:

プロジェクトの設定>Notifications に移動します。
受信する通知の種類を選択します。パイプラインの実行が失敗するたびに通知を受け取る場合は、[ ビルドの失敗] を選択します。

プロジェクト設定の通知のスクリーンショット。

この実行を続行するには、このパイプラインにリソースにアクセスするためのアクセス許可が必要です

パイプラインが起動していないように見える場合、または This pipeline needs permission to access a resource before this run can continue などのエラーメッセージが表示される場合は、サービス接続やエージェントプールなど、リソースによる承認の実行をパイプラインが待機しているかどうかを確認します。

パイプラインに移動し、手動で実行を開始します。
このパイプラインには、 この実行を続行する前にリソースにアクセスするためのアクセス許可が必要 です。メッセージの横にある [表示 ] を選択します。
[ 確認待ち ] 画面で [ 許可] を選択し、確認画面でもう一度 [許可 ] を選択します。

このアクションにより、パイプラインがリソースの承認されたユーザーとして明示的に追加されます。

パイプラインを承認してエージェントプールにアクセスするには、2 つの方法があります。

特定のパイプラインを承認する - プールで実行する Azure DevOps プロジェクトの特定のパイプラインを個別に承認します。
オープンアクセスの構成 - プロジェクトレベルでエージェントプールを構成し、そのプロジェクト内のすべてのパイプラインで使用できるようにします。

特定のパイプラインを承認する

This pipeline needs permission to access a resource before this run can continueのようなメッセージが表示されたら、前のセクションの手順に従って、エージェントプールで実行する特定のパイプラインを個別に承認できます。

次の手順を実行して、承認された一覧からパイプラインを手動で追加および削除することもできます。この手順は、Azure DevOps 組織のプロジェクトレベルで実行されます。

Azure DevOps で、 プロジェクト設定、 エージェントプールに移動し、セルフホステッドプールを選択して、[セキュリティ] を選択 します。
+を選択して、承認された一覧にパイプラインを追加します。
承認された一覧からパイプラインを削除するには、[ X(アクセスの取り消し)] を選択します。

オープンアクセスを構成する

一部のリソースでは、新しいパイプライン定義ごとに明示的な承認を必要としないように 、オープンアクセス を構成できます。

オープンアクセスを構成するには、プロジェクト管理者のアクセス許可が必要です。

エージェントプールの オープンアクセス を構成するには:

Azure DevOps で、 プロジェクト設定、 エージェントプールに移動し、セルフホステッドプールを選択して、[セキュリティ] を選択 します。
[ その他のアクション]、[ アクセスを開く] の順に選択して開くアクセスを有効にし、[アクセスを 再度開く ] を選択して確定します。
開いているアクセスを取り消すには、[ アクセス許可の制限] を選択します。

他のリソースの種類でオープンアクセスを使用できるかどうかを確認するには、「Azure Pipelines でのセキュリティの管理」を参照し、オープンアクセスを検索します。

エージェントプールの オープンアクセス の詳細については、「個々のエージェントプールのパイプラインのアクセス許可を設定する」と「パイプラインのアクセス許可」を参照してください。

ジョブのタイムアウト

パイプラインは長い時間実行されることがありますが、その後ジョブのタイムアウトによって失敗することがあります。ジョブのタイムアウトは、使用するエージェントに大きく依存しています。無料の Microsoft ホステッドエージェントの最大タイムアウトは、プライベートリポジトリの場合はジョブあたり 60 分、パブリックリポジトリの場合は 360 分です。

ジョブの最大タイムアウトを増やすには、次のいずれかを選択できます。

使用されているリポジトリに関係なく、すべてのジョブに対して 360 分を提供する Microsoft ホステッドエージェントを購入する
セルフホステッドエージェントを使って、エージェントによるタイムアウトの問題を排除します

ジョブタイムアウトについてさらに学びましょう。

注

Microsoft でホストされているエージェントジョブがタイムアウトしている場合は、パイプラインのタイムアウトがジョブの最大タイムアウトよりも大きい値に設定されていることを確認します。確認するには、「タイムアウト」を参照してください。

チェックアウト手順でパイプラインが失敗する

パイプラインとは異なるプロジェクトにある組織内の Azure Repos Git リポジトリで checkout ステップを使用している場合は、[ ジョブ承認スコープを現在のプロジェクトに制限 する] 設定が無効になっていることを確認するか、スコープ付きビルド ID の手順に従ってパイプラインがリポジトリにアクセスできることを確認します。

ジョブ承認スコープが制限されているためにパイプラインがリポジトリにアクセスできない場合は、エラー Git fetch failed with exit code 128 を受け取り、ログに次のようなエントリが含まれます。 Remote: TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting.

パイプラインが Could not find a project that corresponds with the repositoryですぐに失敗する場合は、 checkout ステップまたはリポジトリリソース宣言でプロジェクトとリポジトリの名前が正しいことを確認します。

Team Foundation バージョン管理 (TFVC) の問題

一部のファイルをダウンロードしていないソースを取得する
Team Foundation プロキシを使用してソースを取得する

一部のファイルをダウンロードしていないソースを取得する

tf get コマンドから、ログに "すべてのファイルが最新の状態です" というメッセージが表示されることがあります。組み込みのサービス ID にソースをダウンロードするアクセス許可があることを確認します。 ID Project Collection Build Service または Project Build Service には、ビルドパイプラインの [全般] タブで選択した承認スコープに応じて、ソースをダウンロードするためのアクセス許可が必要です。バージョン管理 Web UI では、フォルダー階層の任意のレベルでプロジェクトファイルを参照し、セキュリティ設定をチェックできます。

Team Foundation プロキシを使用してソースを取得する

Team Foundation プロキシを介してソースを取得するようにエージェントを構成する最も簡単な方法は、エージェントをユーザーとして実行するための TFVC プロキシサーバーを指す環境変数 TFSPROXY 設定することです。

ウィンドウズ：

    set TFSPROXY=http://tfvcproxy:8081
    setx TFSPROXY=http://tfvcproxy:8081 // If the agent service is running as NETWORKSERVICE or any service account you can't easily set user level environment variable

macOS/Linux の場合:

    export TFSPROXY=http://tfvcproxy:8081

パイプラインが MSBUILD などのコマンドラインステップで失敗しています。

ビルドまたはリリースの失敗が Azure Pipelines 製品の問題 (エージェントまたはタスク) の結果であるかどうかを絞り込むのに役立ちます。ビルドとリリースのエラーは、外部コマンドによっても発生する可能性があります。

失敗したタスクによって実行された正確なコマンドラインをログで確認します。コマンドラインからコマンドをローカルで実行しようとすると、問題が再現される可能性があります。独自のコンピューターからコマンドをローカルで実行したり、マシンにサインインしてサービスアカウントとしてコマンドを実行したりすると便利です。

たとえば、ビルドパイプラインの MSBuild 部分で問題が発生していますか (たとえば、 MSBuild または Visual Studio ビルドタスクを使用していますか? その場合は、同じ引数を使用して、ローカルコンピューターで同じ MSBuild コマンドを実行してみてください。ローカルコンピューターで問題を再現できる場合は、次の手順で MSBuild の問題を調査します。

ファイルレイアウト

ビルドに必要なツール、ライブラリ、ヘッダー、その他の場所は、ホストされているエージェント上でローカルコンピューターとは異なる場合があります。これらのファイルのいずれかが見つからないためにビルドが失敗した場合は、次のスクリプトを使用してエージェントのレイアウトを調べることができます。これは、不足しているファイルを追跡するのに役立つ場合があります。

一時的な場所に新しい YAML パイプラインを作成します (たとえば、トラブルシューティングのために作成された新しいリポジトリ)。記述されているように、スクリプトはパス上のディレクトリを検索します。必要に応じて、 SEARCH_PATH= 行を編集して他の場所を検索することもできます。

# Script for Linux and macOS
pool: { vmImage: ubuntu-latest } # or whatever pool you use
steps:
- checkout: none
- bash: |
    SEARCH_PATH=$PATH  # or any colon-delimited list of paths
    IFS=':' read -r -a PathDirs <<< "$SEARCH_PATH"
    echo "##[debug] Found directories"
    for element in "${PathDirs[@]}"; do
        echo "$element"
    done;
    echo;
    echo;  
    echo "##[debug] Found files"
    for element in "${PathDirs[@]}"; do
        find "$element" -type f
    done

# Script for Windows
pool: { vmImage: windows-2019 } # or whatever pool you use
steps:
- checkout: none
- powershell: |
    $SEARCH_PATH=$Env:Path
    Write-Host "##[debug] Found directories"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Write-Host "$Dir"
    }
    Write-Host ""
    Write-Host ""
    Write-Host "##[debug] Found files"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Get-ChildItem $Dir -File -ErrorAction Continue | ForEach-Object -Process {
        Write-Host $_.FullName
      }
    }

ローカルコマンドプロンプトとエージェントの違い

ローカルコンピューターでコマンドを実行するとき、およびビルドまたはリリースがエージェントで実行されている場合は、いくつかの違いが有効であることに注意してください。エージェントが Linux、macOS、または Windows でサービスとして実行するように構成されている場合、対話型ログオンセッション内では実行されません。対話型のログオンセッションがないと、UI の操作やその他の制限が存在します。

使用中のファイルまたはフォルダーのエラー

File or folder in use エラーは、次のようなエラーメッセージによって示されます。

Access to the path [...] is denied.
The process cannot access the file [...] because it is being used by another process.
Access is denied.
Can't move [...] to [...]

トラブルシューティングの手順:

使用中のファイルとフォルダーを検出する
ウイルス対策の除外
MSBuild と /nodeReuse:false
MSBuild と /maxcpucount:[n]

使用中のファイルとフォルダーを検出する

Windows では、プロセスモニターなどのツールを使用して、特定のディレクトリの下にあるファイルイベントのトレースをキャプチャできます。または、スナップショットの場合は、プロセスエクスプローラーやハンドルなどのツールを使用できます。

ウイルス対策の除外

ウイルス対策ソフトウェアでファイルをスキャンすると、ビルドまたはリリース中にファイルまたはフォルダーの使用中のエラーが発生する可能性があります。エージェントディレクトリにウイルス対策除外を追加し、構成された "作業フォルダー" を追加すると、ウイルス対策ソフトウェアを干渉プロセスとして識別するのに役立ちます。

MSBuild と /nodeReuse:false

ビルド中に MSBuild を呼び出す場合は、必ず引数 /nodeReuse:false (短い形式の /nr:false) を渡してください。それ以外の場合、MSBuild プロセスはビルドの完了後も実行を続けます。プロセスは、後続のビルドの可能性を予期してしばらくの間残ります。

MSBuild のこの機能は、MSBuild プロセスの作業ディレクトリと競合するため、ディレクトリの削除または移動の試行に干渉する可能性があります。

MSBuild タスクと Visual Studio ビルドタスクでは、MSBuild に渡される引数に /nr:false が既に追加されています。ただし、独自のスクリプトから MSBuild を呼び出す場合は、引数を指定する必要があります。

MSBuild と /maxcpucount:[n]

既定では、 MSBuild や Visual Studio Build などのビルドタスクは、 /m スイッチを使用して MSBuild を実行します。場合によっては、複数のプロセスファイルアクセスの問題などの問題が発生する可能性があります。

/m:1引数をビルドタスクに追加して、MSBuild で一度に 1 つのプロセスのみを実行するように強制してみてください。

MSBuild の同時実行プロセス機能を利用すると、ファイルの使用中の問題が発生する可能性があります。引数 /maxcpucount:[n] (短い形式の /m:[n]) を指定しないと、MSBuild は 1 つのプロセスのみを使用するように指示します。 MSBuild または Visual Studio のビルドタスクを使用している場合は、既定で追加される "/m" 引数をオーバーライドするために "/m:1" を指定することが必要になる場合があります。

断続的または一貫性のない MSBuild エラー

断続的または一貫性のない MSBuild エラーが発生している場合は、単一プロセスのみを使用するように MSBuild に指示してみてください。断続的または不整合なエラーは、ターゲット構成が MSBuild の同時実行プロセス機能と互換性がないことを示している可能性があります。 MSBuild と /maxcpucount:[n]を参照してください。

プロセスが応答を停止する

プロセスが応答しなくなる原因とトラブルシューティング手順。

入力の待機中
プロセスダンプ
WiX プロジェクト

入力の待機中

応答を停止するプロセスは、プロセスが入力を待機していることを示している可能性があります。

対話型ログオンセッションのコマンドラインからエージェントを実行すると、プロセスで入力を求めるダイアログが表示されているかどうかを特定するのに役立つ場合があります。

エージェントをサービスとして実行すると、プログラムが入力を求めないようにするのに役立つ場合があります。たとえば、.NET では、プログラムは System.Environment.UserInteractive ブール値に依存して、プロンプトを表示するかどうかを判断する場合があります。エージェントが Windows サービスとして実行されている場合、値は false になります。

プロセスダンプ

プロセスのダンプを分析すると、デッドロックされたプロセスが待機している内容を特定するのに役立ちます。

WiX プロジェクト

カスタム MSBuild ロガーが有効になっているときに WiX プロジェクトをビルドすると、出力ストリームで待機中に WiX がデッドロックする可能性があります。 MSBuild 引数を追加 /p:RunWixToolsOutOfProc=true 問題を回避できます。

複数のプラットフォームの行末

複数のプラットフォームでパイプラインを実行すると、行末が異なる問題が発生することがあります。歴史的に、Linux と macOS では改行 (LF) 文字が使用され、Windows では復帰 (CR) と改行 (LF) からなる CRLF が使用されました。 Git は、リポジトリの LF で行を自動的に終了し、Windows 上の作業ディレクトリの CRLF で行を終了することで、違いを補おうとします。

ほとんどの Windows ツールは LF のみの終わりで問題ありません。この自動動作により、解決するよりも多くの問題が発生する可能性があります。行末に基づいて問題が発生した場合は、どこでも LF を優先するように Git を構成することをお勧めします。これを行うには、リポジトリのルートに .gitattributes ファイルを追加します。そのファイルに、次の行を追加します。

* text eol=lf

' (単一引用符) が追加された変数

##vso コマンドを使用して変数を設定する Bash スクリプトがパイプラインに含まれている場合は、設定した変数の値に別の'が追加されることがあります。これは、set -x とのやり取りが原因で発生します。解決策は、変数を設定する前に set -x を一時的に無効にすることです。これを行うための Bash 構文は set +x です。

set +x
echo ##vso[task.setvariable variable=MY_VAR]my_value
set -x

なぜこのようになるのですか?

多くの Bash スクリプトには、デバッグを支援する set -x コマンドが含まれています。 Bash は、実行されたコマンドを正確にトレースし、stdout にエコーします。これにより、エージェントに ##vso コマンドが 2 回表示され、2 回目は Bash によって ' 文字が末尾に追加されます。

たとえば、次のパイプラインについて考えてみましょう。

steps:
- bash: |
    set -x
    echo ##vso[task.setvariable variable=MY_VAR]my_value

stdout では、エージェントには次の 2 つの行が表示されます。

##vso[task.setvariable variable=MY_VAR]my_value
+ echo '##vso[task.setvariable variable=MY_VAR]my_value'

エージェントが最初の行を確認すると、 MY_VAR は正しい値 "my_value" に設定されます。ただし、2 行目が表示されると、エージェントは行の末尾まですべてを処理します。 MY_VAR が "my_value"に設定されています。

スクリプトの実行時に Python アプリケーション用のライブラリがインストールされない

Python アプリケーションがデプロイされると、場合によっては CI/CD パイプラインが実行され、コードが正常にデプロイされますが、すべての依存関係ライブラリのインストールを担当する requirements.txt ファイルは実行されません。

依存関係をインストールするには、App Service デプロイタスクでデプロイ後スクリプトを使用します。次の例は、デプロイ後スクリプトで使用する必要があるコマンドを示しています。シナリオのスクリプトを更新できます。

D:\home\python364x64\python.exe -m pip install -r requirements.txt

サービス接続に関連する問題のトラブルシューティングについては、「サービス接続のトラブルシューティング」を参照してください。認証にワークロード ID を使用してサービス接続を具体的にトラブルシューティングするには、「ワークロード ID サービス接続のトラブルシューティング」を参照してください。

パイプラインがエージェントからの聞き取りを停止しました

パイプラインが We stopped hearing from agent <agent name>. Verify the agent machine is running and has a healthy network connection.などのメッセージで失敗した場合は、エージェントのリソース使用率を調べて、エージェントマシンがリソース不足かどうかを確認します。 Sprint 228 以降、Azure Pipelines ログには各ステップのリソース使用率メトリックが含まれています。

Azure DevOps Services を使用する場合は、詳細ログを有効にすることで、ディスク使用量、メモリ使用量、CPU 使用率など、ログ内のリソース使用率を確認できます。パイプラインが完了したら、各ステップのエントリをAgent environment resourcesします。

2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23%

追加のリソース使用率ログのキャプチャについては、「リソース使用率の詳細のキャプチャ」を参照してください。

Storage Explorer を有効にして、.cssや .js などの静的コンテンツを Azure DevOps から Azure Pipelines から静的 Web サイトにデプロイする

このシナリオでは、 Azure ファイルコピータスクを使用して、Web サイトにコンテンツをアップロードできます。コンテンツのアップロードに関するページで説明されているツールを使用して、Web コンテナーにコンテンツをアップロードできます。

次のステップ

ログを確認して、追加の診断ツールを見つけ出します。