Artifact Attestation 配置

Artifact Attestation 是 GitHub 提供的软件供应链安全功能，可以为构建产物生成加密签名的来源证明。

使用 attest-build-provenance Action

- name: Attest Build Provenance
  uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'dist/*'

参数详解

参数	说明	示例
subject-path	需要签名的文件路径（必需）	dist/app.exe, dist/*
subject-name	可选，自定义名称	my-app
push-to-registry	是否推送到容器注册表	true/false

文件路径模式

单个文件

- uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'dist/app.exe'

使用通配符

- uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'dist/*'

多个文件（多行指定）

- uses: actions/attest-build-provenance@v2
  with:
    subject-path: |
      dist/app-windows.exe
      dist/app-macos
      dist/app-linux

递归匹配

- uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'dist/**/*.zip'

SLSA 安全级别

SLSA（Supply-chain Levels for Software Artifacts）是一个安全框架，定义了软件供应链的安全级别。

平台判定 ≠ GitHub 的 Verified 标记

Release 页面的 "Verified" 标记只表示 GitHub 能查到一条 attestation 记录——这是 L0 级别。本平台执行的是严格 L2 校验：除了 "存在 attestation"，还要对 SLSA Provenance v1.0 的 predicate 做源仓库 / builder / uploader / ref 四项交叉校验，全部满足才判通过。看到 GitHub "Verified" 不等于在本平台通过。

级别	校验内容	对应口径
Level 0（GitHub Verified）	只看是否存在 attestation 记录	本平台不再按此判定
Level 2（本平台判定）	下面五项全过才算通过	所有新审核软件
Level 3	用 reusable workflow 隔离构建环境	可选增强，不是平台必须

Level 2 的五项校验（本平台严格要求）

checkAttestation 对最新 Release 的每个 asset 执行以下五项，全部满足才判 verified: true：

1. asset 的 SHA256 在 GitHub Attestation API 查得到；
2. predicate.buildDefinition.externalParameters.workflow.repository 等于 https://github.com/{owner}/{repo}；
3. predicate.runDetails.builder.id 等于 https://github.com/actions/runner/github-hosted；
4. Release 全部 asset 的 uploader.login 等于 github-actions[bot]（任一人工上传即整体失败）；
5. predicate.buildDefinition.externalParameters.workflow.ref 等于 refs/tags/{release.tag_name}。

任一项不满足都会被分类成 7 档 failureReason 之一（uploader_not_bot / no_attestation / bundle_decode_failed / predicate_version_unsupported / source_mismatch / builder_untrusted / ref_mismatch），完整规则见 README §"安全检查机制 → 3. Attestation"。

可直接复制的 L2 兼容模板

下面是满足五项校验的最小 workflow：

name: Release

on:
  push:
    tags:
      - 'v*'   # 约束 5：ref 必须是 refs/tags/*

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      attestations: write

    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Attest Build Provenance
        uses: actions/attest-build-provenance@v2
        with:
          subject-path: 'dist/*'   # 约束 1：subject 指向最终产物

      - name: Create Release
        uses: softprops/action-gh-release@v2  # 约束 3 + 4：由 action 上传，uploader=bot
        with:
          files: dist/*
          generate_release_notes: true

L2 Attestation 校验要求

为通过平台的严格 L2 Attestation 校验，workflow 必须满足：

1. 由 tag push 触发（on: push: tags: ['v*']），不要用 release: { types: [published] } 或 workflow_dispatch
2. 使用默认 GITHUB_TOKEN 上传 Release（不要用个人 PAT，否则 uploader 不是 github-actions[bot]）
3. 使用 softprops/action-gh-release 或等效 action 上传产物（不要人工在 GitHub UI 拖拽上传）
4. attest-build-provenance 的 subject-path 必须指向最终发布的产物文件（而非源码目录或中间产物）

任一项不满足，平台 L2 校验会以 uploader_not_bot / ref_mismatch / source_mismatch 等原因判失败，软件会进入 updateBlocked 状态。

Level 3 配置（可选增强）

Level 3 通过 reusable workflow 隔离构建环境，为更敏感的项目提供更高安全性：

# .github/workflows/release.yml
jobs:
  build:
    uses: ./.github/workflows/build-reusable.yml
    permissions:
      id-token: write
      contents: write
      attestations: write

详细配置请参考 GitHub 官方 SLSA Level 3 指南。Level 3 workflow 同样需要满足上述 L2 四项约束。

Attestation 存储

生成的 Attestation 会自动存储在 GitHub 的 Attestation 存储服务中，可通过以下方式访问：

1. Release 页面 - 显示 "Verified" 标记（仅表示 GitHub 查到记录，不等于本平台通过 L2）
2. gh CLI - 使用 gh attestation verify 命令
3. API - 通过 GitHub REST API 查询

常见问题

Q: Attestation 生成失败

检查以下配置：

• permissions 是否包含所有三个必需权限
• Action 版本是否为最新（推荐 v2）
• 文件路径是否正确

Q: 如何为已有 Release 补充 Attestation？

需要重新触发构建流程。建议创建新的 patch 版本（如 v1.0.1）。