GitLab Pages Job Fails - "public" Folder Missing or Wrong Stage

By Kaveh Alemi·Latchkey

GitLab Pages is published by a specially-named pages job that must produce a public/ directory as an artifact. If that contract is not met, the deploy step fails.

What this error means

The build script succeeds but Pages does not publish: the job is not recognized as Pages, the pages:deploy step errors, or the site 404s because public/ was empty or never uploaded.

Uploading artifacts...
WARNING: public: no matching files. Ensure that the artifact path is relative to the working directory
ERROR: No files to upload

Common causes

Output not placed in public/

Pages serves the contents of the public/ artifact. A generator that writes to dist/ or build/ produces no Pages content unless you move or configure the output to public/.

Job not named pages or missing artifact

GitLab triggers the Pages deploy only for a job named pages (or one with a pages: config) that declares artifacts:paths: [public].

How to fix it

Emit public/ from the pages job

pages:
  stage: deploy
  script:
    - npm run build
    - mv dist public
  artifacts:
    paths:
      - public

Check the pages:deploy result

1. Confirm the pages job uploaded a non-empty public/ artifact.
2. Open the follow-on pages:deploy step in the pipeline - its log states why a deploy was rejected.
3. Verify your Pages base path matches how the static site references assets.

How to prevent it

• Always output the site to public/ in the pages job.
• Declare artifacts:paths: [public] so the deploy has content.
• Build asset URLs relative to the configured Pages base path.

Frequently asked questions

Related guides

References

• GitHub Actions documentation