GitHub Actions artifact attestations 怎样在工作流中生成 SBOM 证明

如果工作流已经能构建出二进制或容器，还想把依赖清单一起交给发布链路，推荐使用 GitHub 当前的 actions/attest@v4。它把指定产物和 SPDX 或 CycloneDX JSON 格式的 SBOM 绑定起来，生成带签名的 SBOM 证明；证明生成后，消费方仍需使用 GitHub CLI 或自己的治理流程进行验证。

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

SBOM 证明到底绑定了哪些对象

这里容易把三件事混成一件事：构建产物是被描述的对象，SBOM 是对依赖组成的声明，attestation 则是把二者关联起来并附带签名的证明记录。actions/attest 不负责替你生成完整 SBOM，工作流要先通过现有工具得到 SPDX 或 CycloneDX JSON，再把文件路径传给 sbom-path。

因此，SBOM 文件存在并不等于它已经被证明；只有它和明确的 subject 绑定后，消费方才有机会核对“这份依赖清单描述的是哪个产物”。

权限和输入参数要成对配置

可把最小片段放在“构建产物”和“生成 SBOM”之后。示例中的路径只是工作流约定，需替换成仓库实际输出位置：

permissions:
  # 允许动作用 OIDC 身份申请短期签名凭据
  id-token: write
  # 允许把 attestation 写入 GitHub 的证明存储
  attestations: write
  contents: read

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 构建产物
        run: make release
      - name: 生成 SPDX SBOM
        run: syft . -o spdx-json > sbom.spdx.json
      - name: 生成 SBOM 证明
        uses: actions/attest@v4
        with:
          # subject-path 必须指向已经生成的真实产物
          subject-path: ./dist/my-app
          # sbom-path 必须是 SPDX 或 CycloneDX JSON
          sbom-path: ./sbom.spdx.json

支持范围与旧 action 的迁移边界

当前写法优先使用 actions/attest@v4。它根据输入进入 SBOM 模式；不提供 sbom-path 时，动作可以处理默认的构建来源证明。旧的 actions/attest-sbom 并不是另一个长期演进的实现，而是兼容包装层，官方仓库已经提示迁移到 actions/attest。

仓库可见性也会影响可用范围：公开仓库可使用 artifact attestations；私有或内部仓库要按当前 GitHub 计划和文档确认支持条件，GitHub Enterprise Server 不在该 action 的支持范围内。不要只因为 YAML 能解析，就把证明能力当作所有仓库都可用。

如果还希望把资产写入 linked artifacts page，需要单独考虑 artifact-metadata: write，并按官方说明配置 push-to-registry 与 subject 标识。这个开关不是生成普通 SBOM 证明的必选项，最好不要为了“看起来完整”而默认打开。

生成之后，消费方还要做验证

证明生成成功只说明工作流创建了一个签名关联记录，不代表部署系统已经拒绝未证明的构建，也不代表 SBOM 内容自动经过人工审查。发布团队应把验证动作放在消费侧，例如用 GitHub CLI 的 attestation 命令核对产物与 SBOM 的关联，再把结果接入发布门禁。

排查时按三层看：先确认 subject-path 在证明步骤之前已经产生，再确认 sbom-path 是可读的 SPDX/CycloneDX JSON，最后确认权限和仓库计划允许写入证明。这样能把“文件没生成”“输入不是 SBOM”和“API 没权限”分开处理。

相关问题

只上传 SBOM 文件，能替代 SBOM attestation 吗？

不能完全替代。上传文件解决的是分发，attestation 解决的是把 SBOM 与指定 subject 建立可验证关联；两者可以同时存在。

actions/attest-sbom 还能不能继续用？

它目前仍可作为兼容包装层工作，但官方已建议迁移到 actions/attest。新工作流直接采用新 action，后续升级成本更低。

生成证明后就能阻止未签名镜像部署吗？

不能自动得到这个结果。还需要在消费方执行验证，并把验证结果接入发布或集群准入策略。