fix-ci-failures

CI の失敗を調査して修正する

このスキルでは、gh CLI を使用して PR 上の CI の失敗を診断し、修正する手順を説明します。ユーザーは PR のブランチをローカルでチェックアウト済みです。

ワークフローの概要

1. 現在のブランチとその PR を特定します
2. CI のステータスを確認し、失敗したチェックを見つけます
3. 失敗したジョブのログをダウンロードします
4. 失敗の内容を抽出して理解します
5. 問題を修正してプッシュします

---

ステップ 1：ブランチと PR を特定する

# Get the current branch name
git branch --show-current

# Find the PR for this branch
gh pr view --json number,title,url,statusCheckRollup

PR が見つからない場合は、ユーザーに PR 番号を指定してもらう必要があります。

---

ステップ 2：CI のステータスを確認する

# List all checks and their status (pass/fail/pending)
gh pr checks --json name,state,link,bucket

# Filter to only failed checks
gh pr checks --json name,state,link,bucket --jq '.[] | select(.bucket == "fail")'

link フィールドには GitHub Actions のジョブの URL が含まれています。URL から実行 IDを取り出します。これは /runs/ の後にある番号です：

https://github.com/microsoft/vscode/actions/runs/<RUN_ID>/job/<JOB_ID>

チェックがまだ IN_PROGRESS の場合は、ログをダウンロードする前に完了するまで待ちます：

gh pr checks --watch --fail-fast

---

ステップ 3：失敗したジョブの詳細を取得する

# List failed jobs in a run (use the run ID from the check link)
gh run view <RUN_ID> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name: .name, id: .databaseId}'

---

ステップ 4：失敗ログをダウンロードする

失敗の種類に応じて、2 つの方法があります。

オプション A：失敗したステップのログを直接表示する

エラーがステップの出力に含まれるビルド／コンパイル／lint の失敗に最適です：

# View only the failed step logs (most useful — shows just the errors)
gh run view <RUN_ID> --job <JOB_ID> --log-failed

重要：--log-failed の実行には、失敗したジョブだけでなく、実行全体の完了が必要です。他のジョブがまだ実行中の場合、このコマンドは処理を待ち続けるか、エラーになります。実行が進行中でも完了済みのジョブのログを取得するには、以下のオプション Cを使用してください。

出力が大きくなることがあります。tail または grep にパイプして対象を絞ります：

# Last 100 lines of failed output
gh run view <RUN_ID> --job <JOB_ID> --log-failed | tail -100

# Search for common error patterns
gh run view <RUN_ID> --job <JOB_ID> --log-failed | grep -E "Error|FAIL|error TS|AssertionError|failing"

オプション B：アーティファクトをダウンロードする

詳細なログ（ターミナルログ、拡張ホストログ、クラッシュダンプ）がアーティファクトとしてアップロードされる統合テストの失敗に最適です：

# List available artifacts for a run
gh run download <RUN_ID> --pattern '*' --dir /dev/null 2>&1 || gh run view <RUN_ID> --json jobs --jq '.jobs[].name'

# Download log artifacts for a specific failed job
# Artifact naming convention: logs-<platform>-<arch>-<test-type>-<attempt>
# Examples: logs-linux-x64-electron-1, logs-linux-x64-remote-1
gh run download <RUN_ID> -n "logs-linux-x64-electron-1" -D /tmp/ci-logs

# Download crash dumps if available
gh run download <RUN_ID> -n "crash-dump-linux-x64-electron-1" -D /tmp/ci-crashes

ヒント：失敗したチェックに表示されるテストランナー名（例：「Electron / Linux」→ electron、「Remote / Linux」→ remote）とプラットフォームの対応表（「Windows」→ windows-x64、「Linux」→ linux-x64、「macOS」→ macos-arm64）を使って、アーティファクト名を組み立てます。

警告：出力が生成される前にテストランナーがクラッシュした場合（例：Electron のダウンロード失敗）、ログアーティファクトが空になることがあります。その場合は、オプション Cに切り替えてください。

オプション C：API 経由でジョブごとのログをダウンロードする（実行中でも使用可能）

実行がまだ進行中でも、失敗したジョブが完了している場合は、GitHub API を使用してそのジョブのステップログを直接ダウンロードします：

# Save the full job log to a temp file (can be very large — 30k+ lines)
gh api repos/microsoft/vscode/actions/jobs/<JOB_ID>/logs > "$TMPDIR/ci-job-log.txt"

次に、保存したファイルを検索します。まず ##[error] を検索してください。これは、ステップが失敗した正確な行を示す GitHub Actions のエラー注釈です：

# Step 1: Find the error annotation (fastest path to the failure)
grep -n '##\[error\]' "$TMPDIR/ci-job-log.txt"

# Step 2: Read context around the error (e.g., if error is on line 34371, read 200 lines before it)
sed -n '34171,34371p' "$TMPDIR/ci-job-log.txt"

##[error] だけでは十分な情報が得られない場合は、より広いパターンで検索します：

# Find test failures, exceptions, and crash indicators
grep -n -E 'HTTPError|ECONNRESET|ETIMEDOUT|502|exit code|Process completed|node:internal|triggerUncaughtException' "$TMPDIR/ci-job-log.txt" | head -20

ファイルに保存する理由：ジョブログ全体に対する API の応答は、3 万行を超えることがあります。ツールの出力は切り詰められるため、必ず最初にファイルへリダイレクトしてから検索してください。

VS Code のログアーティファクトの構成

ダウンロードしたログアーティファクトには、通常、次のファイルが含まれています：

logs-linux-x64-electron-1/
  main.log              # Main process log
  terminal.log          # Terminal/pty host log (key for run_in_terminal issues)
  window1/
    renderer.log        # Renderer process log
    exthost/
      exthost.log       # Extension host log (key for extension test failures)

最初に確認する主なファイル：

• テストのアサーション失敗：拡張ホストの出力とスタックトレースについて、exthost.log を確認します
• ターミナル／サンドボックスの問題：リライターのパイプライン、シェル統合、戦略のログについて、terminal.log を確認します
• クラッシュ／ハング：main.log を確認し、クラッシュダンプのアーティファクトを探します

---

ステップ 5：失敗の内容を抽出する

テストの失敗の場合

失敗したステップのログから、テストランナーの出力を探します：

# Find failing test names and assertion messages
gh run view <RUN_ID> --job <JOB_ID> --log-failed | grep -A 5 "failing\|AssertionError\|Expected\|Unexpected"

VS Code の CI でよく見られるパターン：

• AssertionError [ERR_ASSERTION]：テストのアサーションが失敗しています。期待値と実際の値を確認します
• Extension host test runner exit code: 1：統合テストスイートで失敗が発生しています
• Command produced no output：シェル統合でコマンドの出力を取得できていない可能性があります（terminal.log を参照してください）
• Error: Timeout：テストがタイムアウトしています。ハングまたは CI マシンの遅延が原因の可能性があります

ビルドの失敗の場合

# Find TypeScript compilation errors
gh run view <RUN_ID> --job <JOB_ID> --log-failed | grep "error TS"

# Find hygiene/lint errors
gh run view <RUN_ID> --job <JOB_ID> --log-failed | grep -E "eslint|stylelint|hygiene"

---

ステップ 6：失敗が PR に関連しているか判断する

修正する前に、失敗の原因が PR の変更なのか、既存の問題やインフラの問題なのかを判断します。

1. 失敗したテストが変更したコードに含まれているか確認します — テストがまったく関係のない領域にある場合、テストが不安定な可能性があります
2. テスト名を確認します — 変更した機能領域に関連していますか？
3. 失敗時の出力を確認します — PR で変更したコードパスが参照されていますか？
4. 同じテストが main でも失敗するか確認します — 最近の main のコミットでも同一の失敗がある場合、既存の問題です
5. インフラの問題がないか確認します — ネットワークのタイムアウト、npm レジストリのエラー、マシンレベルの問題は、コード変更が原因ではありません

# Check recent runs on main for the same workflow
gh run list --branch main --workflow pr-linux-test.yml --limit 5 --json databaseId,conclusion,displayTitle

インフラの問題や不安定なテストを見分ける

CI の失敗がすべてコード変更に起因するとは限りません。よくあるインフラの問題は次のとおりです。

ネットワーク／レジストリの問題：

• npm ERR! network、ETIMEDOUT、ECONNRESET、EAI_AGAIN — npm レジストリに接続できません
• error: RPC failed; curl 56、fetch-pack: unexpected disconnect — Git のネットワーク障害です
• Error: unable to get local issuer certificate — TLS／証明書の問題です
• rate limit exceeded — GitHub API のレート制限です
• electron/electron/releases での HTTPError: Request failed with status code 502 — Electron CDN のダウンロード失敗です（実行時に Electron をダウンロードする node.js integration tests のステップでよく発生します）

マシン／環境の問題：

• No space left on device — CI のディスク容量が不足しています
• ENOMEM、JavaScript heap out of memory — CI マシンのメモリが不足しました
• The runner has received a shutdown signal — CI がプリエンプトされたか、タイムアウトしました
• Error: The operation was canceled — GitHub Actions がジョブをキャンセルしました
• Xvfb failed to start — ヘッドレス Linux テスト用のディスプレイサーバーの起動に失敗しました

テストの不安定さ（インフラの問題ではありませんが、あなたの責任でもありません）：

• 通常は成功するテストのタイムアウト — CI マシンの動作が遅い可能性があります
• 非同期テストの競合状態
• シェル統合で終了コードが報告されない（terminal.log の exitCode: undefined を確認してください）

インフラの問題が発生した場合の対応：

1. コードは変更しないでください — この失敗は PR が原因ではありません
2. GitHub UI または次のコマンドで、失敗したジョブを再実行します。

   gh run rerun <RUN_ID> --failed
   

3. 再実行しても失敗が続く場合は、main でも問題が発生しているか確認します。

   gh run list --branch main --limit 10 --json databaseId,conclusion,displayTitle
   

4. main でも問題が発生している場合は、修正されるまで待ちます — PR が原因ではありません

---

ステップ 7：修正して繰り返す

1. ローカルで修正します
2. コンパイルを確認します：VS Code - Build タスクを確認するか、npm run typecheck-client を実行します
3. 関連する単体テストをローカルで実行します：./scripts/test.sh --grep "<pattern>"
4. コミットしてプッシュします。

   git add -A
   git commit -m "fix: <description>"
   git push
   

5. 再度 CI を確認します。

   gh pr checks --watch --fail-fast
   

---

クイックリファレンス

タスク	コマンド
ブランチの PR を検索	gh pr view --json number,url
すべてのチェックを一覧表示	gh pr checks --json name,state,bucket
失敗したチェックのみ一覧表示	gh pr checks --json name,state,link,bucket --jq '.[] | select(.bucket == "fail")'
完了するまでチェックを監視	gh pr checks --watch --fail-fast
実行中の失敗したジョブ	gh run view <RUN_ID> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, id: .databaseId}'
失敗したステップのログを表示	gh run view <RUN_ID> --job <JOB_ID> --log-failed（実行全体の完了後に使用できます）
API 経由でジョブログをダウンロード	gh api repos/microsoft/vscode/actions/jobs/<JOB_ID>/logs > "$TMPDIR/ci-job-log.txt"（実行中でも利用できます）
ログ内のエラー行を検索	grep -n '##\[error\]' "$TMPDIR/ci-job-log.txt"
ログのアーティファクトをダウンロード	gh run download <RUN_ID> -n "<artifact-name>" -D /tmp/ci-logs
失敗したジョブを再実行	gh run rerun <RUN_ID> --failed
最近の main の実行を一覧表示	gh run list --branch main --workflow <workflow>.yml --limit 5