当前位置：首页 > 文章列表 > 科技周边 > 业界新闻 > GitHub Actions 工作流锁文件公开预览后怎样固定依赖变更

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

来源：17golang原创 2026-11-03 08:20:59 0浏览收藏

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，或维护定义该可复用工作流的仓库。

GitHub Actions 工作流、actions.lock、提交 SHA 和未覆盖输入之间的静态关系说明图 — 图1：工作流依赖、锁文件和执行提交的关系；这是静态说明图，不是运行截图或执行证据。

用 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 更完整。

Dependabot、gh actions-lock、verify 命令和工作流依赖记录之间的静态维护关系图 — 图2：锁文件生成、依赖更新和 CI 校验的维护关系；这是静态说明图，不是实际界面截图。

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

对已有仓库，我更建议按 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、输入参数、运行器镜像和容器镜像仍需单独治理。

一张表决定是否现在接入

你的情况	建议	原因
工作流大量使用浮动标签或分支	优先试点	锁文件能把审核过的 action 提交固定下来
只想做离线覆盖检查	使用 verify-local	不联网，只检查 uses 是否都有条目
准备合并依赖更新	使用 verify	额外检查提交来源和可达性
工作流调用外部可复用 workflow	单独固定 jobs.*.uses	调用方锁文件不覆盖它的依赖
团队尚未审查 action 来源	先审查再锁定	锁定不会把不安全依赖变安全

常见追问

锁文件能替代 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 管理更新。这样锁定的是依赖解析结果，安全审查和运行环境治理仍然要保留。