CI/CD / 系统课时

限制 GITHUB_TOKEN 的权限

限制 GITHUB_TOKEN 的权限

每次 GitHub Actions 工作流运行时,作业通常可以使用 GITHUB_TOKEN 与当前仓库交互。安全配置的重点不是简单地禁用 Token,而是通过 permissions 明确声明工作流真正需要的权限,让测试、构建和发布任务遵循最小权限原则。

学习目标

  • 理解 GITHUB_TOKEN 与 permissions 的关系
  • 在工作流级和作业级配置最小必要权限
  • 根据实际操作判断何时需要提升写权限

从最小权限开始

工作流可能需要读取仓库内容、创建 Release、写入 Packages 或操作 Issues,但不同作业通常不需要相同权限。permissions 可以显式限制 GITHUB_TOKEN,避免给只负责测试的作业保留不必要的写能力。

最常见的读取源码场景只需要 contents: read。如果一个作业根本不需要调用需要仓库权限的 API,还可以使用 permissions: {} 将可配置权限设为无访问权限,再按实际需要逐项增加。

工作流与作业权限覆盖关系

在工作流级设置默认权限

如果多个作业都只需要读取仓库内容,可以在顶层统一声明 contents: read。这样权限意图直接记录在工作流文件中,而不是依赖仓库或组织的默认设置。

yaml
name: CI
on:
  push:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Confirm checkout
        run: test -f README.md && echo "repository checked out"

预期输出

text
repository checked out

示例假设仓库根目录存在 README.md。这里没有授予 contents: write,因为检出代码和执行测试不需要修改仓库内容。

只给特定作业提升权限

当工作流同时包含测试和发布任务时,不应为了发布方便而让所有作业获得写权限。可以保留工作流级的只读权限,只在真正执行发布操作的作业中覆盖 permissions。

yaml
name: Release Permission
on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "test with read-only repository permission"

  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - run: echo "release job has contents write permission"

预期输出

text
test with read-only repository permission
release job has contents write permission

两个作业的日志顺序可能不同,因为没有声明依赖关系。关键点在于权限边界:test 使用工作流级的 contents: read,而 release 单独获得 contents: write。

按操作反推权限

配置权限时,应从作业执行的 GitHub 操作反推所需权限,而不是先给 write-all 再尝试削减。读取仓库内容通常考虑 contents: read;修改仓库内容或创建需要内容写权限的资源时才考虑 contents: write;其他能力则应按对应权限类别单独声明。

遇到 Resource not accessible by integration 或 API 返回权限错误时,不要立即扩大全部权限。先确认失败步骤实际调用了哪个 GitHub API,再只增加对应权限,并重新运行验证。这样既能修复流水线,也能让权限声明长期保持可审计。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

限制 GITHUB_TOKEN 的权限

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通