How to Deploy a Static Site to GitLab Pages From CI

GitLab Pages publishes whatever a job named pages leaves in the public/ directory and declares as an artifact.

Create a job named pages, build your site into public/, and declare artifacts.paths: [public]. GitLab picks up the artifact and serves it as your Pages site.

Steps

• Name the deploy job exactly pages.
• Build the site so its output lands in public/.
• Declare public under artifacts.paths.
• Restrict the job to the default branch with rules.

Pipeline

pages:
  stage: deploy
  image: node:20
  script:
    - npm ci
    - npm run build
    - mv dist public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Gotchas

• The output directory must be public; any other name is ignored.
• If your build already writes to public, drop the mv step.
• Set the framework base path to the project path when not using a custom domain.

Related guides