GitLab CI Pages Job Fails - "public" Directory Not Found

By Kaveh Alemi·Latchkey

The GitLab Pages job must produce a public/ directory and upload it as an artifact. If the static build outputs to dist/ or build/ and is not moved or mapped to public, the deploy has nothing to serve.

What this error means

The pages job fails or deploys nothing, with a warning that the public directory was not found or that no files were uploaded as the pages artifact.

WARNING: public: no matching files. The pages job must produce a
"public" directory as a job artifact.
ERROR: No files to upload for pages

Common causes

Build outputs to a different folder

Frameworks emit to dist/ or build/; Pages specifically needs public/.

artifacts:paths does not include public

Even if public exists, it must be listed under artifacts:paths to be uploaded.

Job not named pages or pages:deploy missing

The Pages deploy is keyed off the conventional pages job (or a pages deploy step).

How to fix it

Move build output into public and upload it

Copy the framework output into public and declare it as the artifact.

pages:
  stage: deploy
  script:
    - npm run build
    - mv dist public
  artifacts:
    paths:
      - public
  rules:
    - if: '${CI_COMMIT_BRANCH} == "main"'

How to prevent it

• Always output (or move) static files into public for Pages.
• List public under artifacts:paths.
• Gate the pages job to your default branch.

Frequently asked questions

Related guides

References

• GitHub Actions documentation