GitHub Actions CI 设置

创建 Workflow 文件

在仓库根目录创建 .github/workflows/release.yml 文件。

必需的 permissions 配置

permissions:
  id-token: write      # 用于签名证书（OIDC token）
  contents: write      # 用于创建 Release
  attestations: write  # 用于生成 Attestation

重要

• 这三个权限缺一不可，否则 Attestation 功能无法正常工作。
• permissions 关键字必须全部小写，GitHub Actions YAML 是大小写敏感的，写成 PERMISSIONS 或 Permissions 会导致 workflow 解析失败。

权限说明

权限	用途	必需
id-token: write	获取 OIDC token 用于签名	✅
contents: write	创建 Release 和上传文件	✅
attestations: write	生成并存储 Attestation	✅

触发条件设置

推荐使用 tag push 触发发布流程：

on:
  push:
    tags:
      - 'v*'  # 匹配 v1.0.0, v2.1.3 等格式

其他触发方式

# 手动触发（用于测试）
on:
  workflow_dispatch:
    inputs:
      version:
        description: '版本号'
        required: true

# 仅在特定分支的 tag
on:
  push:
    tags:
      - 'v*'
    branches:
      - main

基础 Workflow 结构

name: Build and Release

on:
  push:
    tags:
      - 'v*'

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

    steps:
      - uses: actions/checkout@v4

      # 你的构建步骤
      - name: Build
        run: |
          # 构建命令

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

      - name: Create Release
        uses: softprops/action-gh-release@v2
        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 状态。详见 Attestation 配置。

Runner 选择

Runner	适用场景
ubuntu-latest	通用构建、Node.js、Python 等
windows-latest	Windows 应用、.NET 等
macos-latest	macOS 应用、iOS 开发等

对于跨平台构建，可以使用 matrix 策略：

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}