9.6 KiB
| description | last_updated |
|---|---|
| Learn how to use GitLab Pages to deploy a static website at no additional cost. | 2019-03-05 |
GitLab Pages
- 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.
GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.
You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content.
 |
 |
 |
 |
|||
| Use any static website generator or plain HTML | Create websites for your projects, groups, or user account | Host on GitLab.com for free, or on your own GitLab instance | Connect your custom domain(s) and TLS certificates |
Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate).
Overview
To publish a website with Pages, you can use any Static Site Generator (SSG), such as 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. See this article to learn more about
static websites vs dynamic websites.
How it works
To use GitLab Pages, first you need to create a project in GitLab to upload your website's
files to. These projects can be either public, internal, or private, at your own choice.
GitLab will always deploy your website from a very specific folder called public in your
repository. Note that when you create a new project in GitLab, a repository
becomes available automatically.
To deploy your site, GitLab will use 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.
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.
Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your site under the HTTPS protocol.
Getting started
To get started with GitLab Pages, you can either:
- Create a project from scratch.
- Copy an existing example project.
- Use a bundled project template ready to go:
-
From the top navigation, click the + button and select New project.
-
Select Create from Template.
-
Choose one of the templates starting with Pages:
-
From the left sidebar, navigate to your project's CI/CD > Pipelines and click Run pipeline to trigger GitLab CI/CD to build and deploy your site to the server.
-
Once the pipeline has finished successfully, find the link to visit your website from your project's Settings > Pages.
Your website is then visible on your domain, and you can modify yourfiles as you wish. For every modification pushed to your repository, GitLab CI/CD will run a new pipeline to publish your changes to the server.
Advanced options:
- Use a custom domain
- Apply SSL/TLS certification to your custom domain
Availability
If you're using GitLab.com, your website will be publicly available to the internet. If you're using self-managed instances (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 opt for making them public or internal to your server.
Note that, 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.
Explore GitLab Pages
To learn more about configuration options for GitLab Pages, read the following:
| Document | Description |
|---|---|
| Static websites and Pages domains | Understand what is a static website, and how GitLab Pages default domains work. |
| Projects and URL structure | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. |
| GitLab CI/CD for GitLab Pages | Understand how to create your own .gitlab-ci.yml for your site. |
| Exploring GitLab Pages | Technical aspects, specific configuration options, custom 404 pages, limitations. |
| ---+--- | |
| Custom domains and SSL/TLS Certificates | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
| CloudFlare certificates | Secure your Pages site with CloudFlare certificates. |
| Let's Encrypt certificates | Secure your Pages site with Let's Encrypt certificates. |
| ---+--- | |
| Static vs dynamic websites | A conceptual overview on static versus dynamic sites. |
| Modern static site generators | A conceptual overview on SSGs. |
| Build any SSG site with GitLab Pages | An overview on using SSGs for GitLab Pages. |
Advanced use
There are quite some great examples of GitLab Pages websites built for some specific reasons. These examples can teach you some advanced techniques to use and adapt to your own needs:
- Posting to your GitLab Pages blog from iOS.
- GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline.
- GitLab CI: Deployment & environments.
- Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages.
- Publish code coverage reports with GitLab Pages.
Admin 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!
More information about GitLab Pages
- Announcement (2016-12-24): "We're bringing GitLab Pages to CE"
- Announcement (2017-03-06): "We are changing the IP of GitLab Pages on GitLab.com"