GitHub Actions: Error: Failed to create deployment (status: 404) — Ensure GitHub Pages has been enabled

Meaning

actions/deploy-pages needs Pages enabled with Source = GitHub Actions, plus permissions pages: write and id-token: write, and an environment: github-pages. A 404 almost always means the setting is missing; a 403 means permissions or branch protection on the environment.

Common causes

• Pages not enabled, or source set to "Deploy from a branch" instead of "GitHub Actions"
• Missing pages: write / id-token: write permissions
• Job lacks environment: github-pages
• Environment protection rules forbid the branch
• Repository is private on a plan without Pages

Detailed fix by platform

Code examples

permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.dep.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4
        id: dep

How to diagnose

1. Setting — Pages source set to GitHub Actions?
2. Permissions — pages and id-token write?
3. Environment — github-pages allowed for this branch?

More related errors