GitHub Actions 工作流锁文件公开预览：锁住依赖，也要看清覆盖边界

GitHub 在 2026 年 10 月 14 日宣布，Actions 工作流依赖锁文件进入公开预览。工作流可以继续使用便于阅读的标签或分支引用，实际运行则采用锁文件记录的提交，减少上游引用移动带来的意外变化。

这项能力补上了 CI 依赖管理的一处缺口。但它没有让整个构建自动变得可重复，也不会判断锁定的代码是否安全。真正接入前，需要看清锁文件负责哪些依赖、跨仓库调用如何衔接，以及团队怎样审查和更新这些记录。

工作流没改，执行的 action 却可能变了

许多工作流通过 uses: owner/action@v3 引用 action。这个写法容易读懂，却不能单凭仓库中的工作流文件确定下一次究竟执行哪个提交。标签和分支可以移动，运行时解析到的代码也就可能变化。

这种变化可能来自正常维护，也可能来自上游账户被入侵后的恶意改写。对能够接触发布凭证或构建产物的 CI 任务，这不是单纯的版本管理问题。

过去，GitHub 推荐将第三方 action 固定到完整提交 SHA。这样能固定直接引用的 action，但它使用的其他 action 也需要关注。新锁文件将这一部分依赖解析结果放进仓库，便于统一检查。

根据公告当日更新的套餐说明，公开预览面向 GitHub Enterprise Cloud、带数据驻留的 Enterprise Cloud、Team 和 Free。查阅时，部分操作文档的可用性栏仍写着 Enterprise Cloud；本文以更新后的公告描述此次开放范围，具体策略入口应以账户实际界面为准。官方扩展仓库明确说明，目前不支持 GitHub Enterprise Server。

actions.lock 把“引用”与“执行提交”分开记录

锁文件位于 .github/workflows/actions.lock，由 GitHub CLI 扩展 gh actions-lock 生成，不应手工编辑。它既记录哪些工作流已经接入，也记录依赖引用对应的提交和来源仓库身份。

接入可以按工作流逐步进行。一个工作流接入后，它使用的 action 依赖必须在锁文件中有记录，运行时采用记录的提交。锁定提交还必须存在于来源仓库的某个分支历史中。

锁文件中的主要字段可以这样理解：

字段或分区	负责记录什么	审查重点
workflows	已接入工作流及其依赖引用	新增工作流是否遗漏接入
dependencies 中的 ref	工作流使用的标签或分支	是否符合预期版本
commit	实际执行的精确提交	本次更新将运行哪些新代码
owner_id、repo_id	来源所有者与仓库的数字身份	名称背后的仓库是否发生变化

最后两项身份字段值得单独看待。仓库名称相同，不一定意味着来源身份仍然相同。官方文档说明，Actions 会在运行时利用这些记录核对来源仓库；扩展仓库也说明，会阻止相应的重定向和身份不匹配。

这让锁文件承担了比“把标签换成 SHA”更多的工作。不过，数字身份和提交检查只能回答来源与版本问题，不能替代代码审查。

传递依赖有覆盖，可复用工作流仍有仓库边界

如果 action A 使用了 action B，只锁住 A 的直接引用还不够。锁文件会覆盖 action 的传递依赖，让这类间接调用也有明确的提交记录。

可复用工作流要分开理解。调用方可以锁定外部可复用工作流的引用，但该工作流内部使用的依赖，由它所在仓库的锁文件负责。调用方的锁文件不会替所有下游工作流仓库维护完整依赖树。

因此，维护共享工作流的团队最好先接入共享仓库，再让业务仓库接入。否则，业务仓库看起来已有锁文件，跨仓库调用的内部依赖却未必受到同样的管理。

同仓库 action 也有变化。官方操作文档说明，工具会将能够解析到实际 action 文件的 uses: ./… 改写为等价的 uses: $/…，涉及工作流和仓库内的 action.yml。$/… 指向定义文件所在仓库的运行提交，本身已经固定，因此不需要另加锁文件条目。

公开预览期间，本地路径仍有接入限制。若工具报告跳过，应先检查路径是否能从仓库根目录解析到真实 action 文件，并核对当前工具版本的规则。不能只看到生成了一个锁文件，就认定所有工作流都已接入。

试点时，要审查的不只是新增文件

下面是官方支持的基本用法，供计划试点的团队参考。本文没有在博客项目中执行这些安装或配置命令。

# 安装 GitHub CLI 扩展
gh extension install github/gh-actions-lock

# 先接入一个工作流
gh actions-lock .github/workflows/ci.yml

# 联网校验，不改写文件
gh actions-lock --verify

不带路径运行 gh actions-lock 会扫描工作流目录。工具除了生成锁文件，也可能将标签改为更具体的版本，例如把 @v3 调整为解析到的 @v3.1.0，而不改变当时解析出的提交；本地 action 引用也可能被迁移。

这意味着代码审查必须覆盖完整差异。应确认工作流实际接入情况、引用改写、锁定提交和来源身份，而不是只检查多了一个 actions.lock。

另一处容易造成试点失败的是允许使用 action 的策略。官方文档说明，接入后，allowlist 针对锁定提交 SHA 检查。原先按标签写的允许项，例如 actions/checkout@v6，不再匹配；需要按策略改用完整提交 SHA 或合适的通配规则。

通配规则会扩大允许范围，不能为了让试点通过就直接放开所有 action。先在少量仓库确认现有策略如何匹配，再选择符合团队约束的调整方式。

锁定以后，更新也要经过审查

锁文件的价值在于让依赖变化显式出现，所以正常运行生成命令不会不断追随已经记录的分支或部分版本标签。新增或删减 uses 依赖后，应重新生成锁文件；需要更新锁定提交时，则要走明确的更新流程。

官方扩展提供 --relock 重新解析合法移动的引用。如果原来锁定的提交已经无法在上游到达，单独使用这个选项仍会报错；接受这类变化需要额外使用 --accept-moved。

后者不应当成为“报错就加上”的常用参数。强制推送、删除提交或重打标签，既可能有合理原因，也可能是需要调查的异常。应先检查上游历史和发布说明，再决定是否接受新提交。

Dependabot 可以减少维护工作。它为已经接入的工作流更新 action 版本时，会在同一次代码审查中重新生成匹配的锁文件记录，不需要额外配置这项联动。但它不会自动替尚未接入的工作流完成接入。

团队可以将工作流、锁文件和本地 action 定义交给相应维护者共同审查。尤其是 commit 的变化，应该当作实际执行代码的更新；owner_id 或 repo_id 的变化则应先调查来源身份。

离线检查也不能替代联网验证。扩展的 --verify-local 只检查引用是否有锁文件记录，不验证这些记录是否可信。它适合缩短本地反馈时间，CI 中仍应按官方建议使用 --verify。

Require lockfile 适合在试点之后启用

同日进入公开预览的 Require lockfile 策略，可以在企业、组织或仓库范围要求使用锁文件。其作用是阻止目标范围内含有 action 依赖、却没有接入锁文件的工作流运行。

它与校验任务解决的问题不同。强制策略保证目标工作流必须接入；校验任务则能在合并前告诉作者，工作流和锁文件已经不一致。后者仍有必要保留。

GitHub 建议先针对少量仓库和工作流试点，建立持续更新机制，再启用 Active 强制模式。文档还明确说明，Evaluate 模式仅在 GitHub Enterprise 可用，不能假设所有套餐都有同样的无阻断观察阶段。

对平台团队，本文建议将接入情况列为迁移检查项，特别关注共享工作流仓库、新建工作流和本地 action。强制策略的范围应跟随实际接入进度扩大，避免大量未接入的正常任务突然被阻断。

锁定 action，不代表锁住整个构建

即便所有受支持的 action 依赖都固定到了审查过的提交，工作流仍可能下载新的工具、安装浮动版本的软件包、使用更新后的 runner 镜像，或者从网络读取会变化的数据。

这些输入并不因 actions.lock 存在而自动固定。应用依赖仍需要自己的锁文件，容器镜像和下载产物需要相应的版本或完整性控制，构建环境也要有可追踪的记录。

同样，锁定的 action 依然可能存在漏洞，或在运行时执行不安全的命令。最小化 token 权限、限制凭证可用范围、审查不可信输入、保护工作流文件等措施，仍然需要保留。

因此，更准确的收益是提高 Actions 依赖解析的确定性，让依赖变化更容易审查与追踪。它是构建可重复性和供应链治理的一部分，不能独自证明构建完全可复现或绝对安全。

结语

Actions 工作流锁文件让可读的版本引用与精确执行的提交可以同时保留，也将传递 action 依赖和来源仓库身份纳入记录。对维护多套 CI 的团队，这比逐个检查浮动引用更便于管理。

当前仍是公开预览，格式、命令和行为都可能变化。稳妥的起点是选一个工作流，查看工具改了什么，确认跨仓库依赖和 allowlist 能否衔接，再补齐更新与审查机制。锁文件只有持续维护，才能让后续每次依赖变化都成为一次明确的决定。

参考来源

• GitHub Changelog：GitHub Actions workflow lockfiles in public preview，2026 年 10 月 14 日发布，本文近期选题及开放范围的主要来源。
• GitHub Docs：Workflow dependency lockfiles，锁文件结构、传递依赖、仓库身份与可复用工作流边界。
• GitHub Docs：Locking action dependencies in a repository’s workflows，生成步骤、引用迁移、allowlist 与更新方式。
• GitHub Docs：Enforcing lockfiles for action dependencies，试点、强制策略及校验流程。
• GitHub：gh-actions-lock，官方 CLI 扩展、预览限制和验证选项。本文依据 2026 年 10 月 15 日查阅内容整理，命令与行为以使用时的版本为准。