GitHub Actions "actions/deploy-pages: Failed to create deployment"

By Kaveh Alemi·Latchkey

actions/deploy-pages calls the Pages deployment API. It needs pages: write and id-token: write. Missing permissions fail deterministically; an intermittent Pages API 5xx is transient and resolves on re-run.

What this error means

The deploy-pages step fails creating the deployment, either with a permission/403 message or an intermittent server error.

Error: Failed to create deployment (status: 500) with build version <sha>.
Request ID: <id>

Common causes

Missing pages or id-token permission

The deploy job lacks pages: write or id-token: write, so the Pages deployment API rejects the call.

Transient Pages API error

An occasional 5xx from the Pages deployment service fails the create call even with correct permissions.

How to fix it

Grant the Pages permissions

1. Add pages: write and id-token: write to the deploy job.
2. Keep contents: read for checkout.
3. Re-run; for an intermittent 5xx simply re-run the job.

  deploy:
    permissions:
      pages: write
      id-token: write
      contents: read
    steps:
      - uses: actions/deploy-pages@v4

How to prevent it

• Always grant pages: write and id-token: write on the Pages deploy job.
• On Latchkey managed runners, transient Pages-API 5xx failures are retried automatically so a one-off deployment flake does not fail the workflow.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions