GitHub Actions cache 怎麼設才安全：restore-keys 不是可信來源

先理解命中順序#

actions/cache 先找完整的 key，再找 key 的部分匹配；若仍找不到，才依序搜尋 restore-keys。部分匹配有多筆時，會使用最近建立的一筆。

1
- uses: actions/cache@v4
2
  with:
3
    path: ~/.cache/pnpm
4
    key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
5
    restore-keys: |
6
      pnpm-${{ runner.os }}-

這段設定的目標是「lockfile 不變時拿到精確 cache；變了時可暫時還原同平台的較舊依賴下載快取」。它不是「永遠拿到正確的 node_modules」。安裝步驟仍要根據 lockfile 驗證依賴，例如使用你專案既有的 frozen lockfile 安裝方式。

不要把 cache 當成 artifact 或 secret store#

cache 與 artifact 的使用目的不同：cache 用於可重建、但重新取得成本高的資料；artifact 則是用於保存 workflow 產物、供後續 job 或人工查看。兩者都不適合裝 secrets。

GitHub 文件也明確警告：能讀取 cache 的人可能透過 pull request 存取其內容。因此以下資料不應放進 cache path：

• .npmrc、.pypirc、.netrc 或含 token 的設定檔。
• .env、雲端憑證、SSH key 與暫存 deployment credential。
• 有可能在下一個高權限 job 被直接執行的產物。

即使低信任 workflow 對 default branch cache 是 read-only，還原後的檔案仍應當成不可信資料。快取隔離能降低寫入風險，不會把快取內容變成可直接執行的安全輸入。

低信任事件採 restore-only 更清楚#

fork PR 或其他低信任觸發來源如果只需要加速安裝，使用 restore-only 操作能把意圖寫明：

1
- name: Restore dependency cache
2
  uses: actions/cache/restore@v4
3
  with:
4
    path: ~/.cache/pnpm
5
    key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
6
    restore-keys: |
7
      pnpm-${{ runner.os }}-

這避免 job 嘗試儲存但因權限被拒時留下令人誤解的 warning。真正負責更新 cache 的 trusted workflow，則可以放在預設分支的 push CI。

快取設定檢查表#

1. path 只包含 package manager cache，沒有 secrets 或 build deploy output。
2. 完整 key 包含 OS 與 lockfile hash；有 matrix 時也加入會改變二進位相容性的版本。
3. restore key 由最具體到最寬鬆排序，並接受它只改善速度、不保證內容正確。
4. 還原後仍執行依賴安裝與測試；不要跳過 integrity 驗證。
5. 不可信 PR 與有 secrets 的寫入／部署 workflow 分離。

快取風險和 pull_request_target 的風險都來自信任邊界被混在同一個工作流程；若 workflow 還會 checkout PR 程式碼，請再看 GitHub Actions 的 fork PR checkout 保護。

參考資料：

GitHub Docs：Dependency caching reference

GitHub Docs：Dependency caching concepts