GitHub Actions cache-mode：檢查綠色 CI 背後隱藏的快取權限
當 CI 呈現綠色成功狀態，但在下一次執行時卻又重新下載相依性套件，我們往往會直覺想修改快取鍵。然而現在，您還必須確認快取是否因權限問題而略過儲存。因為單憑工作流程執行成功，並不能保證快取已經順利建立。
GitHub 於 2026 年 9 月 10 日宣布 cache-mode 正式推出。在 github.com 的所有方案中，均可以工作流程或工作單位來定義快取存取權限。延續先前探討唯讀預設值的文章，本文將進一步聚焦於明確的設定與驗證方法。
已確認的功能：還原與儲存的四種組合
read 僅允許還原，write 允許還原與儲存。write-only 僅允許儲存，而 none 則兩者皆禁止。不要將 write 的名稱誤解為僅限儲存，這是第一項需要確認的重點。
在工作宣告的設定值優先於工作流程整體的設定。相對地，在呼叫可重複使用工作流程時，被呼叫端無法取得高於呼叫端所允許的存取層級。切勿僅憑單一檔案中的宣告，就斷定整個執行的實際權限。
綠色成功執行亦非儲存成功的憑據
官方文件說明，未獲授權的快取作業只會留下提示記錄並繼續執行。被阻擋的還原會被視為快取未命中，被阻擋的儲存則直接略過不執行。工作流程本身不會失敗，正是進行觀察與監控的關鍵所在。
因此，將維運記錄拆分為「執行是否成功」與「快取結果」兩部分會更加實用。在單次執行中，確認是由哪個事件觸發、套用了哪種模式、是否完成還原，以及儲存是否被略過。這是根據官方功能說明所建議的維運作法，而非系統自動提供的全新資訊主頁功能。
套用前先建立簡易權限表
檢視儲存庫中實際的工作流程，找出負責產生快取與消耗快取的工作。在受信任的分支上準備相依套件的工作、測試外部變更的工作，以及驗證部署產出物的工作，並不需要賦予相同的權限。
針對每個工作思考並回答兩個問題：此工作是否需要讀取現有快取？此工作的結果是否可以保留供下次執行讀取？若兩者皆非必要，便應重新審視盲目掛載快取的慣性做法。不過，實際設定仍應依據儲存庫的信任界線與建構架構來決定。
最小實驗：唯讀消耗工作
舉例來說，可以在測試用工作流程的最頂層明確指定 cache-mode: read，並確認個別工作未加以覆寫。接著比對使用快取與無快取狀態下的測試結果是否一致。快取本應只是縮短執行時間的輔助手段，若缺少快取會影響建構的正確性，就必須先重新檢驗建構過程的基本假設。
此實驗的通過標準並不僅是 CI 顯示成功的一行結果。您必須能夠清楚解釋還原嘗試與略過儲存的原因，並能在下一次執行中以相同的輸入再次驗證。若能一併記錄實驗前後的提交、觸發事件、有效設定與記錄位置，其他同事也更容易重現判斷過程。
可重複使用工作流程須追蹤呼叫路徑
即便在共用工作流程中設定了安全的預設值，仍須同時審查呼叫端與個別工作的設定。不同儲存庫呼叫相同檔案，並不代表兩者是以相同的權限執行。
進行代碼審查時，請試著從呼叫端開始，依序追蹤工作的快取宣告與被呼叫的工作流程。若預期的權限與實際記錄不符，在把鍵值改得更複雜之前，應先釐清設定的來源。這是為高度重複使用工作流程的組織縮短診斷時間所提出的建議，並不代表已經過實測的效能提升數據。
注意事項與套用順序
若在 pull_request_target 等低信任度的事件中明確指定 write 或 write-only，可能會覆寫唯讀預設限制，進而增加快取污染的風險。GitHub 在此情況下會加上警告註釋。切勿為了消除警告而採取擴大寫入權限的作法。
相反地，完全禁止所有快取的選擇同樣伴隨成本。這可能會增加下載與建構的時間，因此建議先在具代表性的單一工作中直接比對執行時間，再逐步擴大範圍。與其推測數字並承諾效能效益，不如由團隊共同討論並決定資安所需的限制與可接受的延遲。
團隊現在應確認的問題
今天該做的事並非將新設定一次套用到所有儲存庫，而是在單一核心工作流程中找出快取的產生端與消耗端、記錄其權限，並在一次執行中驗證還原與儲存的依據。若為部署工作，請保持小幅度的變更，讓負責人能檢視記錄並確認是否符合預期。
實務上可能會產生的疑問是：既然儲存步驟被略過，為何 CI 仍然成功？本文依據官方運作機制解答此類疑惑，並未援引外部社群調查或宣稱普遍的故障發生率。在導入新功能時，分別檢視效能結果與權限結果，將有助於在往後更精準地釐清快取相關問題。