ci(documentation): cap GITHUB_TOKEN to contents: read

[arpitjain099]

Pins the default GITHUB_TOKEN to contents: read at workflow level. No GitHub API writes from the workflow.

Post-CVE-2025-30066 (tj-actions/changed-files) hardening pattern. YAML validated locally.

---

Note

Low Risk
CI-only permission tightening with an explicit write grant on the job that publishes docs; no runtime or application code changes.

Overview
Hardens the Documentation workflow by setting workflow-level permissions to contents: read, so the default GITHUB_TOKEN cannot write to the repo unless a job opts in.

The documentation job overrides with contents: write so the existing gh-pages push step can still publish generated docs.

^{Reviewed by Cursor Bugbot for commit ad10fc9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 18d250d. Configure here.}

[nkaradzhov]

@arpitjain099 thanks, i will have a look

[nkaradzhov]

@arpitjain099

Upload step pushes to gh-pages branch via npm run gh-pages (line 26-27), authenticating with GITHUB_TOKEN. With contents: read only, the push fails (403 Forbidden / remote: Permission denied).

"YAML validated locally" only checks syntax, not runtime token scope. No CI run on master/v4.0 push has exercised this yet.

Fix — least-privilege per job:

permissions:
  contents: read

jobs:
  documentation:
    permissions:
      contents: write   # required for gh-pages push
    runs-on: ubuntu-latest

Keeps workflow-level read-only default, grants write only to the job that needs it. Still a hardening win vs. the implicit default GITHUB_TOKEN scope.

[arpitjain099]

@arpitjain099

Upload step pushes to gh-pages branch via npm run gh-pages (line 26-27), authenticating with GITHUB_TOKEN. With contents: read only, the push fails (403 Forbidden / remote: Permission denied).

"YAML validated locally" only checks syntax, not runtime token scope. No CI run on master/v4.0 push has exercised this yet.

Fix — least-privilege per job:

permissions:
  contents: read

jobs:
  documentation:
    permissions:
      contents: write   # required for gh-pages push
    runs-on: ubuntu-latest

Keeps workflow-level read-only default, grants write only to the job that needs it. Still a hardening win vs. the implicit default GITHUB_TOKEN scope.

@nkaradzhov ok I'll check this out later tonight.

[arpitjain099]

Thanks @nkaradzhov, you are absolutely right - the Upload step pushes to gh-pages so it needs contents: write. Updated to keep workflow-level contents: read as the default and elevate only the documentation job, per your least-privilege-per-job suggestion.

[arpitjain099]

Thanks @nkaradzhov, you are absolutely right - the Upload step pushes to gh-pages so it needs contents: write. Updated to keep workflow-level contents: read as the default and elevate only the documentation job, per your least-privilege-per-job suggestion.