Actions lockfile 正式推出:綠色檢查代表的證據並不相同

Dev
瀏覽 2

PR 裡的 uses 版本看起來沒變,背後執行的程式碼卻可能變化,因為標籤可以移到另一個提交。GitHub 在 10 月 28 日宣布 workflow lockfile 正式推出。預覽版介紹的固定機制仍然適用,接下來值得關注的是每項檢查究竟證明了什麼。

保留易讀參照,執行記錄的提交

.github/workflows/actions.lock 將 action 參照與執行提交連結起來,由 gh actions-lock 產生,支援 Free、Team、GitHub Enterprise Cloud 及其資料落地環境。可以逐個工作流程採用。應把產生的檔案和工作流程修改一起審查,而不是手動拼裝 lockfile。

假設 demo/build@v1 起初指向 A,後來移到 B。只解析參照,下次執行就可能選中不同程式碼;lockfile 選擇記錄的提交。下圖是自行製作的假想範例,不是真實儲存庫執行紀錄。若該提交已無法從記錄的上游標籤或分支到達,執行時仍可能拒絕它。

自行製作的假想參照範例:移動的 v1 與記錄的提交對照,不是真實 Actions 執行畫面。
自行製作的假想參照範例:移動的 v1 與記錄的提交對照,不是真實 Actions 執行畫面。

離線通過究竟確認了什麼

官方工具區分 gh actions-lock --verify-local 與 gh actions-lock --verify。前者不連網,只檢查 uses 是否有對應項目,也就是 coverage,適合提交前快速檢查,但不驗證來源。後者線上檢查 provenance,runner 也會在工作開始時再次檢查。兩個綠色結果的意義不同。

如果平行 PR 新增 action 卻沒更新 lockfile,本機檢查可以發現項目缺漏。但項目齊全不代表來源或程式碼安全性已獲證明。第二張圖根據文件整理檢查範圍;本文沒有安裝或執行 CLI 來產生實際結果。

根據官方 CLI 文件自行製作:--verify-local 離線檢查涵蓋,--verify 線上驗證來源,不是實際執行結果。
根據官方 CLI 文件自行製作:--verify-local 離線檢查涵蓋,--verify 線上驗證來源,不是實際執行結果。

可重用工作流程有自己的儲存庫邊界

action 內部使用的遞移相依性也在涵蓋範圍內,但 jobs.<job_id>.uses 呼叫的可重用工作流程本身不由 lockfile 固定,需要使用完整提交 SHA。其內部 action 由定義該工作流程的儲存庫 lockfile 管理,而不是呼叫端的檔案。

例如應用程式儲存庫呼叫平台儲存庫的部署流程,只審查應用程式的 actions.lock 看不到平台 action 的固定情況。需要結合呼叫 SHA 與平台儲存庫的相依變更。runner 映像、輸入與 secret 也是不同的建置輸入,固定 action 提交不會凍結整個環境。

更新 PR 裡要把兩個檔案一起讀

Dependabot 更新已採用機制的工作流程中的 action 版本時,會在同一 PR 重新產生對應 lockfile 項目,方便對照易讀版本與實際提交。--relock 會推進已移動的參照並寫入檔案,與唯讀驗證用途不同。程式碼變更本身仍需要審查。

Require lockfile 可以強制採用,卻不會消除儲存庫邊界。先在一個工作流程理解產生、審查和線上驗證,再推廣會更清楚。下次看到綠色檢查時,可以確認它提供的是項目涵蓋、來源驗證,還是對所選程式碼的實際審查。

來源與延伸閱讀

GitHub Changelog · 2026-10-28

GitHub Docs · Workflow dependency lockfiles

GitHub · gh-actions-lock