GitHub Actions "Unexpected value 'permissions'" (job vs workflow level)

By Kaveh Alemi·Latchkey

permissions is valid at workflow top level and at job level, but not inside steps or under arbitrary keys. Misplacing it, or using an invalid scope/structure, yields an Unexpected value permissions error.

What this error means

The workflow is invalid at parse time pointing at a permissions key, usually because it was nested incorrectly or malformed.

Invalid workflow file: .github/workflows/ci.yml#L12
Unexpected value 'permissions'

Common causes

permissions in an invalid location

Placing permissions under steps or a non-job key is not allowed.

Invalid scope or structure

An unknown permission scope or wrong mapping shape is rejected.

How to fix it

Place permissions at workflow or job level

1. Put permissions at the top level for all jobs, or under a specific job.
2. Use valid scopes (contents, issues, pull-requests, packages, id-token, etc.).
3. Write it as a mapping of scope: read|write|none.

permissions:
  contents: read
jobs:
  deploy:
    permissions:
      contents: write
      id-token: write
    runs-on: ubuntu-latest
    steps:
      - run: echo ok

How to prevent it

• Keep permissions only at workflow or job scope.
• Validate scope names against the documented permission set.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions