GitHub Actions 锁文件实用教程：固定依赖并在 CI 中检查

GitHub Actions 常见写法是 uses: actions/checkout@v4。标签便于升级，但团队需要知道运行时实际落到哪个提交。锁文件把工作流依赖对应到已核验的提交，并让 CI 可以检查锁文件是否跟工作流一致。

第一步：先检查工作流

在仓库根目录查看 .github/workflows/ 下所有 YAML 文件，确认每条 uses: 指向你认可的 action 版本。可复用工作流也要检查；它们的依赖由定义该可复用工作流的仓库管理。若组织启用了 Actions 允许列表，先确认锁定后的提交 SHA 也能通过策略。

建议先启用 Dependabot 的 GitHub Actions 更新，再接入锁文件。这样后续 action 升级可以和锁文件一起进入拉取请求，避免手动升级工作流却忘记更新锁。

第二步：安装扩展

电脑需要安装并登录 GitHub CLI。进入仓库根目录后运行：

1
2

gh extension install github/gh-actions-lock
gh auth status

若扩展已安装，之后更新可运行 gh extension upgrade gh-actions-lock。CLI 登录账号至少要能读取仓库和相关依赖仓库。

第三步：先接入一个工作流

初次建议从不承担发布或部署的 CI 工作流开始，缩小审查范围：

1
2
3

gh actions-lock .github/workflows/ci.yml
git status --short
git diff -- .github/workflows/

工具会写入 .github/workflows/actions.lock，并可能改写工作流里的 uses: 写法。不要只看锁文件；检查整个 diff，重点确认 action 名称、解析出的版本、提交变化和组织允许列表。锁文件记录的提交就是运行时会执行的代码，应按普通依赖升级审查。

单个工作流审查通过后，再为整个仓库生成或更新锁文件：

1
2

gh actions-lock
git diff -- .github/workflows/

完整扫描还会清理已删除工作流遗留的锁条目；指定单个工作流的命令只处理该范围。

第四步：把检查放进 CI

先在本机确认工作流和锁文件匹配：

1

gh actions-lock --verify

--verify 只检查，不写文件；官方扩展仓库建议在 CI 使用它。--verify-local 只核对每个引用是否有锁条目，不验证锁定提交仍对应可信上游，因此不能代替在线的 --verify。实际 CI 工作流还需安装 GitHub CLI 和该扩展，再执行同一条检查命令。

后续维护与常见卡点

新增工作流，或增删现有工作流中的 uses: 后，重新运行 gh actions-lock 并提交工作流与锁文件。普通运行不会默默追随分支或短版本标签的新提交；如果上游标签移动，先去上游仓库历史核实原因，再考虑 gh actions-lock --relock。只有确认上游变更可信、且原提交已无法使用时，才考虑 --accept-moved，不要把它当成日常更新快捷键。

本地 uses: ./... action 如果无法解析，先检查路径是否相对仓库根目录、目标目录里是否有真实的 action 文件。官方文档说明扩展可能跳过无法解析的本地 action；看到跳过提示时应先处理，不要把“命令退出成功”当成所有依赖都已经锁好。

GitHub 锁文件操作文档 · gh-actions-lock 使用说明 · 公开预览公告