GitHub Actions "permissions must list valid scopes"

By Kaveh Alemi·Latchkey

The permissions block only accepts known scope keys (contents, packages, id-token, pages, deployments, and so on) with values read, write, or none. A typo in the scope name or value fails workflow validation.

What this error means

The workflow is invalid because a permissions entry uses an unrecognized scope key or a value other than read/write/none.

Invalid workflow file: .github/workflows/deploy.yml#L5
Unexpected value 'package-write'. Valid permission values are 'read', 'write', 'none'.

Common causes

Misspelled scope key

A scope like package instead of packages, or a made-up scope, is not recognized.

Invalid permission value

The value is not one of read, write, or none.

How to fix it

Use valid scope keys and values

1. Correct the scope key to a known permission (contents, packages, id-token, pages, deployments, etc.).
2. Set the value to read, write, or none.
3. Validate the workflow after editing.

permissions:
  contents: read
  packages: write
  id-token: write

How to prevent it

• Reference the documented permission scope names and only use read/write/none values.
• Lint workflow files to catch invalid permission entries early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions