GitHub Actions Pages "pages: write permission denied"

Deploying to Pages from Actions requires pages: write on GITHUB_TOKEN. With the default read-only token the deployment API returns resource-not-accessible. This is a deterministic permission gap.

What this error means

A Pages deploy step fails with a 403 resource-not-accessible-by-integration error referencing the Pages deployment endpoint.

Error: Resource not accessible by integration (pages deployment)
HttpError: 403 - missing 'pages: write' permission

Common causes

pages: write not granted

The job permissions do not include pages, so GITHUB_TOKEN cannot create the Pages deployment.

Restrictive top-level permissions

A top-level permissions block omitting pages overrides the per-job default.

How to fix it

Grant pages: write on the job

1. Add pages: write (and id-token: write) to the deploy job permissions.
2. Confirm no conflicting top-level permissions block removes it.
3. Re-run the workflow.

  deploy:
    permissions:
      pages: write
      id-token: write
      contents: read

How to prevent it

• Set pages: write explicitly on the Pages deploy job.
• Audit top-level permissions so they do not silently strip pages.

Related guides