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。这样权限意图直接记录在工作流文件中,而不是依赖仓库或组织的默认设置。
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"预期输出
repository checked out示例假设仓库根目录存在 README.md。这里没有授予 contents: write,因为检出代码和执行测试不需要修改仓库内容。
只给特定作业提升权限
当工作流同时包含测试和发布任务时,不应为了发布方便而让所有作业获得写权限。可以保留工作流级的只读权限,只在真正执行发布操作的作业中覆盖 permissions。
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"预期输出
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,再只增加对应权限,并重新运行验证。这样既能修复流水线,也能让权限声明长期保持可审计。