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>

Diagnose it: is the job queued, or is the runner gone?

A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.

- name: Runner facts
  run: |
    echo "runner name: $RUNNER_NAME"
    echo "os/arch:     $RUNNER_OS/$RUNNER_ARCH"
    nproc; free -h; df -h /
    echo "labels this job asked for: ${{ toJSON(job) }}"

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

The failures that are not your workflow

• Exit 137 is the kernel out-of-memory killer, not an application error. Check free -h above against your peak usage.
• Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
• A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
• A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.

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