GitLab Pages

GitLab Pages turns files in your repository into a live website. Portfolios, documentation, school projects, and product landing pages all fit. A pipeline job copies the site files to GitLab, and a public web address appears.

Think of a shop window. You arrange the display inside the repository, and GitLab shows it to every passer-by on the internet.

What Pages Can Host

Works With PagesNeeds a Server
HTML, CSS, and JavaScript filesPHP applications
Static site generators such as Hugo, Jekyll, and EleventyApps that need a database
Documentation sitesPages with server-side login
Single-page apps built with React or VueBack-end APIs

How the Publishing Flow Works

  Push site files
        ↓
  Pipeline runs a job named "pages"
        ↓
  Job saves the public/ folder as an artifact
        ↓
  GitLab Pages publishes the folder
        ↓
  https://username.gitlab.io/my-site

Create a Basic Site

Step 1: Add an index.html File

Create a folder named site with a file named index.html.

<h1>Welcome to My Site</h1>
<p>Hosted on GitLab Pages.</p>

Step 2: Add the Pipeline File

Create .gitlab-ci.yml in the repository root.

pages:
  stage: deploy
  script:
    - mkdir -p public
    - cp -r site/* public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

The classic job name is pages, and the output folder is public. Recent GitLab versions add a dedicated pages keyword for custom job names. The classic form keeps working.

Step 3: Push and Wait

Commit both files and push to the default branch. Watch the job in Build → Pipelines. A green check means the site is live.

Find Your Site Address

Open Deploy → Pages. The page shows the live address.

Project LocationAddress Pattern
Personal namespacehttps://username.gitlab.io/project-name
Group namespacehttps://group-name.gitlab.io/project-name
Project named username.gitlab.iohttps://username.gitlab.io

Build with a Site Generator

A generator turns Markdown files into finished pages. The job installs the tool and writes the result into public.

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

Change the build command and folder name to match your tool. Hugo writes to public by default, so the move step drops out.

Folder Layout

  my-site/
  ├── .gitlab-ci.yml
  ├── site/
  │   ├── index.html
  │   ├── about.html
  │   ├── css/
  │   │   └── style.css
  │   └── images/
  └── README.md

  After the job runs:
  public/
  ├── index.html
  ├── about.html
  ├── css/
  └── images/

Control Who Sees the Site

Open Settings → General → Visibility, project features, permissions and find the Pages setting.

SettingResult
EveryoneAnyone on the internet opens the site
Only project membersVisitors must sign in and hold a role in the project

Private access helps with internal documentation and drafts.

Add a Custom Domain

  1. Open Deploy → Pages.
  2. Select New domain.
  3. Type your domain name, such as www.example.com.
  4. Copy the DNS records that GitLab shows.
  5. Add those records at your domain provider.
  6. Select Verify after DNS changes spread.

GitLab can issue a free HTTPS certificate through Let's Encrypt for verified domains.

Fix Common Problems

ProblemCheck
Site shows 404The public folder needs an index.html file at the top level
Styles missingUse relative paths such as css/style.css, not paths that start with a drive letter
Job does not runConfirm the rules match the branch you pushed
Old content appearsClear the browser cache and confirm the latest pipeline passed

Good Habits

  • Keep site content in Markdown and let a generator build the pages.
  • Compress images before upload.
  • Test changes on a feature branch before merging to the default branch.
  • Add a privacy page when the site collects any visitor data.