1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
# GitLab Pages
> **Note:**
> This feature was [introduced][ee-80] in GitLab EE 8.3.
> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
With GitLab Pages you can host for free your static websites on GitLab.
Combined with the power of GitLab CI and the help of GitLab Runner you can
deploy static pages for your individual projects, your user or your group.
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Enable the pages feature in your GitLab EE instance](#enable-the-pages-feature-in-your-gitlab-ee-instance)
- [Getting started with GitLab Pages](#getting-started-with-gitlab-pages)
- [GitLab pages per user or group](#gitlab-pages-per-user-or-group)
- [GitLab pages per project](#gitlab-pages-per-project)
- [Enable the pages feature in your project](#enable-the-pages-feature-in-your-project)
- [Remove the contents of your pages](#remove-the-contents-of-your-pages)
- [Explore the contents of .gitlab-ci.yml](#explore-the-contents-of-gitlab-ci-yml)
- [Next steps](#next-steps)
- [Adding a custom domain to your Pages website](#adding-a-custom-domain-to-your-pages-website)
- [Securing your custom domain website with TLS](#securing-your-custom-domain-website-with-tls)
- [Example projects](#example-projects)
- [Custom error codes pages](#custom-error-codes-pages)
- [Limitations](#limitations)
- [Frequently Asked Questions](#frequently-asked-questions)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Enable the pages feature in your GitLab EE instance
The administrator guide is located at [administration](administration.md).
## Getting started with GitLab Pages
GitLab Pages rely heavily on GitLab CI and its ability to upload artifacts.
The steps that are performed from the initialization of a project to the
creation of the static content, can be summed up to:
1. Find out the general domain name that is used for GitLab Pages
(ask your administrator). This is very important, so you should first make
sure you get that right.
1. Create a project (its name should be specific according to the case)
1. Provide a specific job named `pages` in `.gitlab-ci.yml`
1. GitLab Runner builds the project
1. GitLab CI uploads the artifacts
1. The [GitLab Pages daemon][pages-daemon] serves the content
As a user, you should normally be concerned only with the first three or four
items. If [shared runners](../ci/runners/README.md) are enabled by your GitLab
administrator, you should be able to use them instead of bringing your own.
> **Note:**
> In the rest of this document we will assume that the general domain name that
> is used for GitLab Pages is `example.io`.
In general there are two kinds of pages one might create:
- Pages per user/group
- Pages per project
In GitLab, usernames and groupnames are unique and often people refer to them
as namespaces. There can be only one namespace in a GitLab instance.
> **Warning:**
> There are some known [limitations](#limitations) regarding namespaces served
> under the general domain name and HTTPS. Make sure to read that section.
### GitLab pages per user or group
Head over your GitLab instance that supports GitLab Pages and create a
repository named `username.example.io`, where `username` is your username on
GitLab. If the first part of the project name doesn't match exactly your
username, it won’t work, so make sure to get it right.
---
To create a group page the steps are exactly the same. Just make sure that
you are creating the project within the group's namespace.
After you upload some static content to your repository, you will be able to
access it under `http(s)://username.example.io`. Keep reading to find out how.
### GitLab pages per project
> **Note:**
> You do _not_ have to create a project named `username.example.io` in order to
> serve a project's page.
GitLab Pages for projects
### Enable the pages feature in your project
The GitLab Pages feature needs to be explicitly enabled for each project
under its **Settings**.
### Remove the contents of your pages
Pages can be explicitly removed from a project by clicking **Remove Pages**
Go to your project's **Settings > Pages**.
### Explore the contents of .gitlab-ci.yml
Before reading this section, make sure you familiarize yourself with GitLab CI
and the specific syntax of[`.gitlab-ci.yml`](../ci/yaml/README.md) by
following our [quick start guide](../ci/quick_start/README.md).
---
To make use of GitLab Pages, your `.gitlab-ci.yml` must follow the rules below:
1. A special `pages` job must be defined
1. Any static content must be placed under a `public/` directory
1. `artifacts` with a path to the `public/` directory must be defined
Be aware that Pages are by default branch/tag agnostic and their deployment
relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the
`pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except),
whenever a new commit is pushed to whatever branch or tag, the Pages will be
overwritten. In the examples below, we limit the Pages to be deployed whenever
a commit is pushed only on the `master` branch, which is advisable to do so.
The pages are created after the build completes successfully and the artifacts
for the `pages` job are uploaded to GitLab.
The example below uses [Jekyll][] and generates the created HTML files
under the `public/` directory.
```yaml
image: ruby:2.1
pages:
script:
- gem install jekyll
- jekyll build -d public/
artifacts:
paths:
- public
only:
- master
```
The example below doesn't use any static site generator, but simply moves all
files from the root of the project to the `public/` directory. The `.public`
workaround is so `cp` doesn't also copy `public/` to itself in an infinite
loop.
```yaml
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
only:
- master
```
## Next steps
### Adding a custom domain to your Pages website
### Securing your custom domain website with TLS
### Example projects
Below is a list of example projects for GitLab Pages with a plain HTML website
or various static site generators. Contributions are very welcome.
- [Plain HTML](https://gitlab.com/gitlab-examples/pages-plain-html)
- [Jekyll](https://gitlab.com/gitlab-examples/pages-jekyll)
### Custom error codes pages
You can provide your own 403 and 404 error pages by creating the `403.html` and
`404.html` files respectively in the `public/` directory that will be included
in the artifacts.
## Limitations
When using Pages under the general domain of a GitLab instance (`*.example.io`),
you _cannot_ use HTTPS with sub-subdomains. That means that if your
username/groupname contains a dot, for example `foo.bar`, the domain
`https://foo.bar.example.io` will _not_ work. This is a limitation of the
[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you
don't redirect HTTP to HTTPS.
[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC"
## Frequently Asked Questions
**Q: Can I download my generated pages?**
Sure. All you need to do is download the artifacts archive from the build page.
**Q: Can I use GitLab Pages if my project is private?**
Yes. GitLab Pages doesn't care whether you set your project's visibility level
to private, internal or public.
---
[jekyll]: http://jekyllrb.com/
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173
[pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages
|
