|
|
|
@ -1,3 +1,8 @@
|
|
|
|
|
---
|
|
|
|
|
type: reference
|
|
|
|
|
last_updated: 2018-06-04
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Exploring GitLab Pages
|
|
|
|
|
|
|
|
|
|
This document is a user guide to explore the options and settings
|
|
|
|
@ -10,7 +15,7 @@ To familiarize yourself with GitLab Pages first:
|
|
|
|
|
- Learn how to enable GitLab Pages
|
|
|
|
|
across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md).
|
|
|
|
|
|
|
|
|
|
## Pages requirements
|
|
|
|
|
## GitLab Pages requirements
|
|
|
|
|
|
|
|
|
|
In brief, this is what you need to upload your website in GitLab Pages:
|
|
|
|
|
|
|
|
|
@ -34,6 +39,99 @@ If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to hos
|
|
|
|
|
|
|
|
|
|
Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete list of example projects. Contributions are very welcome.
|
|
|
|
|
|
|
|
|
|
## 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 root directory of the `public/` directory
|
|
|
|
|
that will be included in the artifacts. Usually this is the root directory of
|
|
|
|
|
your project, but that may differ depending on your static generator
|
|
|
|
|
configuration.
|
|
|
|
|
|
|
|
|
|
If the case of `404.html`, there are different scenarios. For example:
|
|
|
|
|
|
|
|
|
|
- If you use project Pages (served under `/projectname/`) and try to access
|
|
|
|
|
`/projectname/non/existing_file`, GitLab Pages will try to serve first
|
|
|
|
|
`/projectname/404.html`, and then `/404.html`.
|
|
|
|
|
- If you use user/group Pages (served under `/`) and try to access
|
|
|
|
|
`/non/existing_file` GitLab Pages will try to serve `/404.html`.
|
|
|
|
|
- If you use a custom domain and try to access `/non/existing_file`, GitLab
|
|
|
|
|
Pages will try to serve only `/404.html`.
|
|
|
|
|
|
|
|
|
|
## Redirects in GitLab Pages
|
|
|
|
|
|
|
|
|
|
Since you cannot use any custom server configuration files, like `.htaccess` or
|
|
|
|
|
any `.conf` file, if you want to redirect a page to another
|
|
|
|
|
location, you can use the [HTTP meta refresh tag][metarefresh].
|
|
|
|
|
|
|
|
|
|
Some static site generators provide plugins for that functionality so that you
|
|
|
|
|
don't have to create and edit HTML files manually. For example, Jekyll has the
|
|
|
|
|
[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
|
|
|
|
|
|
|
|
|
|
## GitLab Pages Access Control **[CORE ONLY]**
|
|
|
|
|
|
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
|
|
|
|
|
|
|
|
|
|
NOTE: **Note:**
|
|
|
|
|
GitLab Pages access control is not activated on GitLab.com. You can check its
|
|
|
|
|
progress on the
|
|
|
|
|
[infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5576).
|
|
|
|
|
|
|
|
|
|
You can enable Pages access control on your project, so that only
|
|
|
|
|
[members of your project](../../permissions.md#project-members-permissions)
|
|
|
|
|
(at least Guest) can access your website:
|
|
|
|
|
|
|
|
|
|
1. Navigate to your project's **Settings > General > Permissions**.
|
|
|
|
|
1. Toggle the **Pages** button to enable the access control.
|
|
|
|
|
|
|
|
|
|
NOTE: **Note:**
|
|
|
|
|
If you don't see the toggle button, that means that it's not enabled.
|
|
|
|
|
Ask your administrator to [enable it](../../../administration/pages/index.md#access-control).
|
|
|
|
|
|
|
|
|
|
1. The Pages access control dropdown allows you to set who can view pages hosted
|
|
|
|
|
with GitLab Pages, depending on your project's visibility:
|
|
|
|
|
|
|
|
|
|
- If your project is private:
|
|
|
|
|
- **Only project members**: Only project members will be able to browse the website.
|
|
|
|
|
- **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
|
|
|
|
|
- If your project is internal:
|
|
|
|
|
- **Only project members**: Only project members will be able to browse the website.
|
|
|
|
|
- **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership.
|
|
|
|
|
- **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
|
|
|
|
|
- If your project is public:
|
|
|
|
|
- **Only project members**: Only project members will be able to browse the website.
|
|
|
|
|
- **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
|
|
|
|
|
|
|
|
|
|
1. Click **Save changes**.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
The next time someone tries to access your website and the access control is
|
|
|
|
|
enabled, they will be presented with a page to sign into GitLab and verify they
|
|
|
|
|
can access the website.
|
|
|
|
|
|
|
|
|
|
## Unpublishing your Pages
|
|
|
|
|
|
|
|
|
|
If you ever feel the need to purge your Pages content, you can do so by going
|
|
|
|
|
to your project's settings through the gear icon in the top right, and then
|
|
|
|
|
navigating to **Pages**. Hit the **Remove pages** button and your Pages website
|
|
|
|
|
will be deleted.
|
|
|
|
|
|
|
|
|
|
![Remove pages](img/remove_pages.png)
|
|
|
|
|
|
|
|
|
|
## 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"
|
|
|
|
|
|
|
|
|
|
GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations).
|
|
|
|
|
You can only create the highest-level group website.
|
|
|
|
|
|
|
|
|
|
## Specific configuration options for Pages
|
|
|
|
|
|
|
|
|
|
Learn how to set up GitLab CI/CD for specific use cases.
|
|
|
|
@ -208,99 +306,6 @@ NOTE: **Note:**
|
|
|
|
|
When `public/data/index.html` exists, it takes priority over the `public/data.html`
|
|
|
|
|
file for both the `/data` and `/data/` URL paths.
|
|
|
|
|
|
|
|
|
|
### 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 root directory of the `public/` directory
|
|
|
|
|
that will be included in the artifacts. Usually this is the root directory of
|
|
|
|
|
your project, but that may differ depending on your static generator
|
|
|
|
|
configuration.
|
|
|
|
|
|
|
|
|
|
If the case of `404.html`, there are different scenarios. For example:
|
|
|
|
|
|
|
|
|
|
- If you use project Pages (served under `/projectname/`) and try to access
|
|
|
|
|
`/projectname/non/existing_file`, GitLab Pages will try to serve first
|
|
|
|
|
`/projectname/404.html`, and then `/404.html`.
|
|
|
|
|
- If you use user/group Pages (served under `/`) and try to access
|
|
|
|
|
`/non/existing_file` GitLab Pages will try to serve `/404.html`.
|
|
|
|
|
- If you use a custom domain and try to access `/non/existing_file`, GitLab
|
|
|
|
|
Pages will try to serve only `/404.html`.
|
|
|
|
|
|
|
|
|
|
### Redirects in GitLab Pages
|
|
|
|
|
|
|
|
|
|
Since you cannot use any custom server configuration files, like `.htaccess` or
|
|
|
|
|
any `.conf` file, if you want to redirect a page to another
|
|
|
|
|
location, you can use the [HTTP meta refresh tag][metarefresh].
|
|
|
|
|
|
|
|
|
|
Some static site generators provide plugins for that functionality so that you
|
|
|
|
|
don't have to create and edit HTML files manually. For example, Jekyll has the
|
|
|
|
|
[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
|
|
|
|
|
|
|
|
|
|
### GitLab Pages Access Control **[CORE ONLY]**
|
|
|
|
|
|
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
|
|
|
|
|
|
|
|
|
|
NOTE: **Note:**
|
|
|
|
|
GitLab Pages access control is not activated on GitLab.com. You can check its
|
|
|
|
|
progress on the
|
|
|
|
|
[infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5576).
|
|
|
|
|
|
|
|
|
|
You can enable Pages access control on your project, so that only
|
|
|
|
|
[members of your project](../../permissions.md#project-members-permissions)
|
|
|
|
|
(at least Guest) can access your website:
|
|
|
|
|
|
|
|
|
|
1. Navigate to your project's **Settings > General > Permissions**.
|
|
|
|
|
1. Toggle the **Pages** button to enable the access control.
|
|
|
|
|
|
|
|
|
|
NOTE: **Note:**
|
|
|
|
|
If you don't see the toggle button, that means that it's not enabled.
|
|
|
|
|
Ask your administrator to [enable it](../../../administration/pages/index.md#access-control).
|
|
|
|
|
|
|
|
|
|
1. The Pages access control dropdown allows you to set who can view pages hosted
|
|
|
|
|
with GitLab Pages, depending on your project's visibility:
|
|
|
|
|
|
|
|
|
|
- If your project is private:
|
|
|
|
|
- **Only project members**: Only project members will be able to browse the website.
|
|
|
|
|
- **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
|
|
|
|
|
- If your project is internal:
|
|
|
|
|
- **Only project members**: Only project members will be able to browse the website.
|
|
|
|
|
- **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership.
|
|
|
|
|
- **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
|
|
|
|
|
- If your project is public:
|
|
|
|
|
- **Only project members**: Only project members will be able to browse the website.
|
|
|
|
|
- **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
|
|
|
|
|
|
|
|
|
|
1. Click **Save changes**.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
The next time someone tries to access your website and the access control is
|
|
|
|
|
enabled, they will be presented with a page to sign into GitLab and verify they
|
|
|
|
|
can access the website.
|
|
|
|
|
|
|
|
|
|
## Unpublishing your Pages
|
|
|
|
|
|
|
|
|
|
If you ever feel the need to purge your Pages content, you can do so by going
|
|
|
|
|
to your project's settings through the gear icon in the top right, and then
|
|
|
|
|
navigating to **Pages**. Hit the **Remove pages** button and your Pages website
|
|
|
|
|
will be deleted.
|
|
|
|
|
|
|
|
|
|
![Remove pages](img/remove_pages.png)
|
|
|
|
|
|
|
|
|
|
## 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"
|
|
|
|
|
|
|
|
|
|
GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations).
|
|
|
|
|
You can only create the highest-level group website.
|
|
|
|
|
|
|
|
|
|
## Frequently Asked Questions
|
|
|
|
|
|
|
|
|
|
### Can I download my generated pages?
|
|
|
|
|