GitLab Pages

Version history
  • Introduced in GitLab Enterprise Edition 8.3.
  • Custom CNAMEs with TLS support were introduced in GitLab Enterprise Edition 8.5.
  • Ported to GitLab Community Edition in GitLab 8.17.
  • Support for subgroup project’s websites was introduced in GitLab 11.8.
  • Bundled project templates were introduced in GitLab 11.8.

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

  • Use for any personal or business website.
  • Use any Static Site Generator (SSG) or plain HTML.
  • Create websites for your projects, groups, or user account.
  • Host your site on your own GitLab instance or on GitLab.com for free.
  • Connect your custom domains and TLS certificates.
  • Attribute any license to your content.

To publish a website with Pages, you can use any SSG, like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also publish 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. Learn more about static websites vs dynamic websites.

Learn more about GitLab Pages:

Examples of SSGs supported by Pages
Document Description
GitLab Pages domain names, URLs, and baseurls How GitLab Pages default domains work.
GitLab CI/CD for GitLab Pages Create your own site by using .gitlab-ci.yml.
Exploring GitLab Pages Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ.
Custom domains and SSL/TLS Certificates Add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates.
Let’s Encrypt integration Secure your Pages sites with Let’s Encrypt certificates, which are automatically obtained and renewed by GitLab.
CloudFlare certificates Secure your Pages site with CloudFlare certificates.
Static vs dynamic websites Static versus dynamic site overview.
Modern static site generators SSG overview.
Build any SSG site with GitLab Pages Use 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 very 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 at will. A specific job called pages in the configuration file will make GitLab aware that you are deploying a GitLab Pages website.

You can either use GitLab’s default domain for GitLab Pages websites, *.gitlab.io, or your own domain (example.com). In that case, you’ll need admin access to your domain’s registrar (or control panel) to set it up with Pages.

Getting started

To get started with GitLab Pages, you can:

New projects for GitLab Pages

Optional features:

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

Access to your Pages site

If you’re using GitLab.com, your website will be publicly available to the internet.

To restrict access to your website, enable GitLab Pages Access Control.

If you’re using a self-managed instance (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the Pages admin settings chosen by your sysadmin, who can make them public or internal.

Pages examples

There are some great examples of GitLab Pages websites built for specific reasons. These examples can teach you advanced techniques to use and adapt to your own needs:

Administer GitLab Pages for self-managed instances

Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with the admin guide.

Watch a video tutorial for getting started with GitLab Pages admin!