GitHub Actions actions/deploy-pages "Artifact not found" for Pages

actions/deploy-pages could not find the github-pages artifact to deploy. The upload step was missing or named differently, or the deploy and upload actions are on incompatible versions.

What this error means

The deploy-pages step fails with an artifact-not-found error, even though the build job ran. The site is never published because there was no Pages artifact to deploy.

Actions log

Error: No artifact found for the deployment
Error: Failed to create deployment (status: 404) with build version ...
artifact "github-pages" not found

Common causes

No upload-pages-artifact step

deploy-pages consumes the special github-pages artifact produced by actions/upload-pages-artifact. Without that upload step (or a generic upload-artifact instead), there is nothing to deploy.

Version mismatch or missing dependency

Mixing old upload-pages-artifact with a newer deploy-pages (or running deploy in a job that does not depend on the build job) can leave the artifact unavailable.

How to fix it

Upload then deploy the Pages artifact

.github/workflows/pages.yml

build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/configure-pages@v5
    - uses: actions/upload-pages-artifact@v3
      with:
        path: ./_site
deploy:
  needs: build
  runs-on: ubuntu-latest
  steps:
    - uses: actions/deploy-pages@v4

Keep the Pages actions compatible

Use upload-pages-artifact (not the generic upload-artifact) for the build output.
Make the deploy job depend on the build job via needs.
Keep upload-pages-artifact and deploy-pages on matching majors.

How to prevent it

Always produce the artifact with upload-pages-artifact before deploy-pages.
Wire deploy to the build job with needs:.
Upgrade the Pages actions together to avoid version mismatches.