gh actions-lock 教學:用 lockfile 鎖定 GitHub Actions 依賴
workflow 寫 @v3,執行的程式碼可能隨標籤移動而改變。這篇說明 GitHub 的 workflow lockfile 怎麼運作,並一步步用 gh actions-lock 上鎖、看懂 diff、日常維護。
workflow 裡的 uses: actions/checkout@v7 看起來是選了第 7 版,實際跑的卻是 v7 標籤當下指向的 commit。上游移動標籤後,你的 workflow 一行沒改,執行的程式碼卻可能跟著變。
GitHub 在 2026-10-28 正式推出 workflow lockfile。gh actions-lock 把支援範圍內的 action 解析成確切的 commit,記在 .github/workflows/actions.lock。納入管理的 workflow,就照這份記錄執行。
這樣 workflow 裡可以保留好讀的版本號,真正要跑的程式碼也進了審查流程。不過,產生 lockfile 本身不代表已完成安全審查。
步驟依 GitHub 官方資料整理,查證日期是 2026-11-13。來源是 GA 公告、Locking action dependencies in a repository’s workflows、Workflow dependency lockfiles,以及 gh-actions-lock v0.4.1 的 README與疑難排解文件。工具持續更新,指令與選項以已安裝版本的
gh actions-lock --help為準。
這篇處理的是「別人寫的 action 被換掉」這種供應鏈風險。我在OWASP Agentic Top 10 檢查表:AI 工作流十項風險與修法的 ASI04(供應鏈)簡短提過用 lockfile 鎖住第三方 action,這篇寫出完整做法。
先認識幾個詞:
- GitHub Actions:GitHub 內建的自動化服務,程式一推上去,就能自動跑測試、建置、部署。
- repo(repository):GitHub 上存放專案程式碼的地方。
- workflow:放在 repo 的
.github/workflows/裡的 YAML 設定檔,寫明要自動做哪些事。 - action:workflow 裡可以重複使用的現成步驟,例如負責「取出程式碼」的
actions/checkout。workflow 用uses:這一行指定要用哪個 action、哪一版。 - commit 與 SHA:commit 是某一次提交時的程式碼快照。SHA 是每個 commit 獨一無二的編號,一長串英數字,內容只要改一個字,編號就不同。
- tag(標籤):替某個 commit 取的好記名字,例如
v3.1.0。標籤像一張貼紙,可以撕下來貼到別的 commit 上。 - lockfile(鎖定檔):記錄每個依賴「確切是哪一版」的檔案。寫過 JavaScript 的人可能看過
package-lock.json,概念一樣。 - Dependabot:GitHub 內建的機器人,發現依賴有新版本時,會自動開 PR(請求合併變更的申請)幫你更新。
- gh:GitHub 官方的命令列工具(GitHub CLI)。
gh actions-lock是替它加上的擴充功能(extension)。
為什麼 @v3 不一定是你審過的那一版
uses: octo-org/deploy-action@v3 的意思不是「用第 3 版」,而是「用 v3 這張貼紙現在貼著的那個 commit」。有權更新這個 tag 的人可以移動貼紙,範圍取決於上游設定的 tag 保護規則。
平常這是作者發新版的方式,讓 v3 跟著最新的 3.x 走。但作者的帳號一旦被盜,攻擊者也能用同一招,把貼紙貼到藏了惡意程式的 commit 上。你的 workflow 一行都沒改,下次執行卻跑了別人的程式。
這種事真的發生過,2025 年 3 月的 tj-actions/changed-files 就是一例。依 GitHub 安全公告,攻擊者回頭修改了它的多個既有版本標籤,全部指向同一個惡意 commit。這段程式會把 CI 裡的機密資料(例如 token、金鑰)印進 workflow 的執行紀錄(log)。
公告寫的受影響期間是 2025 年 3 月 14 日到 15 日,使用這個 action 的 repo 超過 23,000 個。美國 CISA 也為這起事件(CVE-2025-30066)發了警示。
以往常見的做法,是把 action 直接釘到完整的 commit SHA。我這個網站的部署 workflow 就是這樣寫:
1
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
完整 SHA 可以避免跟著移動的 tag 換版,但不保證那個 commit 的內容安全。它也不好讀,一長串編號看不出是哪一版,只能靠行尾的註解。註解還可能和 SHA 對不上,每次更新都要兩個一起改。
workflow lockfile 換了一種做法。workflow 裡繼續寫 @v7.0.1 這種好讀的版本號,SHA 另外記在 lockfile 裡。官方文件寫得很直接,已納入 lockfile 的 action 可以由 lockfile 固定 SHA,不必每一行都直接寫 SHA。
但我不認為這表示可以先拿掉既有的 SHA,再慢慢補 lockfile。要等 workflow 納入 lockfile、審查並驗證過,才拿掉 SHA。
workflow lockfile 是什麼、怎麼運作
lockfile 就是 .github/workflows/actions.lock 這個檔案。它記下每個 workflow 用到的 action 解析到哪一個 commit,執行時 GitHub 以它為準。
它由 gh actions-lock 自動產生,不要手動修改。每個 action 會記這幾個欄位:
ref:這個 commit 是從哪個標籤或分支解析出來的,例如v3.1.0。commit:解析到的 commit,也就是真正會執行的程式碼。owner_id、repo_id:來源 repo 的數字編號。執行時用它確認,名字背後還是當初鎖住的那個 repo。
被鎖住的不只你直接寫在 uses: 的 action。依 GA 公告,action 自己再用到的其他 action(遞移依賴)也會一起鎖住。
一個 workflow 被納入 lockfile 之後(官方稱為 onboard,這篇我叫它「上鎖」),依概念說明,執行時有三條規則:
- 這個 workflow 用到的每個 action,都必須出現在 lockfile 裡。
- 執行的是 lockfile 裡記的那個 commit,不是標籤現在指到的 commit。
- 那個 commit 必須在 action 自己的 repo 裡,而且從記錄的標籤或分支追得到。只存在於 fork(別人複製出去的 repo)的 commit,或已經不在那個標籤歷史裡的 commit,執行時會被拒絕。
所以標籤被移走時,workflow 要嘛照跑鎖住的那一版,要嘛直接被擋下,不會悄悄改跑新的程式。
概念圖:同一行 uses: octo-org/deploy-action@v3。左邊沒有 lockfile,執行時跟著標籤走;右邊有 lockfile,照跑鎖住的 commit,那個 commit 若已不在標籤的歷史裡,這次執行會被擋下。
誰可以用,要看三份資料:
| 資料 | 寫的適用範圍 |
|---|---|
| GA 公告 | GitHub Enterprise Cloud(含資料落地版本)、Team 與 Free |
| 操作與政策文件 | 適用方案欄仍標示 Enterprise Cloud |
| v0.4.1 README | 擴充功能支援 github.com 與 GHE.com |
我查閱時,GA 公告和操作與政策文件寫的方案並不一致。實際能用哪些功能與政策,以你的 repo 設定為準。尤其不要把「產生得出 lockfile」當成「執行時已套用保護」。
步驟 0:先準備這些
裝好 GitHub CLI 並登入。 照 GitHub CLI 官網安裝,再執行下面這行登入:
1
gh auth login
擴充功能需要已登入的
gh。- 對 repo 有寫入權限。 官方文件寫,有寫入權限就能建立 lockfile,不需要管理員權限。
先保存目前變更,另開工作分支。 工具會修改 workflow 和 lockfile,先確認現況:
1
git status --short安裝工具後若想先看報告,可執行下面這行,它只檢查、不寫檔:
1
gh actions-lock --no-fix先開 Dependabot。 官方建議在產生 lockfile 之前,先讓 Dependabot 管理 GitHub Actions 的版本。最基本的設定如下。已有
.github/dependabot.yml的話,把這個更新項目合併進既有設定,不要整份覆蓋:1 2 3 4 5 6
version: 2 updates: - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"
- 先審過每一行
uses:。 官方提醒,上鎖前要先審過依賴。確認指向的都是仍在維護的目前版本,因為 lockfile 會把你寫的版本原樣鎖住,舊版本鎖起來還是舊版本。 - 確認有沒有 action 允許清單。 有些組織只允許使用特定的 action(allowlist)。上鎖之後比對方式會改變,步驟 3 會說明。
步驟 1:安裝 gh-actions-lock
1
gh extension install github/gh-actions-lock
這會安裝當下最新的 release,而這篇是依 v0.4.1 的文件寫的。想固定使用這一版,安裝時加上 --pin v0.4.1:
1
gh extension install github/gh-actions-lock --pin v0.4.1
--pin 指定的是 release tag,不是完整的 commit SHA。它也不代表工具通過了安全審查,工具來源仍要自己確認。
沒有加 --pin 的一般安裝,之後可以這樣更新:
1
gh extension upgrade gh-actions-lock
裝好後,我會先看一次說明。README 寫,所有選項以這份說明為準:
1
gh actions-lock --help
步驟 2:產生 lockfile
在 repo 的根目錄執行:
1
gh actions-lock
它會掃過 .github/workflows/ 底下每一個 workflow,把每個能解析的 action 釘到一個 commit。結果寫進 .github/workflows/actions.lock。
官方建議一個一個 workflow 慢慢納入。只鎖一個 workflow 時,指定它的路徑:
1
gh actions-lock .github/workflows/ci.yml
要注意,只有對整個目錄執行時,才會清掉已刪除 workflow 的舊紀錄。
步驟 3:看懂 diff 再提交
執行完後,我會先確認修改與新增了哪些檔案,再看已追蹤檔案的變更:
1
2
git status --short
git diff -- .github/workflows/
新建的 actions.lock 還沒被追蹤,不會出現在一般的 git diff 裡。要開檔檢查,或加入暫存區後用下面這行查看:
1
git diff --cached
主要看兩處。
第一處,workflow 檔裡的 uses: 寫得更精確。 例如 octo-org/deploy-action@v3 可能被改寫成 octo-org/deploy-action@v3.1.0。只有找得到指向同一個 commit 的完整版本標籤時,工具才會這樣改寫,所以 commit 不變,不會因此升到別的版本。
想保留 @v3 的寫法,執行時加上 --no-narrow。
第二處,新增的 actions.lock。 檔案開頭有幾行註解,提醒這是自動產生、不要手動修改的檔案。接著的內容結構大致如下(數值是示意):
1
2
3
4
5
6
7
8
9
10
version: 'v0.0.3'
workflows:
'.github/workflows/ci.yml':
- 'octo-org/deploy-action@v3.1.0'
dependencies:
'octo-org/deploy-action@v3.1.0':
ref: 'v3.1.0'
commit: '<commit SHA>'
owner_id: 1234567
repo_id: 7654321
version 是 lockfile 的格式版本,不是擴充功能的版本。workflows 列出每個 workflow 用到哪些 action,dependencies 記下每個 action 解析到的 commit。
審查時我會看兩件事:
commit變了。 代表 workflow 之後會跑不同的程式碼。官方建議把它當成程式碼變更來審,去看上游改了什麼。owner_id或repo_id變了。 這應該很少發生。官方建議先查清楚原因,再合併。
概念圖:上方是 workflow 檔的改寫,@v3 變成 @v3.1.0,指向同一個 commit;下方是新增的 actions.lock,以及 ref、commit、owner_id/repo_id 各代表什麼。
有 action 允許清單的話,清單要跟著改。 官方文件特別提醒,workflow 上鎖之後,允許清單比對的是鎖住的 commit SHA,不再是標籤。像 actions/checkout@v6 這種寫死標籤的項目會對不上,有兩種改法:
- 改成對應的完整 commit SHA。
- 由管理員改用萬用字元。範圍要限縮在可信的 owner/repo,不要為了消除錯誤就整個放寬。
清單可能設在 repo、組織或企業層級,不確定的話先問管理員。
確認沒問題,就把 actions.lock 和改寫過的 workflow 一起提交。官方另外建議把 .github/workflows/actions.lock 加進 CODEOWNERS(指定哪些檔案要由誰審核的設定檔)。
CODEOWNERS 本身不會擋下合併,要搭配分支保護或 ruleset 開啟「需要 code owner 核准」才有效。workflow 檔與 CODEOWNERS 也要列入保護,否則仍可能有人直接拿掉檢查,或改用其他 action。
步驟 4:日常維護
上鎖不是做一次就結束,我認為下面幾件事決定它能不能長期有效。
改了 uses: 就重新執行。 新增 workflow,或在既有 workflow 增刪 action 時,再跑一次:
1
gh actions-lock
Dependabot 會一起更新。 對已上鎖的 workflow,Dependabot 開版本更新的 PR 時,會在同一個 PR 裡重產對應的 lockfile 紀錄,不需要額外設定。但它只處理已上鎖的 workflow。還沒上鎖的,它照舊只改 workflow 檔,也不會替你把新的 workflow 納入 lockfile。
讓 CI 檢查 lockfile 有沒有過期。 gh actions-lock --verify 只檢查、不改檔案。缺少必要鎖定紀錄、驗證失敗這類阻擋性問題,會讓它以錯誤結束,所以適合設成 PR 必須通過的檢查。
gh-actions-lock 的 repo 提供了 verify-lockfile.yml 範例。下面這份是我以它為基礎改寫的版本,把擴充功能固定在這篇對照的 v0.4.1,適用於 github.com 上一般的 PR 檢查:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Fails when .github/workflows/actions.lock is out of sync with the
# workflows or a locked pin no longer verifies upstream.
name: verify-lockfile
on:
pull_request:
push:
branches:
- main
permissions:
contents: read
jobs:
verify:
runs-on: ubuntu-latest
env:
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- run: gh extension install github/gh-actions-lock --pin v0.4.1
- run: gh actions-lock --verify
幾個重點:
on:每個 PR,以及推到main時都會檢查。permissions: contents: read:只給讀取權限,這個檢查不需要改任何東西。persist-credentials: false:checkout 完不把 Git 憑證留在 Git 設定裡。但 job 仍透過GH_TOKEN提供 token 給工具查詢 GitHub,並不是整個 job 都沒有 token。--pin v0.4.1:指定擴充功能的 release tag,讓每次安裝的版本與本文對照的一致。這個下載來的二進位工具不歸 workflow lockfile 管,lockfile 不會鎖住它的內容。
gh actions-lock --verify 的結束碼有三種:
| 結束碼 | 意思 |
|---|---|
| 0 | 沒有阻擋性錯誤,仍可能有警告 |
| 1 | 有阻擋性問題 |
| 2 | 工具本身出錯,例如選項錯誤、lockfile 讀不了或 token 被拒絕 |
檢查通過,不等於所有依賴都已審查或沒有風險。
README 提醒,把這份檔案複製進 repo 之後,要再跑一次下面這行,讓這個負責檢查的 workflow 自己也上鎖:
1
gh actions-lock
另外還有 --verify-local。它不連網,只檢查每一行 uses: 在 lockfile 裡有沒有紀錄,適合提交前快速檢查。它不驗證來源,不能取代 --verify。
工具也不會替你修正權限不足、網路錯誤或 API 限流。遇到這些情況,先排除問題再重跑,不要把「無法驗證」當成「通過」。
GHE.com 的 token 要另外看。 依 v0.4.1 README,GHE.com tenant 的 GITHUB_TOKEN 不能拿去查 github.com 上的公開 action。本機可以另外登入 github.com,CI 則依文件另外提供 GH_ACTIONS_LOCK_GITHUB_COM_TOKEN。
這個 token 只用來查詢公開 repo,不需要寫入權限。不要為了避開限流而多給權限。
標籤或分支移動了,看種類處理。 下表是擴充功能在檢查與維護時的行為,workflow 實際執行時,runner 還會另外驗證鎖定紀錄。
依 v0.4.1 疑難排解文件,main、v4 這類參照的 ref-moved 警告只出現在 JSON 輸出,也不會讓結束碼變成失敗。要看這類訊息,可執行:
1
gh actions-lock --verify --json
| 你寫的參照 | 發生什麼 | 怎麼做 |
|---|---|---|
分支或部分版本,例如 main、v4 | 舊 commit 仍可由上游歷史驗證時,保留舊鎖定;JSON 回報 ref-moved 警告 | 看過上游改了什麼,要跟上就執行 gh actions-lock --relock |
完整版本標籤,例如 v3.1.0 | 標籤必須指向鎖住的 commit,移動了就報錯 | 先弄清楚標籤為什麼被移動,再執行 gh actions-lock --relock,或改寫 uses: 那一行 |
| 歷史被改寫,例如上游 force push 之後,鎖住的 commit 不在歷史裡了 | 報錯,--relock 也修不好 | 先排除 lockfile 被誤改,再審查上游歷史與新 commit;確認要採用後,才執行 gh actions-lock --accept-moved |
概念圖:三種參照移動的情況與對應指令。第三種的 --accept-moved 只能在人工確認後使用,不要放進自動化。
--accept-moved 接受的是什麼? 它表示你已檢查上游歷史,願意信任新的 commit,不是讓已無法驗證的舊 commit 繼續過關。歷史被改寫可能是正常維護,也可能是供應鏈攻擊或 lockfile 被誤改。工具無法替你判斷是哪一種,所以會先停下來。
這個選項只處理 workflow 自己直接引用的依賴。問題若藏在第三方 composite action 裡,要升級、替換或停止使用該 action,不能靠同一個旗標全部放行。
--relock 也會改變要執行的 commit,同樣要審查差異。我不會把這兩個選項當成「CI 出錯就自動補上」的解法;官方則明確要求不要在自動化裡使用 --accept-moved。
不要刪掉 lockfile。 README 提醒,鎖住的參照會一直沿用。刪掉重產,所有參照都會重新解析成「現在指到的 commit」,等於重新相信一次上游。
檔案壞了,照這個順序處理:
flowchart TD
A[lockfile 壞了] --> B[比對差異,另存變更]
B --> C{可信分支的 lockfile 正常?}
C -->|正常| D[從可信分支還原]
D --> E["重跑 gh actions-lock"]
E --> F[檢查差異,加回暫存區]
C -->|也壞了| G[備份後重建]
G --> H[逐項審查每個依賴]
比對的是工作目錄、暫存區與可信版本之間的差異,要保留的變更先另外存好。還原的指令如下。restore 會覆蓋工作目錄中的 lockfile,但不會更新暫存區,執行前請確認沒有需要保留的未提交內容:
1
2
3
git fetch origin
git restore --source=origin/main --worktree -- .github/workflows/actions.lock
gh actions-lock
預設分支不叫 main 的話,把第二行的 origin/main 換掉。重建時每個依賴都會重新解析,所以只在可信分支上的 lockfile 也壞了時才用,不要把它當成一般的排錯手段。
步驟 5:處理本機 action(./)
有些 workflow 會用 repo 自己裡面的 action,寫成 uses: ./.github/actions/setup 這樣。./ 路徑跑的是執行機器上當下取出的檔案,所以擴充功能沒辦法鎖住它,也看不到它裡面又用了哪些 action。
如果這個本機 action 還用了別的 action,gh actions-lock 會回報 local-action 錯誤,而且什麼都不寫。處理方式有兩種:
flowchart TD
A["local-action 錯誤,不寫檔"] --> B{怎麼處理}
B -->|建議| C["--migrate-local-actions"]
C --> D["./ 改寫成 $/"]
D --> E[逐行檢查改寫結果]
B -->|"保留 ./"| F["--ignore-local-actions"]
F --> G{同一 workflow 有紀錄?}
G -->|有| H[可能正常執行]
G -->|沒有| I[job 跑到那步才失敗]
改成 $/(建議)。 執行下面這行:
1
gh actions-lock --migrate-local-actions
它會把 workflow 和 repo 內 action.yml 裡的 uses: ./… 改寫成 uses: $/…。
$/ 的意思是「在這個 workflow 所在的 commit,執行 repo 自己的 action」。因此它本身跟著 workflow 的 commit 固定,不需要在 lockfile 另外記一筆;它引用的遠端 action 則可以記進 lockfile。
這不只是換個路徑寫法。原本的 workflow 若會先 checkout 別的 ref 再執行 ./ action,改成 $/ 後,跑的會是 workflow 所在 commit 的版本。兩者的實際執行內容可能不同,所以改寫後每一行都要看過。
保留 ./。 改加 --ignore-local-actions,錯誤會降為警告。本機 action 若只含 run:,或它用到的 action 已記在同一個 workflow 的鎖定清單裡,仍可能正常執行。
代價是缺少同一個 workflow 的對應紀錄時,job 要到那一步才失敗。錯誤訊息類似 lockfile missing pin for octo-org/setup-tool@v2.0.0,而且到那時,前面的步驟已經跑過了。
進階:要求每個 workflow 都要上鎖
前面的步驟讓「已上鎖的 workflow」跑鎖住的版本,但擋不住有人新增一個沒上鎖的 workflow。想強制所有 workflow 都上鎖,可以用 Require lockfile 政策(說明)。
企業、組織或 repo 的管理員可以在 Actions 政策裡開啟它,作為 workflow 的執行保護。它有兩種狀態:
| 狀態 | 行為 |
|---|---|
| Evaluate | 只記錄、不擋,僅限 GitHub Enterprise Cloud |
| Active | 擋下範圍內所有還沒上鎖的 workflow,包括只有 run:、沒有 uses: 的 workflow,即使同一個 repo 的其他 workflow 已經上鎖 |
改成 Active 之前,先在每個目標 repo 跑過下面這行,或在 Evaluate 狀態下查看 Policy insights:
1
gh actions-lock --verify
開了政策之後,--verify 的檢查仍然要留著。--verify 在 PR 階段就提醒作者 lockfile 過期了,政策則在執行時才擋下沒有有效 lockfile 的 workflow:
flowchart LR
A[修改 workflow] --> B["提交前 --verify-local"]
B --> C["PR 上 CI 跑 --verify"]
C --> D[審查 lockfile diff]
D --> E[合併]
E --> F{workflow 已上鎖?}
F -->|是| G[runner 驗證,不符就擋下]
F -->|否,政策 Active| H[執行被擋下]
F -->|否,未開政策| I[照標籤執行]
組織若已開「action 必須釘到完整 SHA」的政策,它和 Require lockfile 是各自獨立的檢查,兩個都要通過。已上鎖的 workflow,就算檔案裡沒寫 SHA,也能同時通過兩者。
lockfile 管不到的地方
上鎖之前,先知道這些限制:
- reusable workflow 不會被鎖。 reusable workflow 是可被其他 workflow 呼叫的 workflow,在 job 層級用
jobs.<job_id>.uses呼叫。它不在 lockfile 裡,要另外釘完整的 commit SHA;它自己用的 action,由它所在 repo 的 lockfile 負責。開了 Require lockfile 政策時,被呼叫的 workflow 若沒有在自己的 repo 上鎖,這次執行會被擋下。- container image 不會被鎖。 README 寫,
docker://步驟與 job 的container:、services:都不鎖。Docker action 的 image/Dockerfile 基底映像也不鎖。沒寫@sha256:digest 的 image 會被列為警告。- 只管 action 的程式碼。 傳給 action 的輸入、secrets、執行機器的系統映像檔,以及
run:、安裝腳本另外下載的內容,都不在它的範圍內。鎖住 action 也不會限制它的檔案、網路或 token 權限。- 不判斷安全。 lockfile 只確保跑的是你鎖住的那一版,不判斷那一版有沒有問題。官方提醒上鎖前要先審過依賴,因為鎖住的那一版若本來就有問題,lockfile 會很忠實地一直跑它。
- 倒退偵測不到。 README 提醒,如果有人在 lockfile 裡,把
v4、main這類會移動的參照改回它歷史上較舊的 commit,工具偵測不到。lockfile 的 diff 要有人看,或改用完整版本標籤。- 擴充功能不支援 GitHub Enterprise Server。
什麼情況怎麼做
| 我想… | 怎麼做 |
|---|---|
| 第一次上鎖 | 先開 Dependabot、檢查 uses:;裝好擴充功能,在 repo 根目錄執行 gh actions-lock;看懂 diff 再提交 |
| 先只鎖一個 workflow | gh actions-lock .github/workflows/<檔名>.yml |
保留 @v3 的寫法 | 執行時加 --no-narrow |
新增或修改了 uses: | 再執行一次 gh actions-lock |
| 在 PR 檢查 lockfile 有沒有過期 | 加入 verify-lockfile.yml 跑 gh actions-lock --verify,並設成必須通過的檢查 |
收到 ref-moved 警告 | 看過上游變更,要跟上就執行 gh actions-lock --relock |
| 完整版本標籤被移動 | 先弄清楚原因,再 gh actions-lock --relock 或改寫 uses: |
| 鎖住的 commit 不在上游歷史裡 | 人工確認後才 --accept-moved,不要放進自動化 |
有本機 action(./) | --migrate-local-actions 改成 $/ |
| 組織有 action 允許清單 | 改成對應的完整 SHA,或經管理員確認的最小範圍萬用字元 |
| 要求每個 workflow 都上鎖 | 管理員設定 Require lockfile 政策;Enterprise Cloud 可以先用 Evaluate 觀察,再改成 Active |
| lockfile 壞掉 | 從 git 還原後再執行 gh actions-lock,不要刪掉重產 |
常見錯誤與處理
- 手動改 lockfile: 擴充功能會拒絕
ref和 workflow 參照對不上的紀錄。要改就改 workflow,再重新執行gh actions-lock。 - 上鎖後,workflow 被允許清單擋下: 先確認是否因鎖定後改以 SHA 比對。改用對應的完整 SHA 或經管理員審查的有限範圍規則,不要全面放行。
- 出現
local-action錯誤: 本機 action 裡用了其他 action。用--migrate-local-actions改成$/,或加--ignore-local-actions,但要承擔執行到一半失敗的風險。 - job 跑到一半出現
lockfile missing pin for …: 保留./的本機 action 用了 lockfile 沒記到的 action。改成$/最省事。 - 新的 workflow 沒被 Dependabot 納入: Dependabot 不會替你上鎖新 workflow,自己執行一次
gh actions-lock。 - Dependabot 更新後 lockfile 沒動: 先確認該 workflow 已納入管理,再看 PR 差異與
--verify輸出。只看檔案有沒有變動,不能判斷這次更新是否完整。 - 在 CI 裡自動加
--accept-moved: 拿掉。這正是 lockfile 要攔下的情況。 - 以為 reusable workflow 也鎖住了: 沒有,
jobs.<job_id>.uses要另外釘完整 SHA。 - 檢查成功,卻沒有看到參照移動警告: v0.4.1 的部分
ref-moved訊息只在 JSON 輸出中,且警告不會讓結束碼失敗。用--verify --json查看。 - 刪掉 lockfile 重產: 所有參照會重新解析成現在指到的 commit。改從 git 還原。
結論與下一步
我建議照這個順序開始:先開 Dependabot,執行 gh actions-lock,看懂 diff 再提交,然後用 --verify 讓 CI 幫你盯著。標籤被移動時,停下來看一眼,不要讓自動化替你按下 --accept-moved。
我會先鎖負責發布的 workflow。照npm Trusted Publishing 設定教學:發套件不再放長期 token設定後,發布流程不再需要長期 token。但 workflow 跑的 action 若被換掉,一樣能發出有問題的版本。
- 開了 Trusted Publishing 還不夠:npm 發布流程也要上鎖:替發布流程本身加上核准與審查關卡。
- 用 GitHub Actions 加 AI Agent 自動化審查:以本站 PR 為例:替同一條 CI 流程加上自動化審查。
- OWASP Agentic Top 10 檢查表:AI 工作流十項風險與修法:更完整的 AI 工作流風險檢查。
