GitHub Actions artifact attestations 如何落地：从构建产物到验证链的工程边界

团队把 release.zip 上传到制品库，并不等于使用者知道它是怎么构建出来的。GitHub Actions 的 artifact attestations 给这件事补上了一条可验的证据链：工作流对构建产物的 SHA-256 摘要签名，随后用 GitHub CLI 检查仓库、工作流和提交来源。它适合解决“这个文件是不是从指定仓库的指定流程产出”的问题，不负责证明程序本身没有漏洞。

最小可用做法是：构建后固定产物摘要，使用 actions/attest 生成 provenance，再用 gh attestation verify 按仓库身份和摘要核验；权限、摘要和验证主体缺一不可。

artifact attestations 解决的是哪一段信任问题

发布链通常分成三段：源代码进入工作流，工作流产出文件，用户下载并运行文件。传统的 SHA-256 校验只能回答“下载后有没有被改动”，回答不了“它是不是由这个仓库的这个工作流构建”。Artifact attestation 是一份由 GitHub Actions 生成的加密声明，把构建来源与产物摘要绑定起来。

GitHub 官方文档把 provenance attestation 和 SBOM attestation 分开说明。前者描述构建来源，后者描述软件成分。两者可以同时存在，但验 provenance 时不能把 SBOM 当成来源证明。

最小工作流需要哪些权限和输入

下面的片段只展示关键边界。实际项目仍要把构建、测试、发布拆成自己的 job，并让产物名称和下载路径保持稳定：

permissions:
  id-token: write
  contents: read
  artifact-metadata: write

steps:
  - uses: actions/checkout@v4
  - name: Build release.zip
    run: ./scripts/build-release.sh
  - name: Attest release.zip
    uses: actions/attest@v2
    with:
      subject-path: release.zip
      predicate-type: https://slsa.dev/provenance/v1

id-token: write 让工作流取得用于签名链的身份令牌，contents: read 支持检出代码，artifact-metadata: write 允许上传与构建产物关联的元数据。权限不宜直接改成全局写入；把范围放在单个发布工作流里，审查时更容易知道是谁可以产生证明。

GitHub 当前文档也给出了显式摘要的场景：如果被证明的主体不是工作流刚生成的文件，可以把 subject-digest 写成 sha256:HEX_DIGEST。摘要必须来自实际文件，不能把版本号、文件名或 Git 提交短哈希当作摘要替代。

验证时要把产物、仓库和工作流一起锁定

构建端成功并不代表消费端已经验证。对下载到本地的 release.zip，先计算摘要，再交给 GitHub CLI：

DIGEST=$(sha256sum release.zip | awk '{print $1}')
gh attestation verify release.zip \
  --repo example/acme-service

验证命令的重点不是复制一行命令，而是确认它检查的主体。仓库参数要指向允许发布的仓库；如果组织还有多个发布工作流，就继续按文档支持的工作流或来源字段收紧条件。验证输出里的仓库、工作流、提交和产物摘要应与发布记录逐项对应。

迁移旧 action 时别把“能跑”当成“边界没变”

actions/attest-build-provenance 的官方仓库说明指出，现有应用可以继续使用旧 action，但新实现应优先采用 actions/attest。迁移时需要重新核对输入名称、权限、输出和验证命令，尤其要检查容器镜像是否使用了正确的 digest，而不是可变 tag。

一个稳妥的迁移顺序是先在非发布分支生成证明，保存验证输出和摘要；再让发布 job 以同一份产物做验证；最后才把“验证失败即阻断发布”接入保护规则。这里别急着把所有历史构建都强制回溯，旧产物可能根本没有关联的证明。

它不能替代哪些安全控制

Provenance 证明的是构建关系，不是质量认证。它不能替代依赖漏洞扫描、恶意代码检测、SBOM 审查、密钥轮换、人工发布审批，也不能保证构建脚本没有被恶意修改。对高风险发布，建议把 attestation 验证放在已有的制品扫描之后，并把仓库分支保护和环境审批作为另一道独立控制。

证明本身也有生命周期。GitHub 文档提醒，删除 attestation 后，依赖它的消费者将无法继续按原记录查找和验证。因此，清理仓库或重做发布策略时，要先确认消费方是否保存了离线副本，以及失败时是否有明确的回滚产物。

常见问题

artifact attestation 是不是文件签名的替代品？

不是。它把产物和构建来源关联起来；文件签名、分发渠道校验和运行时策略仍然各自承担不同责任。

为什么只写 subject-path 还要关心摘要？

路径只说明工作流要证明哪个文件，摘要才把证明绑定到具体字节。文件在后续步骤被覆盖时，必须重新生成或重新核对证明。

旧的 attest-build-provenance action 能立即删除吗？

不建议直接删除。先按官方迁移说明在独立分支验证新 action 的权限和输出，再逐个切换发布工作流。

验证成功就能说明没有供应链风险吗？

不能。它只增加来源证据，还需要结合依赖扫描、代码审查、分支保护和发布审批判断整体风险。

把证明接入发布门禁的最小清单

• 构建成功后记录文件或镜像的 SHA-256，不使用可变 tag 代替 digest。
• 只给发布工作流授予生成证明所需权限，并审查环境审批。
• 消费端固定允许的仓库、工作流和提交范围，保存验证输出。
• 证明失败时停止发布，保留摘要、日志和失败原因，便于回滚和复盘。

GitHub 的官方概念文档、操作指南和 actions/attest 仓库都把 artifact attestations 定位在构建来源与制品关联上。工程上真正有价值的落点，是把这份来源证据放进已有发布门禁，而不是把它当成一个孤立的绿色勾选。