GitHub Actions 怎样限制 GITHUB_TOKEN 的默认权限

GitHub Actions 的 GITHUB_TOKEN 默认权限不应该直接按“整个工作流都可写”来处理。更稳妥的做法是先把仓库级默认值调成受限模式，再在工作流或单个 job 中补上确实需要的权限。

官方地址：https://docs.github.com/en/actions/tutorials/authenticate-with-github_token

如果任务只需要读取代码，就给 contents: read；只有创建 Issue、发布包或部署时，才在对应层级增加相应的 write 权限。GitHub 文档规定，只要在 permissions 中显式写出任一权限，未列出的权限就会被设为 none。

先把仓库默认权限调成受限模式

先进入仓库的 Settings → Actions → General，找到 Workflow permissions。这里控制的是仓库层面的默认值：可以选择让令牌拥有更宽的读写权限，也可以选择只读的受限权限。新仓库或组织继承来的默认值可能不同，所以不要只凭记忆判断当前状态。

1. 在仓库主页打开 Settings。
2. 进入左侧 Actions → General。
3. 在 Workflow permissions 选择受限的只读选项，然后点击 Save。

这一步只设置默认基线，不代表所有工作流都只能读取。工作流文件仍然可以用 permissions 明确声明所需范围；组织级设置更严格时，仓库页面可能无法改成更宽的权限。

再用 permissions 覆盖工作流范围

仓库默认值收窄后，把权限写进工作流文件。下面这个例子只让工作流读取代码，并让一个创建 Issue 的 job 获得写权限。YAML 中的注释说明了权限为何放在不同层级。

name: permission-demo
on: workflow_dispatch

# 工作流级权限是所有 job 的默认最小范围
permissions:
  contents: read

jobs:
  inspect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "只读取仓库内容"

  create-issue:
    runs-on: ubuntu-latest
    # 这个 job 需要创建 Issue，所以只在这里追加写权限
    permissions:
      contents: read
      issues: write
    steps:
      - name: Create issue
        env:
          # 令牌由 Actions 注入，示例不写入真实密钥值
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh issue create --title "自动记录" --body "由工作流创建"

工作流级 permissions 适合定义共同基线，job 级配置适合把写权限锁在单一任务中。write 已经包含读取能力；如果只声明 issues: write，未声明的其他权限会被设为 none，因此要根据任务是否还需要读取代码来补上 contents: read。

保存后怎样判断权限真的合适

先回到工作流文件，确认权限声明位置和缩进没有错误；再打开 Actions 页面查看工作流运行状态。只读任务应能完成 checkout 或读取 API，创建 Issue 的 job 才应使用 issues: write。不要用“整条工作流变绿”作为唯一判断，因为一个没有触发写操作的 job 可能暂时掩盖授权过宽或过窄。

如果出现 Resource not accessible by integration、API 返回 403 或某个动作提示没有写权限，按下面顺序处理：

1. 确认仓库 Settings → Actions → General → Workflow permissions 没有被组织级限制覆盖。
2. 确认需要写入的能力写在正确的 workflow 或 job 层级，例如创建 Issue 对应 issues: write。
3. 确认事件类型的边界。来自 fork 的 pull_request 工作流通常不能随意获得写权限，不能靠 YAML 强行绕过平台限制。
4. 重新保存工作流并查看新的运行记录，确认报错是否从权限不足变为其他具体问题。

常见误区与最终配置清单

最常见的误区有三个：把仓库默认权限当成最终权限、在工作流顶层给所有 job 开写权限、以及只写一个权限键却忘记未列出的权限会归零。对外发布或修改仓库的 job，应该单独列出它的写权限；只读 job 则保持 contents: read 或更小的范围。

把默认权限调低，再按 job 精确补权，通常比给整个工作流开启读写权限更容易维护。以后新增一个动作时，先问它需要访问哪类资源，再把对应权限写在最窄的作用域中。

相关问题

permissions 写在 workflow 还是 job？

所有 job 共用的只读基线写在 workflow；只有个别 job 需要写入时，优先放到该 job。

为什么写了 issues: write 仍然不能创建 Issue？

先确认工作流事件、仓库设置和组织策略没有进一步收窄令牌，再确认实际调用的是当前 job 的 GITHUB_TOKEN。

能不能直接使用 write-all？

可以表达宽权限，但它不符合最小授权目标。只有在明确知道所有 job 都需要写入多类资源时才应考虑，并且要记录理由。