GitHub Actions lockfiles工作流锁文件能力解决什么依赖风险

GitHub Actions lockfiles 主要解决 action 引用在评审后发生漂移的问题：工作流里的标签或分支名称没有变化，上游指向的提交却可能已经变了。工作流依赖锁文件把已接入工作流使用的 action 固定到具体提交，让后续运行使用锁定的代码，并把依赖更新变成可评审的仓库差异。

GitHub 于 2026 年 10 月 28 日宣布 workflow dependency lockfiles 正式可用。它覆盖 action 的直接和传递依赖，但锁定不等于证明依赖安全，也不等于整个构建完全可复现。采用前应明确它控制的是哪一层输入。

官方地址：https://github.com/

工作流没改，依赖代码为什么会变

设想一个团队每天构建内部文档站，工作流通过某个 action 的主版本标签调用构建辅助逻辑。周一评审时，标签对应提交甲；周三上游维护者调整标签后，同样的工作流可能解析到提交乙。这是解释风险的假设场景，不是真实攻击或故障记录。

如果团队只审查本仓库的工作流文件，就很难从本地代码差异里看到这次变化。标签更新也可能只是正常发布，但它仍改变了执行代码。锁文件让“采用上游新提交”成为需要明确处理的依赖变更，减少运行时解析带来的意外。

这件事与应用包的锁文件相似，却有不同对象。项目中的 npm 或 Python 依赖记录，不能自动固定工作流使用的所有 action；而 .github/workflows/actions.lock 也不会代替应用自己的包管理记录。

先划清锁文件和权限的覆盖范围

官方概念文档说明，锁文件记录 action 引用对应的提交及来源仓库身份，并覆盖可解析的传递 action 依赖。这里的传递依赖，是 action 自身继续使用的其他 action；不能把它理解为任意 shell 下载、包安装或外部服务都被一并锁定。

权限与代码版本也应分别审查。一个 action 即使提交没有变化，给它更多仓库写权限或部署凭据，仍会改变可产生的影响。实践上可先把生成锁文件放到维护者的开发环境，在接入后的工作流中保留任务真正需要的权限；不要因为“已经锁定”就扩大密钥暴露范围。

先接入一条工作流，再评审生成差异

接入前先确认 uses 指向团队愿意采用的版本。锁文件生成器会基于当前引用解析提交，因此它不能替你判断某个未知 action 是否值得信任。可以先选择一条构建工作流试点，再扩展到部署和共享工作流。

# 前提：已安装并登录GitHub CLI；在目标仓库根目录操作
gh extension install github/gh-actions-lock

# 先接入现有ci.yml；文件名须替换为仓库实际工作流
gh actions-lock .github/workflows/ci.yml

# 同时查看工作流与机器生成锁文件的差异，不手写锁定提交
git diff -- .github/workflows/

这些命令是供读者使用的示例，本文没有在任何仓库安装扩展或执行工作流。官方工具还可能把较宽泛的版本引用改写为解析到的更具体版本，所以评审不能只盯着 actions.lock 一个文件。

若工作流调用其他仓库的共享工作流，应把维护边界落实到来源仓库。调用方的锁文件不会替来源仓库锁定内部 action。一个合理的团队安排是先处理共享仓库，再逐步接入使用它的业务仓库，避免调用方误以为所有内部依赖已经覆盖。

把新增依赖与锁定更新放在同一次评审

首次接入之后，维护任务并未结束。新增工作流、增加 action 或调整引用时，应重新生成锁文件，把对应差异放在同一个变更中。这样评审者可以同时看到“为何增加能力”和“将运行哪个提交”，而不是等流水线失败后才补记录。

# 工作流依赖变更后重新生成，覆盖仓库内的工作流
gh actions-lock

# 这是可在CI使用的只读检查方式；需要相应的认证与网络访问
gh actions-lock --verify

组织可以结合 Require lockfile 策略要求接入。具体是否在每个 PR 执行只读检查、由谁处理失败，以及何时允许变更进入部署分支，应依据团队权限与发布流程安排。不能只安装扩展，却不指定后续维护负责人。

对于已接入的工作流，官方说明 Dependabot 的 action 版本更新会同步更新相应锁记录。团队仍要审查该 PR：自动生成解决的是记录同步，不是自动批准依赖代码。未接入工作流也不能凭其他工作流存在锁记录就算覆盖。

遇到漂移和失败，保留证据再处理

第一类是引用移动。官方扩展区分了分支、宽泛版本标签和完整版本标签的行为；不要看见锁记录没有前进，就直接认为工具失效。若确实要采用上游新提交，应先看上游历史和变更原因，再决定是否使用 --relock 推进锁定。

更需要谨慎的是历史重写。锁定提交不再属于记录引用的历史时，单纯重新锁定不一定能处理。官方明确要求使用 --accept-moved 前调查原因，并且不要在自动化里使用该选项。把这类异常交给维护者判断，比每次失败都自动接受新状态更符合锁文件的目的。

第二类是策略不匹配。工作流接入后，允许 action 的策略会按锁定提交判断。原先按标签设置的精确允许项可能不再匹配，因此上线接入变更前应由策略负责人检查对应规则。第三类是认证、网络或解析问题，它们需要依据具体错误处理，不能靠删除锁文件或手改提交绕过去。

对本地路径 action 也要单独确认：./ 指向 runner 工作区内容，不能简单当作远程 action 锁定。官方工具提供相应迁移与处理选项；采取哪一种，应先理解它与工作流自身提交之间的关系，而不是只为了让生成命令结束而忽略提示。

复盘时同时记录代码、权限与外部输入

如果文档站构建在接入后仍出现差异，可以按三个问题复盘：锁定 action 的提交有没有变、执行权限与参数有没有变、运行器及其他下载内容有没有变。这样能避免把锁文件范围外的变化误判为锁定机制失效。

• 为 action 更新保留上游变更依据和对应锁记录。
• 把共享工作流的调用固定方式与来源仓库维护责任写清楚。
• 检查新增工作流是否已经接入，不只检查锁文件是否存在。
• 为引用异常、策略阻断与认证网络错误指定处理人。
• 保留必要的权限限制和其他依赖管理，按对象解释可重复性。

用了锁文件，还需要审查 action 吗？

需要。锁定可以让执行版本更稳定，却不能把存在问题的代码变成安全代码。首次采用和后续更新都需要相应评审。

它能让所有历史构建结果完全一样吗？

不能仅凭锁文件得出这个结论。相同 action 提交之外，还可能有不同的输入、包版本、外部服务和运行环境。

是否必须一次接入仓库全部工作流？

不必。官方支持逐条接入。可以先选择依赖清晰的一条试点，明确更新责任和失败处理，再扩大范围。

官方资料：https://github.blog/changelog/2026-10-28-github-actions-workflow-lockfiles-are-generally-available/；https://docs.github.com/en/actions/concepts/security/workflow-dependency-lockfiles；https://docs.github.com/en/actions/how-tos/secure-your-work/lock-workflow-dependencies；扩展仓库 https://github.com/github/gh-actions-lock。