🔐 GitHub Actions Permissions¶

GitHub Actions uses a permission-based security model.
Workflows and individual jobs can be granted specific access levels to follow the principle of least privilege.

This guide focuses on the three most important permissions when deploying documentation (especially MkDocs + GitHub Pages) and modern cloud deployments.

Overview of Key Permissions¶

Detailed Permission Reference¶

1. contents: write¶

permissions:
  contents: write

What it allows¶

Common use cases¶

• Deploying MkDocs site via peaceiris/actions-gh-pages
• Auto-updating README, release notes, or generated docs
• Any CI that commits artifacts back to the repo

Risk¶

Compromised workflow could rewrite repository code → use only when necessary

2. pages: write¶

permissions:
  pages: write

What it allows¶

When required¶

Only with GitHub’s official deployment action:

- uses: actions/deploy-pages@v4

Not needed when using peaceiris/actions-gh-pages (that one uses contents: write instead).

Risk¶

Very low — only affects the published static site.

3. id-token: write¶

permissions:
  id-token: write

What it allows¶

Supported cloud providers (OIDC)¶

Use cases¶

• Deploy static sites to S3 + CloudFront
• Firebase Hosting, Cloudflare R2, GCP Cloud Storage, Azure Storage

Risk¶

Gives real cloud credentials → treat as high-risk. Only grant when actually deploying to external clouds.

Choosing the Right Permissions for Your Deployment¶

Where to Declare Permissions (Scope)¶

GitHub supports two scopes:

1. Workflow-level (root)¶

permissions:
  contents: write
  pages: write
  id-token: write

→ Applies to all jobs in the workflow (unless overridden)
→ Convenient for simple, single-purpose workflows

2. Job-level (recommended for security)¶

jobs:
  build:
    permissions: {}
    # or explicitly read-only
    # permissions: read-all

  deploy:
    permissions:
      pages: write
      # or contents: write / id-token: write as needed

→ Only the deploy job gets write access
→ Follows least privilege principle

Decision Table¶

Secure Enterprise Pattern (Best Practice)¶

name: Deploy Docs
on: [push, workflow_dispatch]

permissions: {}  # deny all by default

jobs:
  build:
    runs-on: ubuntu-latest
    steps: [...]

  test:
    needs: build
    runs-on: ubuntu-latest
    steps: [...]

  deploy:
    needs: test
    permissions:
      contents: write   # or pages: write / id-token: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4   # if using official action
      # or peaceiris/actions-gh-pages@v4

One-Glance Summary Table¶

Key Takeaways (Senior Engineer Mindset)¶

• Never grant more permissions than needed
• Prefer job-level permissions in multi-job workflows
• Root-level permissions = convenience, job-level = security
• Use pages: write only with official deploy action
• Use id-token: write only for real cloud OIDC deployments