GitHub Actions Pages Deploy Fails - Missing pages: write / id-token

By Daniel Zoghalchali·Latchkey

A GitHub Pages deployment via actions/deploy-pages fails because the job lacks pages: write and id-token: write, or because the repository Pages source is not set to GitHub Actions.

What this error means

The deploy-pages step fails with a permissions or token error, or the deployment is rejected because Pages is not configured to build from Actions.

Actions log

Error: Creating Pages deployment failed
Error: HttpError: Resource not accessible by integration (pages: write missing)

Common causes

Missing pages and id-token permissions

The official Pages deploy flow needs pages: write to create the deployment and id-token: write for the OIDC verification it performs.

Pages not set to deploy from Actions

If the repository Pages source is still set to a branch, the Actions-based deployment has nowhere to publish and fails.

How to fix it

Grant the Pages permissions

Add pages and id-token write permissions and use the configure/upload/deploy Pages actions.

.github/workflows/pages.yml

permissions:
  pages: write
  id-token: write
  contents: read
jobs:
  deploy:
    environment: github-pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4

Set the Pages source to Actions

In Settings > Pages, set the source to "GitHub Actions".
Upload the artifact with actions/upload-pages-artifact before deploy-pages.
Use the github-pages environment so the deployment is tracked.

How to prevent it

Declare pages: write and id-token: write on the deploy job.
Keep the Pages source set to GitHub Actions.
Use the official configure/upload/deploy Pages actions together.

Frequently asked questions

What causes "Pages deploy denied"?