GitHub Actions 现已正式支持工作流锁文件（Workflow Lockfiles）。这一功能的推出旨在解决此前依赖标签引用时面临的供应链攻击风险。
由于 GitHub Actions 直接从 Git 仓库获取代码，业界长期建议开发者使用完整的提交 SHA（哈希值）而非版本标签进行引用。这是因为标签具有可变性，攻击者可能通过篡改标签指向恶意代码，从而实施供应链攻击。
在采用新机制前，典型的安全配置如下所示，工作流步骤中直接硬编码了具体的 Commit SHA：
name: Lint
on: [push, pull_request, workflow_dispatch]
permissions: {}
env:
FORCE_COLOR: 1
RUFF_OUTPUT_FORMAT: github
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
安装与配置流程
启用该功能需将 gh-actions-lock 扩展安装至 GitHub CLI (gh)。执行以下命令即可完成安装：
$ gh extension install github/gh-actions-lock
✓ Installed extension github/gh-actions-lock
安装完成后，在目标仓库根目录下运行锁定命令：
$ gh actions-lock
✓ All 1 workflows valid
执行后，工作流文件中的引用将从长串 SHA 简化为 vX.Y.Z 形式的标签，同时生成对应的锁文件。变更示例如下：
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 946971c..3503607 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -13,7 +13,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- - uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
+ - uses: j178/prek-action@v3.1.0
系统会在 .github/workflows/actions.lock 路径下自动生成锁文件，记录所有依赖的具体版本、Commit SHA 及仓库 ID 等信息：
# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
'.github/workflows/lint.yml':
- 'actions/checkout@v7.0.1'
- 'j178/prek-action@v3.1.0'
dependencies:
'actions/checkout@v7.0.1':
ref: 'v7.0.1'
commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
owner_id: 44036562
repo_id: 197814629
'j178/prek-action@v3.1.0':
ref: 'v3.1.0'
commit: 'sha1-44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d'
owner_id: 10510431
repo_id: 1052387486
最后，需将修改后的工作流文件与新生的锁文件一同提交至版本控制系统。
自动化更新与兼容性
现有的自动化工具如 Renovate 和 Dependabot 均已适配新的锁文件机制。当这些工具定期更新依赖时，会自动同步更新锁文件内容。开发者需注意配置合理的冷却时间以平衡更新频率与稳定性。
CI 环境下的验证机制
为确保锁文件未受损且与工作流保持同步，GitHub 建议在持续集成（CI）流程中加入验证步骤。可通过复制官方推荐的 lockfile.yml 或将其整合至现有工作流程来实现。
以下示例展示了如何在 Lint 工作流中增加独立的验证 Job，使用轻量级的 ubuntu-slim 运行器，并明确指定扩展版本为 v0.4.1：
name: Lint
on: [push, pull_request, workflow_dispatch]
permissions: {}
env:
FORCE_COLOR: 1
RUFF_OUTPUT_FORMAT: github
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: j178/prek-action@v3.1.0
# Fails when .github/workflows/actions.lock is out of sync with the
# workflows or a locked pin no longer verifies upstream.
lockfile:
runs-on: ubuntu-slim
env:
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- run: gh extension install github/gh-actions-lock --pin v0.4.1
- run: gh actions-lock --verify
若后续新增独立的工作流文件（如 validate-lockfile.yml），则需再次运行 gh actions-lock 以重新生成或更新锁文件。
静态分析工具 Zizmor 的支持
Zizmor 是一款针对 GitHub Actions 的安全静态分析工具（Linter）。自 v1.32.0 版本起，Zizmor 开始原生支持锁文件机制；在此之前的版本仅能提示哈希引用信息。
对于使用 prek 作为预提交钩子管理器的项目，可在 .pre-commit-config.yaml 中添加或更新 Zizmor 配置：
- repo: https://github.com/zizmorcore/zizmor-pre-commit
rev: v1.32.0
hooks:
- id: zizmor
完成上述配置并提交更改后，即可实现工作流引用的完整锁定与安全验证。
应用案例
目前已有多个知名开源项目采用了此方案，包括：
- python-pillow/pillow (#10428)
- python/release-tools (#477)
- ms-islington (#758)
- python/cpython (#161811)
