# ダッシュボードが「artifact が見つからない」で真っ赤になるのを塞ぐ GitHub Actions が作った成果物（artifact）を別のアプリから `gh run download` で取ってきて画面に出す構成は、 ある日突然 `no valid artifacts found to download` で落ちて、パネルが赤いエラーだけになる。 このドキュメントは、その真因と、二度と赤くしないための直し方を扱う。 ## 症状 ダッシュボードのパネルに、データの代わりにこれが出る。 ``` 取得失敗: gh failed (1): no valid artifacts found to download ``` workflow は緑（成功）で、GitHub の画面上は何も壊れていないように見える。それなのに取得だけが落ちる。 ## 真因: 「成功した run」と「成果物がある run」は別物 多くの実装は取得元をこう選んでいる。 ```js // ありがちな実装 — 壊れる const runs = await gh(`run list --workflow= --status=success --limit 1 --json databaseId`); const runId = runs[0].databaseId; await gh(`run download ${runId} --name --dir <保存先>`); ``` これは「**成功 run は必ず成果物を持っている**」という前提に立っている。この前提は次の場合に崩れる。 1. **preflight で早期 skip する workflow** 1日に複数回走るスケジュール実行で、「今日はもう成功しているから処理不要」と判定して早期 return する 設計はよくある。この run は失敗ではないので `conclusion: success` のまま残るが、 本処理を通っていないので **artifact をアップロードしていない**。 2. **artifact の保持期限切れ**（既定90日、リポジトリ設定で短縮されていることがある）。 run のメタデータは残るが artifact だけ消える。 3. **matrix / 条件付き job** で、その run では artifact を作る job が走らなかった。 どれも run のステータスだけ見ていると区別できない。実測すると一目でわかる。 ```bash # 「最新の成功 run」の artifact を数える gh api repos///actions/runs/<最新の成功runId>/artifacts --jq '.total_count' # → 0 ← これが真因。1つ前の run には入っている ``` ## 直し方1: artifact の実在を確認してから採用する 1件目で決め打ちせず、成功 run を新しい順に走査して「artifact を実際に持っている run」を選ぶ。 ```js const MAX_SCAN = 20; // 走査する成功 run の上限 async function runHasArtifacts(runId) { const json = await gh( `api repos///actions/runs/${runId}/artifacts --jq '.total_count'` ); return Number(json.trim()) > 0; } async function pickRunWithArtifacts() { const runs = await gh( `run list --workflow= --status=success ` + `--limit ${MAX_SCAN} --json databaseId,createdAt,event` ); for (const run of runs) { // 新しい順 if (await runHasArtifacts(run.databaseId)) return run; } return null; // 20件見て無ければ諦める } ``` `--limit` は控えめで良い。走査は run 1件につき API 1回なので、20件でもレート制限には遠い。 「保持期限切れが常態化している」ようなリポジトリでは、そもそも上流を直す方が先。 ## 直し方2: 取れなかった時こそ画面を殺さない（こちらが本命） 直し方1 は「artifact がある run を見つけられる場合」の対策でしかない。 上流のジョブが止まっている・全部期限切れ、という日は必ず来る。そこで**最後に成功した内容をディスクに 保存しておき、取得に失敗したらそれを出す**。 ```js const CACHE = '.cache/<機能名>-last-success.json'; async function getLatest({ force = false } = {}) { try { const data = await fetchFromArtifact(); // 直し方1 を使う fs.mkdirSync(path.dirname(CACHE), { recursive: true }); fs.writeFileSync(CACHE, JSON.stringify({ data, savedAt: new Date().toISOString() })); return { ...data, _stale: false, _staleError: null }; } catch (error) { if (fs.existsSync(CACHE)) { const cached = JSON.parse(fs.readFileSync(CACHE, 'utf8')); return { ...cached.data, _stale: true, _staleAt: cached.savedAt, _staleError: String(error) }; } throw error; // 初回だけは本当に出すものが無い } } ``` 画面側は `_stale` を見て**エラー表示ではなく警告バナー付きの実データ**にする。 ```jsx {data._stale && (
最新の取得に失敗したため過去データを表示中（最終更新: {formatDate(data._staleAt)}）
)} ``` **なぜこれが本命か**: データが5日古いことより、画面が真っ赤で**何も読めない**ことの方が害が大きい。 週次レポートのような更新頻度の低いデータなら、多少古くても判断には十分使える。 「取得できないなら何も出さない」は一見誠実だが、運用上は単なる機能停止になる。 キャッシュファイルは `.gitignore` に入れること（`.cache` ごと除外でよい）。 ## やってはいけない直し方 - **`--limit` を増やすだけ**: 走査件数を増やしても、実在確認をしなければ結局 artifact 無しの run を掴む。 - **エラーを握り潰して空を返す**: 画面は静かになるが、上流が止まっていることに誰も気づけなくなる。 `_stale` を必ず画面に出し、いつのデータかを明示する。 - **workflow 側の preflight skip を消す**: 毎回フル実行に戻すと実行時間と課金が増える。 skip 自体は正しい設計なので、取得側を賢くする。 ## 検証（ここまでやって「直った」と言う） ステータスコードや単体テストだけでは不十分で、**人が実際に見る画面**まで確認する。 1. 修正後の取得関数を直接実行し、artifact 無しの run をスキップして正しい run を採用することを確認する。 2. 常駐プロセスが**修正後のコードで動いているか**を確認する。 ここが一番よく抜ける — 開発サーバで通っても、利用者が見ているのは何日も前に起動した常駐プロセスである。 ```bash # そのポートを掴んでいるプロセスの起動時刻 < 修正のコミット時刻 なら古いコードで動いている # (Windows) powershell -NoProfile -Command "Get-NetTCPConnection -LocalPort | Select-Object OwningProcess" powershell -NoProfile -Command "Get-Process -Id | Select-Object Id,StartTime" # (Linux/macOS) lsof -ti tcp: | xargs ps -o pid,lstart,command -p ``` 古ければ再起動してから次へ進む。 3. **実ブラウザで描画テキストを取り、エラー文字列が消えたことを確認する**。 クライアント描画のフレームワークでは `curl` の HTML に本文が出ないので、ヘッドレスブラウザを使う。 ```js const panel = page.locator('<パネルのセレクタ>').filter({ hasText: '<パネル見出し>' }).first(); await panel.waitFor({ state: 'visible' }); const text = await panel.innerText(); console.log('HAS_ERROR', text.includes('取得失敗') || text.includes('no valid artifacts')); await panel.screenshot({ path: '<保存先>.png' }); ``` スクリーンショットまで取れば、「直ったはず」ではなく「直っている」と言える。 ## 応用先 同じ「成功 = 成果物あり」の思い込みは、次の場所にも同型で潜んでいる。 - 最新のリリース資材を取りに行く処理（draft/prerelease を弾いていない） - 最新のビルド成果物をデプロイする処理（キャッシュヒットで成果物を作らなかった run を掴む） - 最新のバックアップを復元する処理（0 バイトのファイルを「存在する」と判定する） いずれも**「ステータス」ではなく「実際に欲しいものが入っているか」で選ぶ**、 **取れなかった時に直前の成功を出す**、の2点で同じように塞げる。 ---