Fix GitHub Actions Pages Deploy 404

A successful Pages action can still publish the wrong folder. Check artifact upload path and generated files.

Book $50 Deploy Rescue Generate a checklist

Common symptoms

Action is green but site is 404.
Only README or no files are published.
The build output folder is missing index.html.

What to check first

Platform: GitHub Actions + Pages
Error: Pages deploy 404

A successful Pages action can still publish the wrong folder. Check artifact upload path and generated files.

Step-by-step fix

Confirm the build command creates index.html in the expected folder.
Set upload-pages-artifact path to the build output directory.
Use actions/deploy-pages with pages: write and id-token: write permissions.
Check Settings > Pages uses GitHub Actions as source.

- uses: actions/upload-pages-artifact@v3
  with:
    path: dist
- uses: actions/deploy-pages@v4

Common mistake to avoid

Do not upload the repo root unless it actually contains the built static site.

Still stuck?

Send the deploy log, repository link, target platform, and expected URL. ShipFast Deploy Rescue is a fixed-price debugging service for indie projects and MVPs.

Get Deploy Rescue Email project details