13. GitLab Pages Hosting

Sometimes you need to host static content: documentation sites, project wikis, client landing pages, or user portfolios. Just like GitHub Pages, GitLab Pages allows you to host static websites directly from your GitLab repository—completely free. However, unlike GitHub Pages where you check static files directly into a branch, GitLab Pages generates your site dynamically inside a standard CI/CD pipeline!

How GitLab Pages Works

GitLab Pages runs a special job in your pipeline that compiles your site and places the static assets inside a folder named public. Once the pipeline successfully uploads the public directory as an artifact, GitLab deploys it to a secure public URL automatically.

The GitLab Pages Pipeline: `.gitlab-ci.yml`

To deploy to GitLab Pages, you must define a specific job in your pipeline that meets these exact rules:

1. The job must be named exactly pages.
2. It must export an artifact containing a directory named exactly public.

Example 1: Plain HTML & CSS Website

If your files are already static HTML files, you simply copy them to a `public` directory:

pages:
  stage: deploy
  script:
    # Create the public directory
    - mkdir -p public
    # Move index.html and style.css into the public folder
    - cp index.html public/
    - cp -r assets/ public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Example 2: Next.js or React Website

If you are compiling a modern React application, you execute the build process and rename the build folder to `public`:

pages:
  stage: deploy
  image: node:18-alpine
  script:
    - npm ci
    # Build static export (e.g. Next.js export or React build)
    - npm run build
    # Rename default export folder (dist/build) to 'public'
    - mv dist public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Pages URL and Custom Domains

By default, your static site will be available at:

https://username.gitlab.io/project-name/

However, GitLab Pages fully supports custom branding and infrastructure settings:

• Custom Domains: Connect your own domain (e.g. `www.myportfolio.com`) under Deploy > Pages > New Domain in the sidebar.
• Automatic SSL Certificates: GitLab integrates with Let's Encrypt to automatically provision, secure, and renew free HTTPS SSL certificates for your custom domains.
• Access Control: You can secure your static site by enabling access control. Only authorized members of your GitLab group will be able to view the page, which is ideal for internal corporate wikis!