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）是一个安全框架，定义了软件供应链的安全级别。

级别	配置方式	安全性	适用场景
Level 2	直接使用 attest-build-provenance	基础保护	内部工具、一般项目
Level 3	使用 reusable workflow	更高安全性	公开发布、安全敏感项目

Level 2 配置（推荐）

对于大多数内部工具，Level 2 已经足够：

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      attestations: write
    steps:
      - uses: actions/checkout@v4
      - run: npm run build
      - uses: actions/attest-build-provenance@v2
        with:
          subject-path: 'dist/*'

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 指南。

Attestation 存储

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

1. Release 页面 - 显示 "Verified" 标记
2. gh CLI - 使用 gh attestation verify 命令
3. API - 通过 GitHub REST API 查询

常见问题

Q: Attestation 生成失败

检查以下配置：

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

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

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