index.md 9.99 KB
Newer Older
1
2
---
description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.'
Marcia Ramos's avatar
Marcia Ramos committed
3
4
last_updated: 2019-06-04
type: index, reference
5
6
---

Marcia Ramos's avatar
Marcia Ramos committed
7
8
# GitLab Pages

Marcia Ramos's avatar
Marcia Ramos committed
9
10
11
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80) in GitLab Enterprise Edition 8.3.
> - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173) in GitLab Enterprise Edition 8.5.
> - [Ported](https://gitlab.com/gitlab-org/gitlab-ce/issues/14605) to GitLab Community Edition in GitLab 8.17.
Marcia Ramos's avatar
Marcia Ramos committed
12
13
14
> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47857) in GitLab 11.8.

15
16
17
18
**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
19
20
portfolios, documentation, manifestos, and business presentations.
You can also attribute any license to your content.
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

<table class="borderless-table center fixed-table">
  <tr>
    <td style="width: 22%"><img src="img/icons/cogs.png" alt="SSGs" class="image-noshadow half-width"></td>
    <td style="width: 4%">
      <strong>
        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
      </strong>
    </td>
    <td style="width: 22%"><img src="img/icons/monitor.png" alt="Websites" class="image-noshadow half-width"></td>
    <td style="width: 4%">
      <strong>
        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
      </strong>
    </td>
    <td style="width: 22%"><img src="img/icons/free.png" alt="Pages is free" class="image-noshadow half-width"></td>
    <td style="width: 4%">
      <strong>
        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
      </strong>
    </td>
    <td style="width: 22%"><img src="img/icons/lock.png" alt="Secure your website" class="image-noshadow half-width"></td>
  </tr>
  <tr>
    <td><em>Use any static website generator or plain HTML</em></td>
    <td></td>
    <td><em>Create websites for your projects, groups, or user account</em></td>
    <td></td>
    <td><em>Host on GitLab.com for free, or on your own GitLab instance</em></td>
    <td></td>
    <td><em>Connect your custom domain(s) and TLS certificates</em></td>
  </tr>
</table>

Pages is available for free for all GitLab.com users as well as for self-managed
instances (GitLab Core, Starter, Premium, and Ultimate).

## Overview

<div class="row">
<div class="col-md-9">
<p style="margin-top: 18px;">
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.</p>
<p>Pages does <strong>not</strong> support dynamic server-side processing, for instance, as <code>.php</code> and <code>.asp</code> requires. See this article to learn more about
<a href="https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p>
</div>
<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div>
</div>

### 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](../repository/index.md)
becomes available automatically.

To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md),
Marcia Ramos's avatar
Marcia Ramos committed
81
to build your site and publish it to the GitLab Pages server. The sequence of
82
83
84
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](getting_started_part_four.md) at will.

Marcia Ramos's avatar
Marcia Ramos committed
85
You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain-names),
86
87
88
89
90
91
`*.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.

Marcia Ramos's avatar
Marcia Ramos committed
92
### Getting started
93

94
To get started with GitLab Pages, you can either:
95

96
97
- [Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch).
- [Copy an existing example project](getting_started_part_two.md#fork-a-project-to-get-started-from).
Marcia Ramos's avatar
Marcia Ramos committed
98
- Use a bundled project template ready to go:
99

100
101
102
1. From the top navigation, click the **+** button and select **New project**.
1. Select **Create from Template**.
1. Choose one of the templates starting with **Pages**:
103

104
   ![Project templates for Pages](img/pages_project_templates_v11_8.png)
105

106
1. From the left sidebar, navigate to your project's **CI/CD > Pipelines**
Evan Read's avatar
Evan Read committed
107
108
   and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
   site to the server.
109
110
111
112
1. After the pipeline has finished successfully, wait approximately 30 minutes
   for your website to be visible. After waiting 30 minutes, find the link to
   visit your website from your project's **Settings > Pages**. If the link
   leads to a 404 page, wait a few minutes and try again.
Marcia Ramos's avatar
Marcia Ramos committed
113

114
Your website is then visible on your domain and you can modify your files
115
as you wish. For every modification pushed to your repository, GitLab CI/CD
116
will run a new pipeline to immediately publish your changes to the server.
Marcia Ramos's avatar
Marcia Ramos committed
117
118
119

_Advanced options:_

120
121
- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain)
- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain
Marcia Ramos's avatar
Marcia Ramos committed
122

Marcia Ramos's avatar
Marcia Ramos committed
123
## Availability
Marcia Ramos's avatar
Marcia Ramos committed
124

Marcia Ramos's avatar
Marcia Ramos committed
125
126
127
128
129
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](../../../administration/pages/index.md) chosen by your sysadmin,
who can opt for making them public or internal to your server.
Marcia Ramos's avatar
Marcia Ramos committed
130

Marcia Ramos's avatar
Marcia Ramos committed
131
132
133
134
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.
135

Marcia Ramos's avatar
Marcia Ramos committed
136
## Explore GitLab Pages
Marcia Ramos's avatar
Marcia Ramos committed
137

Marcia Ramos's avatar
Marcia Ramos committed
138
139
140
141
142
143
144
To learn more about configuration options for GitLab Pages, read the following:

| Document | Description |
| --- | --- |
| [Static websites and Pages domains](getting_started_part_one.md) | Understand what is a static website, and how GitLab Pages default domains work. |
| [Projects and URL structure](getting_started_part_two.md) | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. |
| [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. |
145
| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. |
Marcia Ramos's avatar
Marcia Ramos committed
146
|---+---|
147
| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
148
| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates automatically obtained and renewed by GitLab. |
Marcia Ramos's avatar
Marcia Ramos committed
149
150
151
152
153
| [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. |
|---+---|
| [Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. |
| [Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. |
| [Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | An overview on using SSGs for GitLab Pages. |
154

155
## Advanced use
156

157
158
159
160
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:

Marcia Ramos's avatar
Marcia Ramos committed
161
162
163
164
165
- [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/).
- [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/).
- [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/).
- [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/).
- [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/).
Marcia Ramos's avatar
Marcia Ramos committed
166

Marcia Ramos's avatar
Marcia Ramos committed
167
## Admin GitLab Pages for self-managed instances
Marcia Ramos's avatar
Marcia Ramos committed
168
169
170
171

Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with
the [admin guide](../../../administration/pages/index.md).

172
**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) for getting started with GitLab Pages admin!**
Marcia Ramos's avatar
Marcia Ramos committed
173
174
175
176
177

## More information about GitLab Pages

- Announcement (2016-12-24): ["We're bringing GitLab Pages to CE"](https://about.gitlab.com/2016/12/24/were-bringing-gitlab-pages-to-community-edition/)
- Announcement (2017-03-06): ["We are changing the IP of GitLab Pages on GitLab.com"](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/)