# 「ずっと skipped だった CI ジョブ」を掘り起こして緑にする手順 ## これは何の指示書か CI が長期間 red なリポジトリを引き継いだとき、**赤いジョブを直すだけでは終わらない**。 `needs:` で後ろに繋がったジョブは前段が落ちている間ずっと `skipped` になり、 `skipped` は PR のチェック欄で**赤くも緑にも見えない**ため、そのジョブ自体の欠陥が何ヶ月も隠れる。 この指示書は「前段を直す → 隠れていた次の障害が出る」を**想定内として連続で回し切る**ための手順書。 GitHub Actions + Node/pnpm + Next.js + Playwright を例にするが、考え方は CI 一般に効く。 --- ## 前提 - リポジトリの CI が赤い、または「テストが通っているはずなのに壊れたコードがマージされた」状態 - `gh` CLI が認証済み（`gh auth status` で確認） - 対象 PR / ブランチが分かっている --- ## 手順 0: 着手前に「そのジョブは過去に一度でも成功したか」を確認する **最重要。これをやらないと「E2E は通っている」という誤った前提で作業してしまう。** ```bash REPO=/ JOB_PATTERN='E2E' # 疑っているジョブ名の一部 for r in $(gh run list --repo "$REPO" --branch main --limit 10 --json databaseId -q '.[].databaseId'); do gh run view "$r" --repo "$REPO" --json jobs \ -q ".jobs[] | select(.name|test(\"$JOB_PATTERN\")) | .conclusion" done ``` 出力が全部 `skipped` なら、**そのジョブは「通っている」のではなく「一度も検証されていない」**。 `success` が1つも無いジョブは、これから初めて動く＝落ちる前提で計画する。 --- ## 手順 1: 失敗ログの「本当のエラー行」だけを抜く `--log-failed` は Git の内部コマンドや Node 廃止警告で数百行に膨れる。ノイズを落とす: ```bash gh run view --repo "$REPO" --log-failed \ | grep -viE "node 20|node\.js 20|post job|orphan|git config|git submodule|git version|safe\.directory|extraheader|Pruning|overriding HOME|##\[group|##\[endgroup" \ | tail -40 ``` エラーだけ拾いたい場合: ```bash gh run view --repo "$REPO" --log-failed \ | grep -iE "error:|refused|timeout|failed to|ELIFECYCLE" | head -20 ``` --- ## 手順 2: よくある「前段を8秒で殺す」設定バグ ### 2-1. パッケージマネージャのバージョン二重指定 `pnpm/action-setup` の `with.version` と `package.json` の `packageManager` を**両方**書くと即死する: ``` Error: Multiple versions of pnpm specified: - version 9 in the GitHub Action config with the key "version" - version pnpm@9.15.0 in the package.json with the key "packageManager" ``` **直し方**: `packageManager` を唯一の情報源にし、workflow 側の `version:` を消す。 ```yaml # Before - uses: pnpm/action-setup@v4 with: version: 9 # After - uses: pnpm/action-setup@v4 ``` `corepack` や `actions/setup-node` の `cache: 'pnpm'` と併用する場合も同じ。 > このステップが死ぬと**それ以降の全ステップが飛ぶ**ので、 > lint も typecheck も build も「一度も実行されていない」状態になる。 --- ## 手順 3: `next build` がビルド時に DB へ繋ぎに行って落ちる ### 症状 ``` Error occurred prerendering page "/admin/audit" [AggregateError: ] { code: 'ECONNREFUSED' } Export encountered an error on /(admin)/admin/audit/page, exiting the build. ``` ### 原因 サーバコンポーネントで DB を参照しているページに動的レンダリング宣言が無く、 Next.js が**ビルド時に静的プリレンダーしようとして実 DB へ接続する**。 ホスティング側（Vercel 等）は本番 env があるため成功し、**CI だけが落ちる**ので気付きにくい。 ### 直し方（重要: ページ個別に付けない） **ルートグループの `layout.tsx` に置く。配下の全ページに効くので付け漏れが出ない。** ```ts // app/(admin)/layout.tsx export const dynamic = 'force-dynamic'; ``` 認証必須のルートグループすべて（`(admin)` `(member)` 等）とルート直下の `app/page.tsx` に入れる。 これらは元々ユーザーごと・常に最新であるべき画面なので、静的化しない方が意味的にも正しい。 ### 検出コマンド ```bash for f in $(find app -name "page.tsx"); do grep -qE "from '@/db/client'|await db\." "$f" && \ printf "%-55s dynamic=%s\n" "$f" "$(grep -c 'export const dynamic' "$f")" done ``` > **注意**: この grep は「ヘルパー経由で間接的に DB を触るページ」を取りこぼす。 > 一覧に頼らず、下の手順4で**CI と同じ env でローカル build を回して実際に落ちる場所を出す**こと。 --- ## 手順 4: CI をローカルで再現する（往復を減らす最大の武器） workflow の `env:` をそのままシェルに並べてローカル実行する。CI を1回回すより桁違いに速い。 ```bash <認証シークレット環境変数>=<ダミー値> \ <アプリURL環境変数>=http://localhost:3000 \ =<ダミー値> \ <他のダミー env> \ pnpm build 2>&1 | tail -25 ``` `pnpm format:check` / `pnpm lint` / `pnpm typecheck` も先に回して、CI を1往復で済ませる。 ### 偽陽性に注意（Windows） `core.autocrlf=true` の環境では、`git checkout` したファイルが CRLF になり Prettier（既定 `endOfLine: lf`）が「未整形」と報告する。 `git diff --stat` が空なら**ローカル表現だけの差**で、LF でチェックアウトする CI では通る。整形し直さないこと。 恒久対策は `.gitattributes` に `* text=auto eol=lf`。 --- ## 手順 5: Playwright E2E が CI で「一度も動いていない」典型 ### 症状 全 spec が `net::ERR_CONNECTION_REFUSED at http://localhost:3000/...` で落ちる。 ### 原因 ```ts // playwright.config.ts —— これが犯人 webServer: process.env.CI ? undefined // ← CI ではサーバを起動しない : { command: 'pnpm dev', url: 'http://localhost:3000' }, ``` `CI` のときサーバ起動を無効にしているのに、**workflow 側でもサーバを起動していない**。 「CI では外部で起動する前提」で書かれた設定が、起動ステップの実装忘れとセットで放置されているパターン。 ### 直し方 ```ts webServer: { command: process.env.CI ? 'pnpm build && pnpm start' : 'pnpm dev', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, timeout: 300_000, // CI ではビルド時間を含むので長めに }, ``` workflow の E2E ステップには**build ジョブと同じダミー env** を渡す（無いとサーバが起動できない）: ```yaml - name: Run E2E run: pnpm test:e2e env: CI: true : <ダミー値> # build と同じ env 一式 ``` --- ## 手順 6: 初回実行で出る「テスト側の欠陥」を直す 一度も走っていないテストは、アプリではなく**テスト自身が壊れている**ことが多い。 ### 典型: `getByRole('alert')` の strict mode violation ``` strict mode violation: getByRole('alert') resolved to 2 elements: 1)
…アプリのエラー表示…
2) ``` Next.js のルートアナウンサーも `role="alert"` を持つ。アプリ側の要素だけに絞る: ```ts const APP_ALERT = '[role="alert"]:not(#__next-route-announcer__)'; await expect(page.locator(APP_ALERT)).toContainText(/…/); ``` **アプリの表示自体は正しい**ケースなので、アプリ側を書き換えないこと。 ### ローカルでブラウザが無くて落ちるのは無視してよい `devices['iPhone 15']` を使う spec は webkit を要求する。 ローカルに未インストールなら `Executable doesn't exist at …webkit-XXXX` で落ちるが、 CI が `playwright install --with-deps chromium webkit` していれば CI では通る。 ローカルの1件失敗を CI の失敗と混同しない。 --- ## 手順 7: 「緑になった」の定義 ```bash gh run watch --repo "$REPO" --compact gh pr checks --repo "$REPO" ``` **前段が緑になった時点では終わっていない。`needs:` の後段が初回実行されて `pass` になるまで見届ける。** そこまで確認して初めて「CI が通った」と報告してよい。 マージ後は配信先の実体も確認する: ```bash curl -s -o /dev/null -w "health=%{http_code}\n" https://<本番ホスト>/api/health curl -s https://<本番ホスト>/<公開ページ> | grep -c "<新機能の目印テキスト>" ``` --- ## つまずきポイントまとめ | 症状 | 真因 | 対処 | |---|---|---| | CI が数秒で死ぬ | パッケージマネージャのバージョン二重指定 | workflow の `version:` を消す | | lint/format が急に大量に落ちる | 前段死亡で長期間走っていなかっただけ | `--write` で一括整形して1コミット | | build だけ CI で落ちる（本番は通る） | DB 参照ページの静的プリレンダー | route group の layout に `force-dynamic` | | E2E 全滅 `ECONNREFUSED` | CI で webServer を起動していない | `webServer` を CI でも有効化＋env を渡す | | ローカルだけ format:check が落ちる | Windows の CRLF | `git diff` が空なら無視。`.gitattributes` で恒久対策 | | `role="alert"` が2件に一致 | フレームワークのアナウンサー要素 | `:not(#__next-route-announcer__)` で絞る | --- ## 作業ログの残し方 1つ直すごとに独立したコミットにし、**何が隠れていたか**をメッセージに書く。 「緑にするための一括修正」にすると、次に同じ罠を踏んだ人が原因を追えない。 ``` ci: のバージョン二重指定を解消して CI を復旧 fix(build): DB 参照ページを静的プリレンダー対象から外す fix(ci): E2E が CI で一度も実行されていなかった問題を修正 ``` ---