GitHub Actions peaceiris/actions-gh-pages "src dir not found"

By Kaveh Alemi·Latchkey

peaceiris/actions-gh-pages publishes the contents of publish_dir to the Pages branch. If that directory does not exist at action time - the build step failed or wrote elsewhere - the action has nothing to publish.

What this error means

An actions-gh-pages step fails because the publish directory does not exist, usually right after a build step that did not produce it.

[INFO] Usage: https://github.com/peaceiris/actions-gh-pages#readme
Error: Action failed with "The directory \"public\" does not exist."

Common causes

Build output missing

The static-site build did not run or failed, so publish_dir was never created.

Wrong publish_dir path

publish_dir points at public when the generator emits dist (or vice versa).

How to fix it

Build first and point publish_dir correctly

1. Run the site build before the gh-pages step.
2. Set publish_dir to the generator output directory.
3. List the directory in a debug step if unsure.

- run: npm run build
- uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist

How to prevent it

• Order build before publish in the same job.
• Keep publish_dir in sync with the build output path.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions