Token 权限与最小授权

本文档介绍 ATOMGIT_TOKEN 的自动生成机制、permissions 字段的配置方法以及最小权限原则的实践示例。

流水线默认 Token（ATOMGIT_TOKEN）具有仓库级读写权限，但在最小权限原则下，应限制 Token 仅拥有 job 所需的最低权限，防止越权操作。

配置说明

ATOMGIT_TOKEN 自动生成

每次流水线运行时，AtomGit Action 自动生成 ATOMGIT_TOKEN，用于：

• 克隆代码仓库
• 推送构建产物
• 创建 PR、Issue 评论
• 操作项目资源

ATOMGIT_TOKEN 的权限范围由 workflow 的 permissions 字段控制。

permissions 字段详解

顶层 permissions（workflow 级别默认）：

# .gitcode/workflows/ci.yml
name: CI Pipeline

permissions:
  project: read           # 项目信息读取
  pr: write               # PR 写操作（创建、评论、合并）
  issue: read             # Issue 读取
  note: write             # 评论/Note 写操作
  repository: write       # 仓库写操作（推送）

权限类型对照

权限域	read	write	none	说明
project	读取项目信息	修改项目设置	无权限	项目元数据操作
pr	读取 PR	创建/评论/合并 PR	无权限	Pull Request 操作
issue	读取 Issue	创建/评论 Issue	无权限	Issue 操作
note	读取评论	创建评论	无权限	通用评论操作
repository	克隆/读取	推送/修改仓库	无权限	代码仓库操作

最小权限原则实践

原则：每个 job 仅声明其所需权限，不多给。

示例一：仅读仓库的 lint job

permissions:
  repository: read         # 仅需克隆代码
  pr: none                 # 不操作 PR
  issue: none              # 不操作 Issue
  note: none               # 不评论
  project: none            # 不读取项目信息

stages:
  lint:
    name: 代码检查
    jobs:
      name: code-lint
      runs-on: {ubuntu-24,x64,slim}
      steps:
        - run: npm run lint

示例二：需要评论 PR 的测试 job

permissions:
  repository: read         # 克隆代码
  pr: write                # 在 PR 上评论测试结果
  issue: none
  note: none
  project: none

stages:
  test:
    name: 测试
    jobs:
      name: report-results
      runs-on: {ubuntu-24,x64,small}
      steps:
        - run: |
            pytest
            curl -X POST "https://atomgit.com/api/v5/repos/${{ atomgit.repository }}/pulls/${{ atomgit.event.pr.number }}/comments" \
              -H "Authorization: token $ATOMGIT_TOKEN" \
              -d '{"body": "All tests passed ✅"}'

permissions 与 ATOMGIT_TOKEN 的关系

permissions 配置	ATOMGIT_TOKEN 实际权限
未声明 permissions	使用仓库设置中定义的权限
顶层声明 permissions	所有 job 继承顶层权限，除非 job 级覆盖
permissions: {}（空）	ATOMGIT_TOKEN 仅拥有最小默认权限（repository:read）

关键安全提示：pull_request 事件来自 fork 仓库时，ATOMGIT_TOKEN 仅拥有 read 权限，无论 permissions 如何声明。这是 AtomGit Action 的安全隔离机制。若需写权限，需使用 pull_request_target 事件。