docs(ci): correct the job-level permissions comment

[Aleksei Sviridkin (lexfrei)]

What this PR does

The comment above the top-level permissions: block said jobs request the minimum extra scopes on top of it. That's backwards. A job-level block replaces the workflow-level one, and every scope it does not name is set to none. Write packages: write alone in a job and it loses contents: read and can't check the repo out.

Same wording in every file that carried the old line. It matches what #3574 uses for the workflow it adds.

backport.yaml and pull-requests.yaml also appear in open #3569. Its changed lines there are the cancel-in-progress expressions two lines below the comment, and a three-way merge is clean in either order.

Comment-only: every changed line starts with #, the files still parse, and actionlint reports the same 45 pre-existing findings before and after.

Screenshots

Not a UI change.

Downstream repositories

• No downstream repository is affected by this change
• cozystack/website - follow-up:
• cozystack/terraform-provider-cozystack - follow-up:
• cozystack/ansible-cozystack - follow-up:
• cozystack/ccp - follow-up:
• cozystack/talm - follow-up:
• cozystack/cozyhr - follow-up:
• cozystack/cozy-proxy - follow-up:
• cozystack/cozystack-telemetry-server - follow-up:
• cozystack/external-apps-example - follow-up:
• cozystack/examples - follow-up:

Walked the trigger map against the diff. The only row that names a file here is the ccp one on .github/workflows/tags.yaml, and it triggers on release-prep behaviour, which this doesn't touch.

Release note

docs(ci): the comment above the top-level `permissions` block in the workflow files now says a job-level block replaces it instead of adding to it

Summary by CodeRabbit

• Documentation
  • Clarified workflow permission guidance across automation processes.
  • Documented that the default token permissions are read-only.
  • Clarified that job-level permissions replace top-level defaults and must explicitly declare all required scopes.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request updates permission comments in ten GitHub Actions workflows. The comments state that top-level tokens are read-only and that job-level permission blocks replace top-level defaults.

Changes

Workflow permission documentation

Layer / File(s)	Summary
Permission inheritance comments .github/workflows/*	Updated workflow comments to document read-only top-level tokens, replacement semantics for job-level permissions, and explicit declaration of required scopes.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: myasnikovdaniil

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the comment-only CI documentation change.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/permissions-comment-direction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[IvanHunters]

Verdict

LGTM

The comment now matches GitHub Actions' documented behavior (a job-level permissions block replaces the workflow-level one rather than merging, and every scope left unnamed drops to none); the change is comment-only across all ten workflows with no permissions: value touched.

Caveats

• Verified comment-only: every hunk changes solely the narrative line above permissions:; the contents: read block itself is unchanged in all ten files, so there is no token-scope behavior change to regress.
• The corrected wording fixes a genuinely misleading prior comment ("jobs request the minimum extra scopes" implied additive semantics); the replace-not-merge phrasing is accurate. A reader should still note the unstated corollary that a job with no permissions: block continues to inherit the workflow-level defaults, but the sentence as written ("A job-level block replaces this one") is correct and not obligated to enumerate that case.

[IvanHunters]

Verdict

LGTM

Comment-only change; the corrected semantics are verified true against GitHub Actions documentation, applied identically across all 10 touched files, and the diff contains no non-comment line.

Caveats

• Phases 5b/5c/5d (upgrade/fresh-install impact, config-combination matrix, test-adequacy) are N/A for this PR: it touches only .github/workflows/*.yaml/.yml comment lines, no packages/, CRD, RBAC value, chart, or migration. Verified via git diff | grep -vE '^[+-]#' that zero non-comment lines changed in any of the 10 files.
• The GitHub Actions semantics the corrected comment now states were independently verified (not taken from the PR body) against docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions via two independent lookups: a job-level permissions: block replaces the workflow-level one for that job (does not merge/add), and any permission not named in whichever block applies is set to none.
• A repo-wide audit of every job-level permissions: block in the 10 touched files found none currently exhibiting the footgun the corrected comment warns about (a job with packages: write alone that also calls actions/checkout): every job either omits contents: and never checks out code, or restates contents: read alongside its other scopes. The fix is preventative documentation correctness, not a fix for a currently-broken job.
• Second independent naive-reviewer pass (novelty pass) was not run: the diff is verified byte-for-byte comment-only across all 10 files with zero non-comment lines changed, leaving no semantic surface for an independent derivation beyond the taxonomy-blind hypotheses already executed directly (Phase 3c: 3 derived, 0 survived).

Recommended follow-ups

• .github/workflows/build-main.yaml carries a different, bespoke top-level comment ("the warm-cache job below narrows to the packages:write scope it actually needs") rather than this PR's newly standardized wording. It was not touched here and its warm-cache job already restates both contents: read and packages: write correctly, so there is no defect, only a wording inconsistency; optional alignment in a separate PR.