Token Permissions and Least Privilege

This document introduces the automatic generation mechanism of ATOMGIT_TOKEN, the configuration method of the permissions field, and practical examples of the principle of least privilege.

The default pipeline token (ATOMGIT_TOKEN) has repository-level read and write permissions. However, under the principle of least privilege, the token should be restricted to only the minimum permissions required for the job to prevent privilege escalation.

Configuration Guide

Automatic Generation of ATOMGIT_TOKEN

Each time a pipeline runs, AtomGit Action automatically generates ATOMGIT_TOKEN, which is used for:

• Cloning code repositories
• Pushing build artifacts
• Creating PRs, issue comments
• Managing project resources

The scope of ATOMGIT_TOKEN permissions is controlled by the workflow's permissions field.

Detailed Explanation of the Permissions Field

Top-level permissions (default at workflow level):

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

permissions:
  project: read           # Read project information
  pr: write               # Write operations on PR (create, comment, merge)
  issue: read             # Read Issue
  note: write             # Write operations on comments/Note
  repository: write       # Write operations on repository (push)

Permission Type Comparison

Permission Scope	read	write	none	Description
project	Read project information	Modify project settings	No permission	Project metadata operations
pr	Read PR	Create/Comment/Merge PR	No permission	Pull Request operations
issue	Read Issue	Create/Comment Issue	No permission	Issue operations
note	Read comments	Create comments	No permission	General comment operations
repository	Clone/Read	Push/Modify repository	No permission	Code repository operations

Practical Application of the Principle of Least Privilege

Principle: Each job should only declare the permissions it needs, without excess.

Example One: Lint Job That Only Reads the Repository

permissions:
  repository: read         # Only need to clone the code
  pr: none                 # Do not operate PR
  issue: none              # Do not operate Issue
  note: none               # Do not comment
  project: none            # Do not read project information

stages:
  lint:
    name: Code Check
    jobs:
      name: code-lint
      runs-on: [ubuntu-24, x64, slim]
      steps:
        - run: npm run lint

Example Two: Test Job That Needs to Comment on a PR

permissions:
  repository: read         # Clone code
  pr: write                # Comment on the test results in PR
  issue: none
  note: none
  project: none

stages:
  test:
    name: Test
    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 ✅"}'

Relationship Between Permissions and ATOMGIT_TOKEN

Permissions Configuration	Actual Permissions of ATOMGIT_TOKEN
Permissions not declared	Use the permissions defined in the repository settings
Permissions declared at the top level	All jobs inherit the top-level permissions unless overridden at the job level
permissions: {} (empty)	ATOMGIT_TOKEN only has the minimal default permission (repository: read)

Critical Security Note: When the pull_request event comes from a forked repository, ATOMGIT_TOKEN only has read permissions regardless of how permissions are declared. This is a security isolation mechanism of AtomGit Action. If write permissions are needed, use the pull_request_target event.