GitLab Pages

GitLab Pages serves static sites from a repository using GitLab CI/CD pipelines. pageflare integrates as a step in your .gitlab-ci.yml pipeline — build your site, optimize with pageflare, and deploy.

How It Works

Add pageflare to your GitLab CI pipeline between the build step and the Pages deployment. GitLab Pages requires the output to be in a public/ directory.

Step 1 — Create the Pipeline

Create or update .gitlab-ci.yml:

.gitlab-ci.yml

image: node:22

pages:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - npx @pageflare/cli dist/ --in-place --no-progress
    - mv dist/ public/
  artifacts:
    paths:
      - public
  only:
    - main

If your framework already outputs to public/ (e.g., Hugo), skip the mv step:

.gitlab-ci.yml

image: node:22

pages:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - npx @pageflare/cli public/ --in-place --no-progress
  artifacts:
    paths:
      - public
  only:
    - main

Hugo Example

.gitlab-ci.yml

image: registry.gitlab.com/pages/hugo:latest

pages:
  script:
    - hugo --minify
    - npm install -g @pageflare/cli
    - pageflare public/ --in-place --no-progress
  artifacts:
    paths:
      - public
  only:
    - main

Step 2 — Pro License

1. Go to your project in GitLab.
2. Navigate to Settings > CI/CD > Variables.
3. Add a variable named PAGEFLARE_LICENSE with your license key.
4. Set it as Masked to protect the value in logs.

Step 3 — Verify

After pushing, go to CI/CD > Pipelines in your GitLab project. Check the job logs for the pageflare summary:

  Done  145.2 KB saved (38.1%)  1.2s
  Files  42 total, 38 optimized, 4 unchanged, 0 errors

Framework Output Directories

Framework	Output directory	Needs mv to public/
Astro	dist/	Yes
Hugo	public/	No
Jekyll	_site/	Yes
Eleventy	_site/	Yes
Vite	dist/	Yes
Docusaurus	build/	Yes
Next.js static export	out/	Yes
MkDocs	site/	Yes

Troubleshooting

Pipeline fails with “command not found” If npx is not available in your CI image, install pageflare globally: npm install -g @pageflare/cli && pageflare public/ --in-place.

Pages not updating Make sure the job is named pages (exact name required by GitLab) and the artifacts path is public. GitLab only deploys Pages from a job with this exact name.

404 after deployment Verify the public/ directory contains an index.html. If you use a framework that outputs to a different directory, make sure the mv step is correct.