GitHub Actions permissions 怎样按作业收紧 GITHUB_TOKEN

如果一个工作流包含构建、发布和检查多个 job，最稳妥的做法是把 permissions 放到真正需要它的 job 下面，而不是给整份 workflow 一次性开放写权限。GitHub Actions 会按 job 计算 GITHUB_TOKEN 的有效权限；当你显式列出部分权限时，未列出的权限会变成 none，而 write 本身包含对应的 read。

官方参考地址：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

下面以一个只读取代码并上传构建结果的 build job 为例，说明从入口、编辑到运行后核对的完整路径。文中的界面图是原创说明图，不是 GitHub 截图。

先确认这个 job 到底需要什么权限

进入仓库后，打开 Code → .github → workflows，选择要修改的 YAML 文件。先看 job 中的动作：检出代码通常需要 contents: read；只有确实要操作 Actions 运行、发布包或写回仓库时，才追加对应的 write 权限。

不要根据“以后可能会用到”来放大权限。把每个 job 需要的资源写成清单，再把清单转换成 YAML，后续排错会更容易。

把权限写在需要它的 job 下面

在 jobs.build 下增加 permissions。下面的示例只保留读取仓库内容的能力，其余未声明的权限不主动开放：

name: build

on:
  push:
    branches: [ main ]

jobs:
  build:
    # 只给这个 job 读取仓库内容的能力。
    permissions:
      contents: read
      # 明确关闭本例不需要的 Actions 操作权限。
      actions: none
      # 不让构建 job 修改拉取请求。
      pull-requests: none
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        # 该步骤使用上面 job 的 GITHUB_TOKEN 权限读取代码。
        uses: actions/checkout@v4
      - name: Build
        # 这里放项目自己的构建命令，失败时由 Actions 标记 job 失败。
        run: go build ./...

这里的关键不是把每个 none 都写一遍，而是先明确权限边界。显式写出的关闭项能让读者和维护者一眼看到设计意图；真正依赖的权限则保留在最小范围内。

提交工作流文件并看新的运行状态

在编辑器右上角选择 Commit changes，填写简短的提交说明，例如“收紧构建 job 的令牌权限”，然后提交到当前分支。回到 Actions，选择刚刚触发的 workflow，再打开对应的 build job。

如果工作流使用了不属于 contents: read 的操作，运行可能会因权限不足失败。此时不要直接改成 write-all，先根据失败步骤补充一个具体权限，并说明它服务于哪个动作。

在运行摘要中核对结果

核对三个位置：workflow 运行是否完成、build job 是否成功、日志中使用令牌的步骤是否只执行了预期操作。图中的“完成”和权限摘要只是阅读界面的说明，不代表某一次真实运行结果。

若构建成功但发布步骤失败，通常说明发布动作需要额外的仓库、包或身份联合权限。把发布拆成单独 job，并为它单独配置权限，比给整个 workflow 提权更容易复查。

三个容易忽略的边界

• 顶层和 job 级不要混淆：顶层 permissions 会影响所有 job；job 级配置用于覆盖某个具体 job 的权限，适合构建、测试、发布分离的工作流。
• 未列出的权限不是“保持默认”：显式设置部分权限后，未列出的权限会被设为 none，所以新增步骤前要同步检查它需要的范围。
• fork 和受保护场景可能更严格：来自 fork 的拉取请求通常不能随意获得写权限，仓库或组织设置也可能进一步限制令牌能力，不能只看 YAML 就假定一定可写。

最后可以把权限配置写成一条维护规则：构建 job 只读，发布 job 单独授权，新增动作先查它需要的 scope，再提交最小变更。这样既能减少误用令牌的机会，也能让运行失败时的修复方向更清楚。

相关问题

为什么只写了一个 permissions 字段，其他权限却不能用了？ 因为未列出的权限会被设为 none，这是显式收紧权限时必须考虑的行为。

什么时候应该使用 write？ 只有当前 job 确实需要写仓库、发布包或操作工作流资源时才使用，并把它限制在对应 job。

权限不足时要不要直接改成 write-all？ 不建议。先定位失败动作，再只增加它需要的具体权限。