GitLab Pages

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab Pages publishes static websites directly from a repository in GitLab.

These websites:

  • Deploy automatically with GitLab CI/CD pipelines.
  • Support any static site generator (like Hugo, Jekyll, or Gatsby) or plain HTML, CSS, and JavaScript.
  • Run on GitLab-provided infrastructure at no additional cost.
  • Connect with custom domains and SSL/TLS certificates.
  • Control access through built-in authentication.
  • Scale reliably for personal, business, or project documentation sites.

Examples of SSGs supported by Pages

To publish a website with Pages, use any static site generator like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. Pages also supports websites written directly in plain HTML, CSS, and JavaScript. Dynamic server-side processing (like .php and .asp) is not supported. For more information, see Static vs dynamic websites.

Getting started

To create a GitLab Pages website:

DocumentDescription
Use the GitLab UI to create a simple .gitlab-ci.ymlAdd a Pages site to an existing project. Use the UI to set up a simple .gitlab-ci.yml.
Create a .gitlab-ci.yml file from scratchAdd a Pages site to an existing project. Learn how to create and configure your own CI file.
Use a .gitlab-ci.yml templateAdd a Pages site to an existing project. Use a pre-populated CI template file.
Fork a sample projectCreate a new project with Pages already configured by forking a sample project.
Use a project templateCreate a new project with Pages already configured by using a template.

To update a GitLab Pages website:

DocumentDescription
GitLab Pages domain names, URLs, and base URLsLearn about GitLab Pages default domains.
Explore GitLab PagesRequirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, and FAQ.
Custom domains and SSL/TLS CertificatesCustom domains and subdomains, DNS records, and SSL/TLS certificates.
Let’s Encrypt integrationSecure your Pages sites with Let’s Encrypt certificates, which are automatically obtained and renewed by GitLab.
RedirectsSet up HTTP redirects to forward one page to another.

For more information, see:

DocumentDescription
Static vs dynamic websitesStatic versus dynamic site overview.
Modern static site generatorsSSG overview.
Build any SSG site with GitLab PagesUse SSGs for GitLab Pages.

How it works

To use GitLab Pages, you must create a project in GitLab to upload your website’s files to. These projects can be either public, internal, or private.

GitLab always deploys your website from a specific folder called public in your repository. When you create a new project in GitLab, a repository becomes available automatically.

To deploy your site, GitLab uses its built-in tool called GitLab CI/CD to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named .gitlab-ci.yml, which you can create and modify. A user-defined job with pages: true property in the configuration file makes GitLab aware that you’re deploying a GitLab Pages website.

You can either use the GitLab default domain for GitLab Pages websites, *.gitlab.io, or your own domain (example.com). In that case, you must be an administrator in your domain’s registrar (or control panel) to set it up with Pages.

The following diagrams show the workflows you might follow to get started with Pages.

New projects for GitLab Pages

Access to your Pages site

If you’re using GitLab Pages default domain (.gitlab.io), your website is automatically secure and available under HTTPS. If you’re using your own custom domain, you can optionally secure it with SSL/TLS certificates.

If you’re using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable GitLab Pages Access Control.

If you’re using a self-managed instance, your websites are published on your own server, according to the Pages settings chosen by your sysadmin, who can make them public or internal.

Pages examples

These GitLab Pages website examples can teach you advanced techniques to use and adapt for your own needs:

Administer GitLab Pages for self-managed instances

If you are running a self-managed instance of GitLab, follow the administration steps to configure Pages.

Watch a video tutorial about how to get started with GitLab Pages administration.

Configure GitLab Pages in a Helm Chart (Kubernetes) instance

To configure GitLab Pages on instances deployed with Helm chart (Kubernetes), use either:

Security for GitLab Pages

Namespaces that contain .

If your username is example, your GitLab Pages website is located at example.gitlab.io. GitLab allows usernames to contain a ., so a user named bar.example could create a GitLab Pages website bar.example.gitlab.io that effectively is a subdomain of your example.gitlab.io website. Be careful if you use JavaScript to set cookies for your website. The safe way to manually set cookies with JavaScript is to not specify the domain at all:

Copy to clipboard
// Safe: This cookie is only visible to example.gitlab.io
document.cookie = "key=value";

// Unsafe: This cookie is visible to example.gitlab.io and its subdomains,
// regardless of the presence of the leading dot.
document.cookie = "key=value;domain=.example.gitlab.io";
document.cookie = "key=value;domain=example.gitlab.io";

This issue doesn’t affect users with a custom domain, or users who don’t set any cookies manually with JavaScript.

Shared cookies

By default, every project in a group shares the same domain, for example, group.gitlab.io. This means that cookies are also shared for all projects in a group.

To ensure each project uses different cookies, enable the Pages unique domains feature for your project.

Unique domains

History

By default, every new project uses pages unique domain. This is to avoid projects on the same group to share cookies.

The project maintainer can disable this feature on:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Deploy > Pages.
  3. Clear the Use unique domain checkbox.
  4. Select Save changes.

For example URLs, see GitLab Pages default domain names.

Primary domain

History

When you use GitLab Pages with custom domains, you can redirect all requests to GitLab Pages to a primary domain. When the primary domain is selected, users receive 308 Permanent Redirect status that redirects the browser to the selected primary domain. Browsers might cache this redirect.

Prerequisites:

  • You must have at least the Maintainer role for the project.
  • A custom domain must be set up.
  1. On the left sidebar, select Search or go to and find your project.
  2. Select Deploy > Pages.
  3. From the Primary domain dropdown list, select the domain to redirect to.
  4. Select Save changes.

Expiring deployments

History

You can configure your Pages deployments to be automatically deleted after a period of time has passed by specifying a duration at pages.expire_in:

Copy to clipboard
deploy-pages:
  stage: deploy
  script:
    - ...
  pages:  # specifies that this is a Pages job
    expire_in: 1 week
  artifacts:
    paths:
      - public

Expired deployments are stopped by a cron job that runs every 10 minutes. Stopped deployments are subsequently deleted by another cron job that also runs every 10 minutes. To recover it, follow the steps described in Recover a stopped deployment.

A stopped or deleted deployment is no longer available on the web. Users see a 404 Not found error page at its URL, until another deployment is created with the same URL configuration.

The previous YAML example uses user-defined job names.

Recover a stopped deployment

Prerequisites:

  • You must have at least the Maintainer role for the project.

To recover a stopped deployment that has not yet been deleted:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Deploy > Pages.
  3. Near Deployments turn on the Include stopped deployments toggle. If your deployment has not been deleted yet, it should be included in the list.
  4. Expand the deployment you want to recover and select Restore.

Delete a Deployment

To delete a deployment:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Deploy > Pages.
  3. Under Deployments, select any area on the deployment you wish to delete. The deployment details expand.
  4. Select Delete.

When you select Delete, your deployment is stopped immediately. Stopped deployments are deleted by a cron job running every 10 minutes.

To restore a stopped deployment that has not been deleted yet, see Recover a stopped deployment.

User-defined job names

History

To trigger a Pages deployment from any job, include the pages property in the job definition. It can either be a Boolean set to true or a hash.

For example, using true:

Copy to clipboard
deploy-my-pages-site:
  stage: deploy
  script:
    - npm run build
  pages: true  # specifies that this is a Pages job
  artifacts:
    paths:
      - public

For example, using a hash:

Copy to clipboard
deploy-pages-review-app:
  stage: deploy
  script:
    - npm run build
  pages:  # specifies that this is a Pages job
    path_prefix: '_staging'
  artifacts:
    paths:
    - public

If the pages property of a job named pages is set to false, no deployment is triggered:

Copy to clipboard
pages:
  pages: false

Parallel deployments

To create multiple deployments for your project at the same time, for example to create review apps, view the documentation on Parallel Deployments.