开源项目维护者安全怎样设计发布权限的最小授权流程为什么结果为空或不符合预期

我第一次把开源项目的发布流程交给自动化时，最容易犯的错不是忘记加一个权限，而是给了一个“什么都能做”的令牌。构建、测试、打包和发布共用同一份写权限，平时看起来省事，真正出问题时却很难回答：到底是谁创建了标签，哪个任务能改仓库，为什么发布结果是空的？

更稳妥的做法是把发布拆成独立的受控动作：普通 CI 默认只读，构建产物先保存，只有满足规则的发布任务才获得目标范围内的写权限。GitHub 官方也建议给 GITHUB_TOKEN 只授予完成当前任务所需的最小权限；OpenSSF 的安全实践同样把访问控制和最小授权放在维护流程的基础位置。

官方地址：https://openssf.org/

GitHub 权限说明：https://docs.github.com/en/actions/tutorials/authenticate-with-github_token

先把“发布”拆成三种不同权限

维护者安全的第一步不是马上改 YAML，而是列出动作和对象。提交代码需要写入分支，构建通常只需要读取仓库并上传临时产物，正式发布可能需要创建标签、创建 Release 或发布包。这三类动作的风险完全不同。

这张表的关键不是权限名称，而是权限和对象一一对应。一个只负责测试的 job 不应该因为“以后可能要发布”而提前拥有标签写权限。

把 GITHUB_TOKEN 默认权限降到只读

我更愿意从工作流的顶层先关小权限，再在单个 job 里按需打开。这样新加的步骤不会意外继承一整套写权限。

name: release

# 顶层默认只读，避免新 job 继承不必要的写权限
permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    # 构建只读取源码并上传临时产物，不创建标签或 Release
    permissions:
      contents: read
      actions: read
    steps:
      - uses: actions/checkout@v4
      - name: 构建并上传产物
        run: |
          # 这里放项目自己的构建命令，失败时让 job 立即停止
          make release-artifacts

  publish:
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    # 只有人工确认的发布 job 才获得创建 Release 所需的写权限
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - name: 创建发布
        run: |
          # 发布前应再次确认版本号和产物已被上一步传递
          ./scripts/publish.sh

这里的 contents: write 只是示例边界，不代表所有项目都需要它。如果发布目标是包仓库，应该只打开对应的包权限；如果使用 GitHub App，也应把仓库和资源限制到发布所需范围。不要为了让流程“先跑起来”把顶层改成全写。

用分支和标签规则集卡住发布入口

令牌权限小了，发布仍可能被错误的分支或标签触发。因此我会把保护对象从默认分支延伸到发布标签。GitHub Rulesets 可以分别针对分支和标签设置规则，也可以限制谁能绕过规则。

官方规则集地址：https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets

1. 为默认分支要求 Pull Request、必要的检查和至少一名合适的审阅者。
2. 为版本标签设置命名模式，例如只允许符合项目版本约定的标签。
3. 把绕过权限给专用团队或 GitHub App，避免把管理员权限扩散给所有维护者。
4. 发布任务只接受受控事件或人工触发，不把不可信 Pull Request 的上下文直接带进写操作。

规则集的作用是把“谁可以做”与“什么内容可以做”分开。即便某个账号拥有一般维护权限，也不应该天然获得任意标签的创建、删除和绕过能力。

让发布凭据只服务一个动作

如果默认令牌无法完成发布，不要立刻换成一个长期有效的个人访问令牌。更好的顺序是先确认发布究竟需要创建标签、创建 Release，还是写入包仓库，然后为这个动作准备专用凭据。

jobs:
  publish:
    permissions:
      contents: read
    steps:
      - name: 使用专用发布凭据
        env:
          # 密钥只在当前步骤注入，脚本结束后不再出现在后续步骤环境中
          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
        run: |
          # 脚本内部只调用目标发布接口，不把令牌写入日志
          ./scripts/publish.sh --token "$RELEASE_TOKEN"

这个示例强调的是边界而不是某个具体命令。凭据应限制到目标仓库和目标资源，能用 GitHub App 安装令牌或细粒度令牌时，不要继续使用覆盖多个仓库的旧令牌；能让发布任务手动批准时，也不要把发布权限授予每一个测试任务。

为什么发布结果为空：按四个症状定位

“结果为空”通常不是一个原因。我排查时会先看发布 job 是否真的进入了写路径，再按下面四类线索缩小范围：

• 权限范围：日志出现资源不存在、无权创建或 API 返回拒绝，先检查 job 级 permissions 和令牌实际类型。
• 规则集阻断：令牌有效但标签或分支更新被拒绝，查看目标引用的规则集、绕过名单和必需检查。
• 事件上下文：工作流在 Pull Request 或外部贡献者事件中运行，条件表达式可能让发布 job 被跳过，或者安全策略不允许把写令牌交给不可信代码。
• 产物交接：构建 job 成功不等于发布 job 拿到了文件。检查产物名称、下载步骤和版本号是否一致。

可以在工作流中保留不包含秘密的上下文信息，帮助判断 job 是否被跳过：

# 只打印非敏感上下文，避免把令牌和秘密带进日志
echo "event=${GITHUB_EVENT_NAME} ref=${GITHUB_REF} actor=${GITHUB_ACTOR}"

# 用明确的文件存在性判断区分“构建没产物”和“发布权限不足”
test -s dist/release.tar.gz || {
  echo "发布产物不存在或为空" >&2
  exit 1
}

排查时不要把完整环境变量、令牌内容或调试接口响应直接贴到公开 Issue。日志要能证明路径发生了什么，但不应该成为新的泄露面。

发布前保留一张最小检查清单

1. 普通 CI 的默认权限是否为只读，发布写权限是否只出现在发布 job？
2. 发布目标是分支、标签、Release 还是包仓库，权限是否只覆盖这一类对象？
3. 规则集是否保护了默认分支和版本标签，绕过名单是否足够小且可审计？
4. 发布凭据是否使用专用身份，是否避免长期、跨仓库、跨资源授权？
5. 发布任务是否只在可信事件下运行，是否明确处理了外部 Pull Request？
6. 构建产物是否有稳定名称，发布 job 是否能在日志中说明它拿到了哪个版本？
7. 失败时是否能从 job 权限、规则集、事件条件和产物交接四个方向定位，而不用重试猜原因？

我自己的经验是，最小授权不会让发布流程变慢太多，反而会让故障边界更清楚。真正需要维护的是权限矩阵和审计记录，而不是一把“任何时候都能发布”的万能钥匙。

相关问题

普通构建任务需要 contents: write 吗？

通常不需要。先用 contents: read，只有确实要创建标签、Release 或写回仓库时，才在对应 job 中增加写权限。

为什么令牌有写权限仍然不能推送标签？

写权限只是必要条件之一，目标标签可能还受到规则集、分支保护或绕过名单限制。应先看目标引用的规则集拒绝原因。

能不能用维护者个人令牌直接发布？

不建议把个人长期令牌作为默认方案。应优先使用专用 App 或细粒度凭据，并限制仓库、资源和使用步骤。