开源项目维护者安全怎样设计发布权限的最小授权流程怎样完成一个可复用的最小示例

开源项目最容易被忽略的发布风险，不是“有没有一把密钥”，而是构建、打包、上传和创建 Release 是否共用了一把过大的钥匙。更稳妥的做法是：默认关闭令牌权限，构建任务只读，只有绑定受保护环境的发布任务拿到必要的写权限；需要云端上传时，再用带仓库、标签和工作流条件的 OIDC 换取短时凭据。

官方资料入口：https://openssf.org/；GitHub Actions 安全文档：https://docs.github.com/en/actions/how-tos/secure-your-work

下面的示例适合维护者先做权限盘点，再按项目实际资源替换发布命令。它不是某个云厂商的完整部署脚本，重点是权限边界。

先把构建和发布拆成两种权限

我会先把工作流级权限设为空，再在 job 级别逐项加回。这样新增步骤时不会悄悄继承一组过宽的默认权限。构建阶段通常只需要读取代码和生成本地制品；创建 GitHub Release 才需要 contents: write。

name: release

on:
  push:
    tags: ["v*"]

# 先关闭默认权限，新增步骤必须显式说明需要什么。
permissions: {}

jobs:
  build:
    runs-on: ubuntu-latest
    # 构建只读取仓库，不应拥有创建 Release 的能力。
    permissions:
      contents: read
    steps:
      # 生产环境请替换为已经审阅并固定的完整提交 SHA。
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - name: 构建并保存制品
        run: |
          # 这里放项目自己的构建命令，产物交给后续发布 job。
          make release-artifacts

  publish:
    needs: build
    runs-on: ubuntu-latest
    # 环境保护规则通过后，job 才能继续使用发布权限和环境 secrets。
    environment:
      name: release
    permissions:
      contents: write
      # 只有确实需要云端 OIDC 时才开启这一项。
      id-token: write
    steps:
      - name: 创建 Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # 版本号来自受控的 tag，避免从不可信输入拼接发布目标。
          gh release create "${GITHUB_REF_NAME}" --generate-notes

图1：发布权限边界说明图，构建只读，发布写入，并把高权限 job 放进受保护环境。

这里的关键不是把 contents: write 写得更漂亮，而是让它只出现在发布 job。GitHub 文档说明，显式设置 permissions 后，未列出的权限会变成 none；OpenSSF 的 OSPS Baseline 也把“作业只获得对应活动所需的最小权限”作为更高成熟度的控制项。

把 release 环境当成第二道门

令牌最小化后，还要限制“谁能触发高权限 job”。在仓库的 release 环境中配置必需审查者，并把允许部署的分支或标签限制到正式发布范围。这样，工作流文件即使被改动，也不能仅凭一次普通分支运行就拿到环境 secrets。

维护者可以把规则写进发布清单：发布 job 是否只能由版本标签触发？环境是否只允许主仓库的发布分支或标签？必需审查者是否与编写代码的人分离？失败后是否能撤销或轮换环境凭据？这些问题比“有没有加一层 if”更接近真实的授权边界。

用 OIDC 把云端授权限制到发布环境

如果制品还要上传到云存储或云端制品库，不建议把长期云密钥直接放进仓库。GitHub OIDC 允许 job 请求短时身份令牌，但云端 trust policy 必须至少有条件。一个可复用的条件组合是：固定仓库、固定 release 环境，再固定发布工作流引用；若项目按标签发布，还要把可接受的 ref 纳入约束。

permissions:
  contents: read
  # 仅用于向云身份提供方请求 OIDC JWT，不代表云资源写权限。
  id-token: write

env:
  # 云端 trust policy 应与仓库、环境和工作流引用逐项对应。
  RELEASE_SUBJECT: repo:ORG/REPO:environment:release

steps:
  - name: 获取短时云凭据
    run: |
      # 真实项目应调用云厂商官方登录 Action，并固定到已审阅的提交 SHA。
      # 云端角色只授予目标制品路径的写权限，并设置较短有效期。
      echo "只允许受 release 环境保护的工作流交换短时凭据"
  - name: 上传制品
    run: |
      # 上传范围限定到当前版本目录，不授予删除整个存储桶的能力。
      ./scripts/upload-artifact --prefix "releases/${GITHUB_REF_NAME}/"

图2：OIDC 信任边界说明图，仓库来源和环境条件共同决定短时角色能做什么。

注意 id-token: write 只允许请求 OIDC JWT，不会自动给云资源写权限；真正的权限仍由云端角色和 trust policy 决定。条件写得越具体，错误触发或其他仓库复用这条信任关系的空间越小。

维护者最容易漏掉的三个边界

第一，别让不可信 PR 代码进入高权限上下文。尤其不要让来自 fork 的代码在拥有 secrets 或读写令牌的流程中直接执行。测试和发布应拆开，发布只接受已经合并、打过标签并通过保护规则的来源。

第二，别只盯着 token。第三方 Action 的 tag 可以移动，生产工作流应固定到完整提交 SHA，并由维护者定期升级。需要写 Release、Packages 或部署资源时，分别确认是不是每一项都真的需要写权限。

第三，别把最小授权做成一次性配置。每次加入新步骤，都记录它访问的资源、所需权限、负责人和回收方式。成员离开、发布仓库迁移或云端角色变更后，重新检查 OIDC subject、环境审查者和仓库 ID 条件是否仍然匹配。

小结：一条可复用的发布权限清单

可以把流程压缩成四句话：工作流默认 permissions: {}；构建 job 只读；发布 job 才写入且必须经过 release 环境保护；云端上传使用有具体条件的 OIDC 短时角色。再配合 MFA、固定 Action 提交和发布审计记录，维护者就能把“谁能发布”从口头约定变成可检查的边界。

相关问题

为什么不直接给整个工作流 contents: write？因为工作流里的每个步骤都会处在同一组令牌权限下，构建、测试或第三方 Action 出问题时，影响面更大。

OIDC 是否等于不需要云端权限管理？不是。OIDC 只改变身份交换方式，云端 trust policy 和角色权限仍需按仓库、环境、工作流和目标资源分别收窄。