GitHub Actions actions/deploy-pages "deployment failed" (environment)

actions/deploy-pages creates a deployment to the github-pages environment. Environment protection rules that the ref does not satisfy, missing pages/id-token permissions, or no uploaded Pages artifact all fail the deployment.

What this error means

A deploy-pages step fails creating or completing the deployment, sometimes citing the environment, a protection rule, or a missing artifact.

github-actions

Error: Creating Pages deployment failed
Error: HttpError: Branch "feature/x" is not allowed to deploy to github-pages due to environment protection rules.

Common causes

Environment protection rule blocks the ref

The github-pages environment can restrict which branches may deploy; a non-allowed branch is rejected.

Missing permissions or artifact

Without pages: write and id-token: write, or without an uploaded Pages artifact, the deploy cannot complete.

How to fix it

Align environment, permissions, and artifact

Allow the deploying branch in the github-pages environment rules.
Set pages: write and id-token: write on the job and reference the environment.
Ensure upload-pages-artifact ran before deploy-pages.

.github/workflows/pages.yml

permissions:
  pages: write
  id-token: write
environment:
  name: github-pages
steps:
  - uses: actions/deploy-pages@v4

How to prevent it

Configure the github-pages environment to allow your deploy branches.
Keep the upload then deploy ordering intact.