Skip to content

Permissions contract

What each reusable workflow needs from its caller, and the rules that keep that list true.

Why it matters

A called workflow cannot have more permissions than its caller grants. When a job of a reusable workflow asks for more, GitHub refuses the whole run before any job starts (startup_failure), in every repository that calls it. So a workflow here asks for the least it needs, per job, and the README and this page say exactly what that is.

What each workflow needs

Grant at least the "Caller grants" column on the calling job, or at the top of the calling workflow. The table is read from the workflow files.

Workflow Caller grants Job: permissions
dco.yml contents: read, pull-requests: read dco: contents: read, pull-requests: read
org-standard-check.yml contents: read check: contents: read
ru-attest-release.yml attestations: write, contents: read, id-token: write attest: attestations: write, contents: read, id-token: write
ru-build.yml contents: read, pull-requests: write generate-matrix: contents: read
build: contents: read
size-report: pull-requests: write
ru-ci-gate.yml contents: read gate: contents: read
ru-cpp-analysis.yml contents: read cppcheck: contents: read
ru-cpp-lint.yml contents: read lint: contents: read
ru-cross-build.yml contents: read build-cores: contents: read
plan: none
build: contents: read
ru-docs-linkcheck.yml contents: read link-check: contents: read
ru-docs-publish.yml contents: write input-validation: none
quality-checks: contents: read
version-detection: contents: read
build: contents: write
ru-handbook-check.yml contents: read check: contents: read
ru-host-ci.yml contents: read host: contents: read
ru-host-quality.yml contents: read gates: contents: read
complexity: contents: read
coverage: contents: read
sanitizers: contents: read
fuzz: contents: read
ru-markdown-lint.yml contents: read markdownlint: contents: read
ru-misra.yml contents: read plan: contents: read
scan: contents: read
report: contents: read
ru-mkdocs-publish.yml contents: write build: contents: read
quality: contents: read
deploy: contents: write
ru-release-firmware.yml actions: read, contents: write release: actions: read, contents: write
ru-release-with-artifacts.yml contents: write release: contents: write
ru-release.yml contents: write release: contents: write
ru-repo-checks.yml contents: read, pull-requests: read checks: contents: read, pull-requests: read
ru-template-drift.yml contents: read drift: contents: read
ru-yaml-lint.yml contents: read yamllint: contents: read

The rules

The self-CI (check_permissions.py in the workflow contract checks job) fails a pull request when:

Rule Why
A reusable workflow's top-level permissions: is missing or not {} Nothing is granted by default; permissions are per job, so a read-only job never holds a write token
A job of a reusable workflow has no permissions: mapping It would inherit everything the caller granted
A workflow's job permissions differ from its row in the README table More breaks callers; less means the table asks for too much
A reusable workflow has no row, or a row names no workflow The table is the contract callers read
A caller in this repository grants less than the contract The self-tests would hit startup_failure

A new permission on an existing workflow is a breaking change: it needs a ### Breaking entry in the changelog and a new major (Versioning).

The "no bare && tail" rule

GitHub runs run: blocks with bash -e, and a script's exit status is that of its last command. A last line such as [ -n "$X" ] && echo "..." fails the step whenever the condition is false, although -e ignores the same line anywhere else. check_run_tails.py fails any run: block that ends that way; write an if ... fi instead.

Next: the workflow catalogue.