actions/deploy-pages "Artifact not found" (github-pages) in CI

By Kaveh Alemi·Latchkey

actions/deploy-pages deploys the artifact named github-pages, which actions/upload-pages-artifact must have produced earlier in the run. If the upload step is missing, named differently, or in a job the deploy does not depend on, deploy-pages fails because there is no artifact to publish.

What this error means

The Pages deploy step fails with "Error: No artifact found for the deployment" or "Artifact not found for name: github-pages", even though the site was built.

Error: No artifact found for the deployment.
Please ensure that the artifact named 'github-pages' is uploaded with actions/upload-pages-artifact before deploying.

Common causes

upload-pages-artifact never ran or used a different name

The build job did not call actions/upload-pages-artifact (which uploads the required github-pages name), or the artifact was uploaded under a custom name.

Missing job dependency or wrong run

The deploy job did not needs: the build job, so it ran before the artifact existed, or the artifact belongs to a different run.

How to fix it

Upload the github-pages artifact and depend on the build

1. Use actions/upload-pages-artifact in the build job to create the github-pages artifact.
2. Add needs: build to the deploy job.
3. Re-run so the deploy finds the artifact in the same run.

build:
  steps:
    - uses: actions/upload-pages-artifact@v3
      with: { path: ./_site }
deploy:
  needs: build
  steps:
    - uses: actions/deploy-pages@v4

Keep the artifact name as github-pages

deploy-pages looks specifically for the github-pages artifact; let upload-pages-artifact use its default name rather than renaming it.

How to prevent it

• Always pair upload-pages-artifact with deploy-pages in the same run.
• Add needs: so deploy runs after the artifact is uploaded.
• Keep the default github-pages artifact name.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions