gh-actions-lock README

项目的 README,来自 github.com/github/gh-actions-lock。合并为一个 markdown 文件:README.md。

gh-actions-lock

A GitHub CLI extension that pins every direct and transitive action your workflows use to a verified commit, recorded in .github/workflows/actions.lock.

Install

Requires an authenticated gh. github.com and GitHub Enterprise Cloud with data residency (*.ghe.com) are supported; GitHub Enterprise Server is not.

gh extension install github/gh-actions-lock

To teach your AI coding agent the CLI:

gh skill install github/gh-actions-lock

Quickstart

From the repository checkout:

gh actions-lock            # onboard or fix: pin every resolvable action and write actions.lock
git add .github/workflows/ # check into source

Rerun gh actions-lock after adding a workflow or changing any uses:.

Make sure you don't check in a corrupt lockfile. Copy .github/workflows/verify-lockfile.yml into your repository, modify it for your needs, then run gh actions-lock once so that workflow is locked too.

GitHub Enterprise Cloud with data residency

Run gh auth login --hostname TENANT.ghe.com, then run gh actions-lock from the tenant repository checkout. The host comes from the repository remote; you don't need --hostname or an exported token.

Actions that aren't on the tenant, such as actions/checkout, are read from public github.com repositories. Those lookups never use the tenant token, GH_TOKEN or GITHUB_TOKEN. They use, in order:

  1. GH_ACTIONS_LOCK_GITHUB_COM_TOKEN, a github.com token used only for these lookups.
  2. Your gh auth login --hostname github.com login.
  3. Otherwise they're anonymous and share GitHub's limit of 60 requests an hour per IP address, which a shared proxy or runner pool can exhaust quickly.

In GitHub Actions on GHE.com, the job's GITHUB_TOKEN is issued by your tenant, so github.com doesn't accept it. Create a fine-grained personal access token on github.com with public repository access only and no permissions, save it as a secret on the tenant, and pass it in:

- run: gh actions-lock --verify
  env:
    GH_TOKEN: ${{ github.token }}
    GH_ACTIONS_LOCK_GITHUB_COM_TOKEN: ${{ secrets.ACTIONS_LOCK_GITHUB_COM_TOKEN }}

Modes

Command Writes Network Use for
gh actions-lock yes yes Onboarding and fixing the lockfile
gh actions-lock --relock yes yes Advancing moved refs (main, v4) to current upstream commits
gh actions-lock --verify no yes CI: the same checks as a fix run
gh actions-lock --verify-local no no Pre-commit: every uses: has a lockfile entry (coverage only, not provenance)
gh actions-lock --no-fix no yes Read-only report

Other flags:

gh actions-lock --help is authoritative.

Limitations

Learn more

Contributing

See CONTRIBUTING.md

Support

See SUPPORT.md.

License

Licensed under MIT.

gh-actions-lock (github/gh-actions-lock)

正在搜索数据库…

这是什么?这是一个 GitHub CLI 扩展,用于生成并验证 GitHub Actions 依赖锁文件。它会把工作流使用的每个直接和间接 action 都锁定到一个确定的提交上。
它是独立应用,还是插入 gh 使用的扩展?它作为扩展接入 gh CLI,以 gh actions-lock 的形式运行。运行结果会写入你仓库中的一个文件:.github/workflows/actions.lock。
我要怎么让它运行起来?先用 gh auth login 登录,再按照 README 的 Install 部分安装扩展,然后在你的仓库检出目录中运行 gh actions-lock。每次添加新工作流或修改任何 uses: 后,都需要重新运行一次。
我需要先准备什么吗?你需要一个已登录的 gh。它支持 github.com 和启用了数据驻留的 GitHub Enterprise Cloud,但不支持 GitHub Enterprise Server。
有什么需要注意的坑吗?有。容器镜像不会被锁定,从其他仓库调用的可复用工作流也不会被锁定。使用了远程 action 的本地 ./ action 会阻止运行,直到你加上某个参数。如果锁文件的改动把浮动引用退回到更早的提交,这种情况不会被检测到,所以要检查锁文件的差异。
没有网络能用吗?只有 --verify-local 可以离线运行,而且它只是一项覆盖性检查:确认每个 uses: 在锁文件中都有对应条目,但不验证来源可信性。
用它免费吗?免费。它采用 MIT 许可证,你可以在自己的项目中自由使用。
为什么把工作流锁定到提交很重要?像 v4 或 main 这样的标签可能会在你没有做任何改动的情况下被移动到新代码上。锁定到确定的提交,意味着运行的正是你审查过的代码,不过如果它被移回更早的提交,仍然无法被检测到。
--relock 是做什么的?它会把 main 或 v4 这类浮动引用推进到上游的当前提交。请谨慎使用,并在接受之前检查锁定的提交为什么发生了变动。
它会同时锁定其他 action 所使用的 action 吗?会。它会锁定每一个直接和间接的 action,所以你所用 action 的依赖也都在覆盖范围内。
我能只锁定一个工作流吗?可以,把工作流文件名传进去即可限定运行范围。只有全目录运行才会删除已被删除工作流对应的锁文件条目。
有哪些类似的项目?gh-aw, gh-secure, gitleaks, gitea, grype, farol, semgrep, bashka
作者
github
大小
3.8 MB
星标
385
时长
6个月
提交 · 90 天