GITHUB_TOKEN permission

GITHUB_TOKEN permission

The workflow module’s gha_permission type is one grant of access to a workflow’s GITHUB_TOKEN. It is written as the scope, a colon and read, write or none, such as contents: read. The shorthands read-all and write-all, and {} for the empty map, stand alone.¹ The type is a pattern rather than an enumeration of scopes, because GitHub adds scopes. tests/test_schema_rules.py checks that it admits every scope that SchemaStore’s schema lists at the pinned commit.

Where it is used

• A workflow’s permissions records the grants of the file’s top-level permissions key, which apply to every job’s token. It is absent when the file sets none, and then the repository’s or organization’s default applies. A scope that the map leaves out gets no access.
• A job’s job_permissions records the grants of the job’s own permissions key, which replace the workflow’s for that job. A called workflow can lower its token’s access, never raise it.

What no tool checks

docs/index.md says that no tool checks that read-all, write-all or {} stands alone in a list, or that id-token takes write or none, never read. It adds that the Pydantic models do not check the type’s pattern, and that linkml-validate accepts a permission followed by one line break.²

In this repository

SECURITY.md says that every workflow declares permissions: {} at the top.³ Each job then asks for the scopes it needs, which the concepts under workflows/ record.

Footnotes

1. src/github_actions/schema/github_actions_workflow.yaml, gha_permission, permissions and job_permissions ↩

2. docs/index.md, the Validating data section ↩

3. SECURITY.md, the paragraph after the table ↩