GitHub Actions "top-level permissions must be a mapping"

By Daniel Zoghalchali·Latchkey

The permissions key accepts either a mapping of scope to access level, or the shorthand read-all / write-all. Any other value (a bare list, a string, an unknown token) fails validation.

What this error means

The workflow fails to start with "permissions must be a mapping" because permissions was written as a list, an arbitrary string, or a malformed structure.

Error: top-level permissions must be a mapping

Common causes

permissions given as a list or string

permissions was written as a YAML list or a non-shorthand string instead of a scope:level mapping.

Typo in the shorthand

A misspelled shorthand (read_all instead of read-all) is not recognized as the valid form.

How to fix it

Use a valid permissions mapping or shorthand

1. Write permissions as scope: level pairs.
2. Or use the supported shorthand read-all / write-all.
3. Set the minimum scopes the workflow actually needs.

permissions:
  contents: read
  pull-requests: write

How to prevent it

• Always express permissions as a scope:level mapping.
• Use only the documented read-all / write-all shorthands.
• Lint workflows so malformed permissions are caught.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions