GitLab Pages

Properties5

Aliases #GitLab Pages Deployment

Is BaseNo

Iconi-lucide-gitlab

Order3

Tags #deployment #gitlab #ci-cd

GitLab Pages provides static hosting integrated with GitLab's CI/CD pipelines. Perfect for teams already using GitLab for version control.

Repository Setup

Create a GitLab repository for your Lithos project
Push your project (excluding node_modules and .output)
GitLab Pages is automatically enabled when you add a .gitlab-ci.yml

GitLab CI Configuration

Create .gitlab-ci.yml in your repository root:

image: node:20

stages:
  - build
  - deploy

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .nuxt/

variables:
  NUXT_APP_BASE_URL: /${CI_PROJECT_NAME}/

build:
  stage: build
  script:
    - npm ci
    - npm run generate
  artifacts:
    paths:
      - .output/public

pages:
  stage: deploy
  script:
    - mv .output/public public
  artifacts:
    paths:
      - public
  only:
    - main

Project vs User Pages

Project Pages: username.gitlab.io/project-name (set NUXT_APP_BASE_URL)
User Pages: username.gitlab.io (no base URL needed)

Configuration Options

Custom Domain

Go to Settings > Pages
Add your custom domain
Configure DNS:
- A record: 35.185.44.232
- CNAME: namespace.gitlab.io
Enable Force HTTPS

Environment Variables

Set variables in Settings > CI/CD > Variables:

variables:
  NUXT_PUBLIC_SITE_URL: ${CI_PAGES_URL}
  
build:
  script:
    - npm run generate

Branch-specific Deployments

Deploy different branches to different URLs:

pages:
  stage: deploy
  script:
    - mv .output/public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

pages:preview:
  stage: deploy
  script:
    - mv .output/public public
  artifacts:
    paths:
      - public
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html
  rules:
    - if: $CI_MERGE_REQUEST_IID

Private Projects

For private repositories, enable Pages access:

Go to Settings > General > Visibility
Expand Pages
Choose access level:
- Everyone - Public access
- Only project members - Requires authentication

Troubleshooting

Pipeline Failures

Check the pipeline logs in CI/CD > Pipelines. Common issues:

Missing node_modules cache (first run takes longer)
Node version too old (ensure image: node:20)
Incorrect artifact paths

404 on Subpages

Ensure the base URL is correctly set. For project pages:

variables:
  NUXT_APP_BASE_URL: /${CI_PROJECT_NAME}/

Slow Builds

Enable caching to speed up builds:

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .nuxt/

GitLab vs GitHub Pages

Feature	GitLab Pages	GitHub Pages
CI/CD	Built-in	GitHub Actions
Private repos	Supported	Limited on free tier
Custom domains	Yes, with SSL	Yes, with SSL
Size limits	100MB artifacts	1GB total
Access control	Fine-grained	Public only (free)