GitHub Actions のキャッシュが復元されない

要約

GitHub Actions の cache が復元されない原因は、key 不一致、ブランチ間参照ルール、容量上限（既定 10 GB）超過、7 日間未参照での evict の 4 系統に集約される。
Actions ログの Cache not found for input keys: 行に表示される実際の検索 key と、Settings → Actions → Caches のリポジトリ cache 一覧を突き合わせて切り分ける。

実行例

GitHub の ubuntu-latest ランナーで key-A として保存したキャッシュを key-B で復元すると、restore-keys が無い場合は「Cache not found for input keys」と出て何も戻らず、cache-hit も matched-key も空のままになる。
restore-keys に共通の prefix を足すと key-A が前方一致で拾われて中身が戻るが、完全一致ではないので cache-hit は false と出る。

$ cat lab-cache/data.txt
payload 2026-09-21T02:27:49Z

Run actions/cache/save@v4
with:
  path: lab-cache
  key: lab-35554254512-key-A
Cache saved with key: lab-35554254512-key-A

Run actions/cache/restore@v4
with:
  path: lab-cache
  key: lab-35554254512-key-B
Cache not found for input keys: lab-35554254512-key-B

$ echo "cache-hit=${{ steps.miss.outputs.cache-hit }}"
cache-hit=
$ echo "matched-key=${{ steps.miss.outputs.cache-matched-key }}"
matched-key=

Run actions/cache/restore@v4
with:
  path: lab-cache
  key: lab-35554254512-key-B
  restore-keys: lab-35554254512-
Cache hit for restore-key: lab-35554254512-key-A
Received 281 of 281 (100.0%), 0.0 MBs/sec
Cache Size: ~0 MB (281 B)
Cache restored successfully
Cache restored from key: lab-35554254512-key-A

$ echo "cache-hit=${{ steps.fallback.outputs.cache-hit }}"
cache-hit=false
$ echo "matched-key=${{ steps.fallback.outputs.cache-matched-key }}"
matched-key=lab-35554254512-key-A
$ cat lab-cache/data.txt
payload 2026-09-21T02:27:49Z

— 2026-09-21 時点の出力

よくある原因

1. key 不一致: key に ${{ github.sha }} のように毎回変わる値を入れていると毎回 miss する。hashFiles のような決定的な式に変える必要がある。
2. restore-keys 未設定: 完全一致しなくても部分一致で復元したいなら restore-keys の prefix リストが必須。
   これが無いと miss し空状態でジョブが始まる。
3. ブランチ参照ルール: PR の topic ブランチから参照できる cache は、自身のブランチで保存されたものと base / default ブランチで保存されたものに限られる。
   別 PR の cache は読めない仕様。
4. 容量上限: 1 リポジトリの cache 合計は既定で 10 GB。
   超えると最終アクセスの古い cache から自動削除される。
   上限はリポジトリ管理者などが引き上げられるが、既定を超える分は課金対象になる。node_modules を丸ごと cache していると簡単に到達する。
5. 7 日間 evict: 7 日間アクセスの無い cache は自動削除される。
   長期間動かないリポジトリで起きやすい。

解決策

1. key を決定的にする

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-
      npm-

Caching dependencies to speed up workflows（新しいタブで開く）↗ のとおり、hashFiles で lockfile のハッシュを取るのが定番。restore-keys の段階フォールバックで同 OS の任意 npm cache を拾える。

2. ブランチ間参照を理解する

PR ブランチでビルドした cache は、main ブランチへマージするまで他 PR からは見えない。
default ブランチで cache を温めておき、PR からは base 経由で参照する設計にすれば cache miss を減らせる。

3. cache を整理する

Settings → Actions → Caches で個別 key を削除できる。
あるいは GitHub CLI の gh cache list で一覧し、gh cache delete <key>（--all で全削除）で整理する。
以前の拡張機能 gh actions-cache は 2024 年 10 月にアーカイブされ、機能は gh cache に統合された。node_modules を直接 cache せず、パッケージマネージャの global store（~/.npm / ~/.pnpm-store）だけを cache すれば容量を抑えられる。

4. evict を防ぐ

on:
  schedule:
    - cron: "0 3 * * *"   # 毎日 03:00 UTC

短時間のジョブで cache を毎日 restore + save するワークフローを回しておくと、7 日 evict を回避できる。