nx-cloud-ci-failure-review

Nx Cloud CI 失敗レビュー

すべての Nx Cloud 読み取りには nx-cloud-api スキルが必要です。このワークフローは読み取り専用です。

失敗したパイプラインを少数の診断グループにまとめます。パイプラインの失敗は、エージェントやプラットフォームがその失敗を引き起こしたことを証明するものではありません。各グループは、証拠が裏付ける範囲でのみ分類してください。

スコープと収集

ユーザーが 1 つ以上の CIPE または run-group のリンクを提示した場合は、フォーカス調査モードを使用します。まずそれらの正確なレコードを取得します。返された run-group、run、task、workflow のリンクをたどります。提示された実行を直接比較します。ユーザーが再発やスコープを求めない限り、広範な時間枠を実行したり、ワークスペース全体のランキングを作成したりしないでください。指定された重大なエラーの後に続くキャンセルは、結果として扱い、独立した根本原因グループにはしないでください。

ユーザーがワークスペースの失敗レビューを求めた場合は、レビューモードを使用します。デフォルトでは過去 24 時間の失敗をレビューします。CIPE と run-group のリストフィルターは createdAt を使用し、失敗時刻ではありません。最大で通常の 6 時間の CI 実行時間をカバーするため、30 時間の作成ウィンドウをクエリします。意図する 24 時間のレビュー期間と 30 時間の作成ウィンドウを明示してください。

statuses=FAILED、statuses=TIMED_OUT、statuses=CANCELED をクエリします（cipes フィルターは終端ステータスのみを受け付けます）。ブランチ、CI コンテキスト、ステータス、エンドポイント、レコード件数を明示してください。ウィンドウを広げる場合や、無関係なリポジトリ／ワークスペースを混在させる場合は、事前に確認してください。

すべての読み取りに nx-cloud-api（npx nx-cloud api）を使用します。cipes、run-groups、run-groups/{runGroupId}、runs、runs/{runId}/tasks、およびリンクされた steps と instances エンドポイントについて、--describe でライブスキーマを確認します。--list-operations でルートを確認します。パブリック API には独立した workflow ルートはありません。返された links をたどって子レコードに到達します。フォーカス調査モードでは、提示された CIPE から開始します。レビューモードでは、失敗した CIPE とそれにリンクされた run group から開始します。ライブで文書化されたフィルターとフィールドのみを使用します。まず 1 つの狭いページを取得し、続行する前に nextCursor を確認します。

次の順序で収集します:

1. 失敗、タイムアウト、キャンセルされた CIPE を、ステータス、タイムスタンプ、ブランチ、CI コンテキストとともに収集します。小さく明示した --pages 値を使用します。nextCursor: null でゼロ終了した後にのみ、ワークスペース全体でグループをランク付けします。それ以外の場合は、データを不完全として報告します。
2. リンクされた run group とその文書化された critical-error フィールド。
3. 選択した各グループの run と終端タスク行。
4. タスクデータでグループを説明できない場合にのみ、workflow と instance のステータス。
5. 代表的なケースについて、関連する最小のタスクまたはインスタンスのログ抜粋。

最大 5 つの狭い詳細リクエストのセマフォを使用します。グループが上位 5 つに入った後にのみログを取得します。CI ログの内容を読む前にユーザーに伝えます。マスク処理されたエラー行のみを引用します。

キャンセルは、その理由とタイミングが別の場所に属することを示すまで、独自のカテゴリとして扱います。そのコンテキストなしに、キャンセルを失敗と呼んではいけません。

グループ化の方法

安定した証拠からグループを構築します。タスク識別子と正規化されたエラーシグネチャを優先してください。タイムスタンプ、GUID、リトライカウンター、一時パス、ランダムポートを正規化します。それ以外の点では類似した 2 つのメッセージを区別するスタックコンテキスト、コマンド、エラーコードは保持してください。

以下のカテゴリは、その証拠が存在する場合にのみ使用してください。

• タスクエラーの繰り返し。
• タスクタイムアウト。
• キャンセル。
• ワークフローまたはエージェントの失敗。
• 不明なパイプライン障害。

グループを ワークフローまたはエージェントの失敗 と呼ぶのは、ワークフロー/インスタンスのステータス、クリティカルエラー、またはエージェントの証拠がそれを裏付けており、かつタスクの失敗ではパイプラインを説明できない場合だけにしてください。タスクログの不在からインフラストラクチャを推測しないでください。

分類の前にパイプライン全体像を突き合わせてください。タスクが SUCCEEDED またはキャッシュヒットを記録していても、メインジョブが成果物のダウンロード、検証、復元の間に失敗することがあります。実行グループの criticalErrorMessage、タスクステータス、キャッシュステータス、ワークフローステータス、およびその後のキャンセルを比較してください。その場合、メインジョブのキャッシュ復元エラーを主要なものとして分類し、キャンセルされた実行をその結果として分類します。

すべてのグループについて、その CIPE 数、実行グループ数、影響を受けたタスク数、最初と最後の発生、ブランチ/コンテキスト、および 1 つまたは 2 つの代表的な ID を記録してください。まず影響を受けたパイプライン数、次に再発、次に文書化されている場合はブロックされた期間で順位付けしてください。

次のアクションのルール

• タスクエラーの繰り返し: 関連するワークスペースのチェックアウトが存在する場合、記録されたコミットで CODEOWNERS とプロジェクトの所有権メタデータを確認してください。レビューの担当者候補を提案してください。その証拠が存在しない場合は、作業を割り当てたり所有権を主張したりしないでください。
• タスクタイムアウト: 所要時間とリソースの証拠を比較してください。直接的な原因が示されない場合は、焦点を絞った再現またはリソースレポートを要求してください。
• キャンセル: 文書化されたキャンセル元を特定するか、不明なキャンセルとして分離しておいてください。
• ワークフローまたはエージェントの失敗: 証拠が一時的なイベントを裏付ける場合にのみ、リトライまたは監視を行ってください。それ以外の場合は、名前が挙げられたワークフロー/エージェント資産を調査してください。
• 不明: ケースを切り分けられる最小のログまたは実行の詳細を要求してください。

明示的な承認なしに、コード、ワークフロー、割り当ての変更を行わないでください。

レポート形式

# Failed CI review

## Scope

- Window: …
- Data: …

## Failure groups

### 1. <evidence-level category> — <short signature>

- **Confirmed facts:** affected CIPEs/runs/tasks; representative IDs; log excerpt.
- **Assessment:** **Confirmed** / **Likely** / **Needs diagnostic run** — …
- **Impact:** …
- **Highest-leverage next action:** …

## Unclassified or incomplete data

- …

レビューレポートは 5 グループまでに制限してください。フォーカス調査モードでは、提供された実行が同じ正規化されたシグネチャを持つ場合、それらを 1 つの比較として報告してください。各所見を、可能な場合は正確な CIPE、実行グループ、実行、タスクにリンクしてください。ページネーション、欠落した資産、または欠落したコンテキストが結論に影響する場合は、データの制限を記載してください。