workflow

`permissions:`

Controls the scopes granted to the automatically generated GITHUB_TOKEN. Can be set at the workflow or job level; the job-level block overrides the workflow default.

Syntax

permissions:
  <scope>: read|write|none

Common values / subkeys

Value / Subkey	Purpose
contents	Read/write repository contents (releases, tags)
pull-requests	Read or write PR comments, labels, reviews
id-token	Set to write for OIDC federation (AWS/Azure/GCP)
packages	Push/pull GHCR packages
actions	Read workflow runs / cancel runs
read-all \| write-all \| {}	Grant all scopes read/write, or none ({})

Examples

permissions:
  contents: read

Least-privilege default at workflow root

permissions:
  id-token: write
  contents: read

OIDC to cloud provider without repo writes

permissions: {}

Explicitly grant no permissions

jobs:
  release:
    permissions:
      contents: write
      packages: write

Elevate only for the release job

Gotcha

Setting any key restricts unlisted scopes to none; if you set only `id-token: write` you also lose the default contents read unless you add it back.

Related keywords

${{ secrets.NAME }}

The `secrets` context exposes repository, environment, and organization secrets to workflow expressions. Values are masked in logs and are not passed to workflows triggered from forked PRs.

${{ github }}

The `github` context exposes information about the workflow run, event payload, repository, and actor. It is available in most expression fields and is the primary source of triggering-event data.

jobs:

Top-level map of jobs that run in parallel by default. Each job has an ID (used by `needs:` and outputs) and either a `steps:` list or a `uses:` reference to a reusable workflow.

on:

Declares the events that trigger the workflow. Accepts a single event, a list, or a map with per-event filters (branches, paths, tags, types).

env:

Defines environment variables for a scope. Declared at the workflow, job, or step level and read back via the `env` context or as real environment variables inside `run:` scripts.

← All GitHub Actions syntax · Git commands · Cron syntax