GitLab Pages | GitLab (2024)

• Getting started
• How it works
• Access to your Pages site
• Pages examples
• Administer GitLab Pages for self-managed instances
  • Configure GitLab Pages in a Helm Chart (Kubernetes) instance
• Security for GitLab Pages
  • Namespaces that contain .
• Unique domains
• Create multiple deployments
  • Example configuration
  • Enable multiple deployments
  • Limits
  • Path clash
  • Use multiple deployments to create pages environments
  • Deployments deletion
    • Auto-clean

With GitLab Pages, you can publish static websites directly from a repositoryin GitLab.

To publish a website with Pages, you can use any static site generator,like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can alsopublish any website written directly in plain HTML, CSS, and JavaScript.

Pages does not support dynamic server-side processing, for instance, as .php and .asp requires.For more information, seeStatic vs dynamic websites.

Getting started

To create a GitLab Pages website:

To update a GitLab Pages website:

For more information, see:

How it works

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

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

To deploy your site, GitLab uses its built-in tool called GitLab CI/CDto build your site and publish it to the GitLab Pages server. The sequence ofscripts 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 specific job called pages in the configuration file makes GitLab aware that you’re deploying aGitLab 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, youmust 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.

Access to your Pages site

If you’re using GitLab Pages default domain (.gitlab.io), your website isautomatically secure and available under HTTPS. If you’re using your own customdomain, 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 yourown server, according to the Pages settingschosen by your sysadmin, who can make them public or internal.

Pages examples

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

• Posting to your GitLab Pages blog from iOS.
• GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline.
• .
• Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages.
• Publish code coverage reports with GitLab Pages.

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 via Helm chart (Kubernetes), use either:

• The gitlab-pages subchart.
• An external GitLab Pages instance.

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 createa GitLab Pages website bar.example.gitlab.io that effectively is a subdomain of yourexample.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:

// Safe: This cookie is only visible to example.gitlab.iodocument.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 anycookies manually with JavaScript.

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

By default, every new project uses pages unique domain. This is to avoid projects on the same groupto 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. Deselect the Use unique domain checkbox.
4. Select Save changes.

Create multiple deployments

Use the pages.path_prefix CI/CD option to configure a prefix for the GitLab Pages URL.A prefix allows you to differentiate between multiple GitLab Pages deployments:

• Main Pages deployment: a Pages deployment created with a blank path_prefix.
• Extra Pages deployment: a Pages deployment created with a non-blank path_prefix

The value of pages.path_prefix is:

• Converted to lowercase.
• Shortened to 63 bytes.
• Any character except numbers (0-9) and letter (a-z) is replaced with a hyphen (-).
• Leading and trailing hyphens (-) are removed.

Example configuration

Consider a project such as https://gitlab.example.com/namespace/project. By default, its main Pages deployment can be accessed through:

• When using a unique domain: https://project-namespace-uniqueid.gitlab.io/.
• When not using a unique domain: https://namespace.gitlab.io/project.

If a pages.path_prefix is configured to the project branch names,like path_prefix = $CI_COMMIT_BRANCH, and there’s abranch named username/testing_feature, this extra Pages deployment would be accessible through:

• When using a unique domain: https://project-namespace-uniqueid.gitlab.io/username-testing-feature.
• When not using a unique domain: https://namespace.gitlab.io/project/username-testing-feature.

Enable multiple deployments

To enable multiple GitLab Pages deployments:

1. On the left sidebar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. Select Use multiple deployments.

Limits

The number of extra deployments is limited by the root-level namespace. For specific limits for:

• GitLab.com, see Other limits.
• Self-managed GitLab instances, seeNumber of extra Pages deployments when using multiple deployments.

Path clash

pages.path_prefix can take dynamic values from CI/CD variablesthat can create pages deployments which could clash with existing paths in your site.For example, given an existing GitLab Pages site with the following paths:

/index.html/documents/index.html

If a pages.path_prefix is documents, that version will override the existing path.In other words, https://namespace.gitlab.io/project/documents/index.html will point to the/index.html on the documents deployment of the site, instead of documents/index.html of themain deployment of the site.

Mixing CI/CD variables with other strings can reduce the path clashpossibility. For example:

pages: stage: deploy script: - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}" variables: PAGES_PREFIX: "" # No prefix by default (master) pages: path_prefix: "$PAGES_PREFIX" artifacts: paths: - public rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run on default branch (with default PAGES_PREFIX) - if: $CI_COMMIT_BRANCH == "staging" # Run on master (with default PAGES_PREFIX) variables: PAGES_PREFIX: '_stg' # Prefix with _stg for the staging branch - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Conditionally change the prefix for Merge Requests when: manual # Run pages manually on Merge Requests variables: PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # Prefix with the mr-<iid>, like `mr-123`

Some other examples of mixing variables with strings for dynamic prefixes:

• pages.path_prefix: 'mr-$CI_COMMIT_REF_SLUG': Branch or tag name prefixed with mr-, like mr-branch-name.
• pages.path_prefix: '_${CI_MERGE_REQUEST_IID}_': Merge request numberprefixed ans suffixed with _, like _123_.

Use multiple deployments to create pages environments

You can use multiple GitLab Pages deployments to create a new environment.For example:

pages: stage: deploy script: - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}" variables: PAGES_PREFIX: "" # no prefix by default (master) pages: path_prefix: "$PAGES_PREFIX" environment: name: "Pages ${PAGES_PREFIX}" url: "${CI_PAGES_URL}/${PAGES_PREFIX}" artifacts: paths: - public rules: - if: $CI_COMMIT_BRANCH == "staging" # ensure to run on master (with default PAGES_PREFIX) variables: PAGES_PREFIX: '_stg' # prefix with _stg for the staging branch - if: $CI_PIPELINE_SOURCE == "merge_request_event" # conditionally change the prefix on Merge Requests when: manual # run pages manually on Merge Requests variables: PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # prefix with the mr-<iid>, like `mr-123`

With this configuration, users will have the access to each GitLab Pages deployment through the UI.When using environments for pages, all pages environments arelisted on the project environment list.

You can also group similar environments together.

Deployments deletion

Auto-clean

Extra Pages deployments, created by a merge request with a path_prefix, are automatically deleted when themerge request is closed or merged.