锁定存储库工作流中的 GitHub Actions 依赖项

生成一个锁文件，用于将工作流使用的每个操作固定到已验证的提交，并在依赖项更改时保持最新状态。

谁可以使用此功能？

People with write access to a repository

GitHub Enterprise Cloud

在本文中

注意

工作流依赖项锁文件位于公开预览中，并且可能会更改。

锁定工作流的依赖项可确保引用的操作包含最初审阅的相同代码。 有关详细信息，请参阅“工作流依赖项锁定文件”。

1. 检查操作参考

创建锁文件会根据当前分支或标记引用将依赖项固定到提交。 请确保这些是您要固定的版本。

检查工作流中的每个uses引用是否指向受支持的当前版本的操作。 有关最佳做法，请参阅 安全使用指南。

如果任何工作流调用另一个存储库中的可重用工作流，也请检查这些引用。 可重用工作流的依赖项由定义可重用工作流的存储库的锁文件涵盖。 如果你的组织维护共享工作流，我们建议先接入这些代码仓库。 请参阅“重用工作流配置”。

建议允许 Dependabot 管理 GitHub Actions 依赖项。 如果尚未启用，请在创建 lockfile 之前启用它。 请参阅“使用 Dependabot 保持操作的最新状态”。

2.安装 actions-lock 扩展

  1. 安装GitHub CLI。

  2. 安装扩展。

    Bash
    gh extension install github/gh-actions-lock

提示

若要稍后更新扩展，请运行 gh extension upgrade gh-actions-lock。

3. 生成锁文件

从存储库的根目录中，不带任何参数运行该扩展。 它将扫描 .github/workflows/ 下的每个工作流，将每个可解析操作固定到提交 SHA，并写入 lockfile。

Bash
gh actions-lock

若要导入单个工作流而不是整个目录，请指定其路径。

Bash
gh actions-lock .github/workflows/ci.yml

如果扩展报告其已因不支持本地路径操作而跳过某个工作流，这意味着该工作流中的一个 uses: ./… 引用未解析为实际操作文件。 本地路径从存储库根目录解析，而不是从包含它们的文件所在的目录解析，因此，看起来相对于其所属文件正确的路径也可能无法解析。 更正路径并再次运行命令。

对于完整的选项集，请运行 gh actions-lock --help。

4.查看更改并提交

该扩展所做的更改不止锁定文件，因此请在提交之前查看完整的差异。 它还将你的工作流中对 uses 的引用改写为其解析到的特定版本，因此，此类 octo-org/deploy-action@v3 引用可能会变为 octo-org/deploy-action@v3.1.0。 这使得引用更具体，而不改变其解析到的提交。

如果存储库、组织或企业仅允许指定操作，请在提交前检查允许列表。 工作流接入后，将针对锁定的提交 SHA 检查允许列表，因为标记可以移动到不同的代码，但锁定的 SHA 无法。 固定到标签的条目（例如 actions/checkout@v6）不再匹配。 请改用通配符或完整的提交 SHA。 请参阅“管理存储库的GitHub Actions设置”。

在工作流和存储库内的 uses: $/… 文件中，对你自己的存储库中的操作的引用也会从 action.yml 重写为对应的 uses: ./…。 $/…引用始终解析为正在运行的提交，因此它本质上是固定的，不需要锁文件条目。

5. 使锁文件保持最新状态

使锁定文件与存储库的工作流文件和安全更新保持同步。

  1. 更改依赖项时重新运行扩展。 每当添加具有uses依赖项的工作流，或在现有工作流中添加或删除gh actions-lock依赖项时，请再次运行uses。

  2. 让 Dependabot 处理版本升级。 Dependabot 为你已启用的工作流中的操作打开版本更新时，它还会在同一个拉取请求中重新生成匹配的锁文件条目，因此工作流文件和锁文件不会发生偏离。

Dependabot 不会为你启用工作流。 如果它在工作流中更新了某个在锁文件中没有条目的依赖项，则只会报告需要进行初始化配置。

  1. 重新解析已移动的引用。 对分支或部分版本的引用（例如 main 或 v3）被视为来自锁文件的可信引用，在正常运行时不会重新解析。 如果扩展报告错误，因为标记现在指向不同的上游提交，请先检查上游存储库的历史记录。 如果移动是合法的，请使用 gh actions-lock --relock 重新解析引用。 如果最初锁定的提交已完全不可达，例如上游存储库强制推送或删除了它，--relock 仍将报告错误。 若要接受新提交，请运行 gh actions-lock --relock --accept-moved。

查看锁文件更改

查看锁文件更改，就像任何其他依赖项更改一样：

  • 已更改的内容 commit 是工作流将运行的代码。 按照对待任何其他依赖项版本的方式处理它。
  • 已更改的owner_id或repo_id 应很少见。 这意味着该名称对应的存储库 不是 你最初锁定的那个存储库，因此请在合并之前进行调查。

如果锁定文件看起来不正确，请修复工作流文件并重新生成它。 切勿手动编辑锁文件。

后续步骤

为存储库生成锁文件后，请确保它被强制执行并保持最新状态，而无需开发人员记住运行命令。 请参阅“为操作项依赖项强制实施锁文件”。