GitHub Actions 工作流锁文件公开预览后怎样固定依赖变更

GitHub Actions 的工作流如果写成 uses: org/action@v3 或 uses: org/action@main，运行时解析到的提交可能随着标签或分支移动而改变。工作流依赖锁文件解决的是这个具体问题：保留可读的引用，同时把实际执行的 action 代码固定到审核过的提交。

官方资料：https://docs.github.com/en/actions/concepts/security/workflow-dependency-lockfiles

这项能力最初在 2026 年 10 月进入公开预览，随后已进入一般可用阶段，支持 GitHub Enterprise Cloud、带数据驻留的 GitHub Enterprise Cloud、Team 和 Free 计划。下面按一个维护 CI 的真实场景，说明怎样接入，以及它没有解决什么问题。

先看清锁文件到底固定了什么

锁文件固定的是工作流依赖 action 的提交 SHA，包括传递依赖。比如工作流引用 actions/checkout@v4，锁文件会记录它当时解析到的精确提交；即使 v4 标签后来移动，已接入锁文件的工作流仍按记录的提交运行。

它不等于“所有 CI 输入都被冻结”。输入参数、Secrets、运行器镜像和容器镜像不在 action 锁文件的控制范围内；跨仓库可复用工作流调用也不由调用方仓库的锁文件覆盖，需要在 jobs..uses 中直接使用完整提交 SHA，或维护定义该可复用工作流的仓库。

用 gh actions-lock 生成第一份 actions.lock

GitHub 官方提供的 gh-actions-lock 是 GitHub CLI 扩展，生成和校验锁文件。先在已登录 GitHub CLI 的仓库目录中安装扩展：

# 安装官方 GitHub CLI 扩展，用于生成工作流依赖锁文件
gh extension install github/gh-actions-lock

# 从仓库根目录扫描工作流，生成或修复 actions.lock
gh actions-lock

工具生成的文件位于 .github/workflows/actions.lock，不要手工编辑。生成后把工作流变化和锁文件放在同一个提交中审阅：

# 将工作流和机器生成的锁文件一起加入审阅范围
git add .github/workflows/

# 查看 action 引用与锁定提交是否成对变化
git diff --cached -- .github/workflows/

如果仓库使用了多个 workflow，可以先逐个接入，而不是一次性切换全部流水线。只要某个 workflow 已接入，GitHub Actions 就要求它使用的每个 action 依赖都能在锁文件中找到。

理解 actions.lock 里的两个核心区块

锁文件由 workflows 和 dependencies 两个区块组成。前者说明某个 workflow 使用了哪些依赖，后者说明每个依赖从哪个 ref 解析出了哪个 commit，以及来源仓库的数字身份。

# 下面是官方格式的缩略示意，实际提交值由 gh actions-lock 生成
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: 'sha1-...'
    owner_id: 44036562
    repo_id: 197814629

ref 是人能读懂的标签或分支，commit 是实际执行的提交；owner_id 和 repo_id 用来确认运行时仍然是同一个来源仓库。传递依赖也会进入记录，所以锁文件比只在 YAML 里手工固定一层 SHA 更完整。

把接入过程拆成可回滚的维护策略

对已有仓库，我更建议按 workflow 逐个接入。第一步生成并审阅锁文件，第二步把锁文件提交到版本库，第三步在一段时间内观察更新 PR 是否同时修改 workflow 引用和对应锁定提交。确认规则稳定后，再考虑让组织或仓库管理员启用 Require lockfile 策略。

依赖升级仍然可以使用可读的版本引用。官方说明中，Dependabot 为已接入的 workflow 打开 action 版本更新时，会在同一个 PR 中重新生成匹配的锁文件条目，不需要额外配置。审阅者需要关注的不是“锁文件变了没有”，而是引用、ref、commit 与来源仓库身份是否一起变化。

如果上游分支或标签正常移动，要主动推进锁定提交，可使用：

# 允许工具根据上游当前引用重新计算锁定提交
gh actions-lock --relock

# 只报告问题，不修改仓库文件，适合先做变更预览
gh actions-lock --no-fix

--relock 代表接受一次有意识的依赖更新，应与代码审阅和变更记录绑定；不要把它当成无人值守的自动放行开关。

在 CI 中区分覆盖检查和来源校验

锁文件工具提供两种容易混淆的检查。--verify-local 不访问网络，只检查每个 uses: 是否有锁文件条目，适合提交前或快速门禁；--verify 会做来源校验，适合合并前确认锁定提交仍可追溯到记录的分支或标签。

# 本地覆盖检查：不联网，只判断 uses 是否都有锁文件条目
gh actions-lock --verify-local

# 合并前校验：检查锁定提交的来源和可达性
gh actions-lock --verify

如果 action 的锁定提交只存在于 fork，或已经无法从记录的分支、标签到达，工作流运行时会被拒绝。另一方面，--verify-local 只覆盖“有没有条目”，并不验证来源可信度；两者不能互相替代。

四个常见误区

• 把锁文件当成安全认证。它能减少引用漂移带来的意外代码变化，但不会替你审查 action 是否安全。
• 只锁直接依赖。锁文件的价值之一就是覆盖传递依赖，手工只改 YAML 中的第一层 SHA 会漏掉后续依赖。
• 手工改 actions.lock。它是机器生成文件，应该通过 gh actions-lock 更新，避免结构与 workflow 失配。
• 认为接入后所有执行环境都固定。Secrets、输入参数、运行器镜像和容器镜像仍需单独治理。

一张表决定是否现在接入

常见追问

锁文件能替代 YAML 中的完整 SHA 吗？

对于已经接入锁文件的 action 依赖，GitHub 文档说明不再要求在 workflow 文件中重复写完整 SHA；但可复用 workflow 调用仍需要在调用位置单独使用完整提交 SHA。

actions.lock 要不要提交到 Git？

要提交。它是工作流依赖的可审阅清单，应该和 workflow 变更一起进入版本库，而不是只留在生成者的本地目录。

为什么 lockfile 校验会失败？

常见原因包括新增了未锁定的 uses:、锁定提交不再从记录的 ref 可达，或来源仓库身份发生变化。先用 gh actions-lock --no-fix 查看报告，再决定是重新锁定还是修正引用。

从公开预览到一般可用，GitHub Actions 工作流锁文件解决的是“审核过的 action 代码是否会因标签移动而改变”。实际接入时，先从一个 workflow 生成并审阅 actions.lock，再把 verify-local 和 verify 放到不同层级的门禁中，最后结合 Dependabot 管理更新。这样锁定的是依赖解析结果，安全审查和运行环境治理仍然要保留。