GitHub Actions cannot set permissions inside a composite action

GITHUB_TOKEN permissions are controlled by the workflow or job that runs the action, not by the action itself. A composite action cannot declare a permissions key - it inherits whatever the calling job grants.

What this error means

A composite action.yml with a permissions key fails validation, or the permissions are silently ignored.

# action.yml (composite) - invalid
runs:
  using: composite
permissions:
  contents: write   # not a valid key for a composite action

Common causes

permissions is a workflow/job concept

Token scopes are set by the consumer; actions run under the caller’s granted permissions.

Expecting an action to elevate its own token

An action cannot grant itself more than the job provides.

How to fix it

Set permissions in the calling job

1. Declare the needed permissions in the workflow or job that uses the composite action.
2. Remove the permissions key from action.yml.

# calling workflow
jobs:
  run:
    permissions:
      contents: write
    steps:
      - uses: ./my-composite-action

Document required permissions in the action README

1. State which token scopes the action needs so consumers grant them.
2. Fail early in the action if a required permission is missing.

How to prevent it

• Grant token scopes at the job/workflow level, not in actions.
• Document an action’s required permissions for its callers.

Related guides