Skip to content

G
gitlab-ce
Commit fabca7ab authored by Mike Lewis's avatar Mike Lewis
Browse files
Options

Merge branch 'docs-ssot-pages' into 'master' 

Docs: ssot epic - Pages

Closes #58178 and #61517

See merge request gitlab-org/gitlab-ce!29144
parents bb491910 b3ef3afc
Hide whitespace changes
Inline Side-by-side
Showing with 118 additions and 121 deletions
doc/user/project/pages/getting_started_part_four.md
View file @ fabca7ab
---
last_updated: 2018-02-16
author: Marcia Ramos
author_gitlab: marcia
level: intermediate
article_type: user guide
date: 2017-02-22
last_updated: 2019-06-04
type: reference, howto
---
# Creating and Tweaking GitLab CI/CD for GitLab Pages
......
doc/user/project/pages/getting_started_part_one.md
View file @ fabca7ab
---
last_updated: 2018-02-16
last_updated: 2018-06-04
type: concepts, reference
---
# Static sites and GitLab Pages domains
......
doc/user/project/pages/getting_started_part_three.md
View file @ fabca7ab
---
last_updated: 2018-11-19
author: Marcia Ramos
author_gitlab: marcia
level: beginner
article_type: user guide
date: 2017-02-22
last_updated: 2019-06-04
type: concepts, reference, howto
---
# GitLab Pages custom domains and SSL/TLS Certificates
......
doc/user/project/pages/getting_started_part_two.md
View file @ fabca7ab
---
last_updated: 2019-03-05
author: Marcia Ramos
author_gitlab: marcia
level: beginner
article_type: user guide
date: 2017-02-22
last_updated: 2019-06-04
type: reference, howto
---
# Projects for GitLab Pages and URL structure
......@@ -13,11 +9,11 @@ date: 2017-02-22
To get started with GitLab Pages, you need:
1. A project
1. A configuration file (`.gitlab-ci.yml`) to deploy your site
1. A project, thus a repository to hold your website's codebase.
1. A configuration file (`.gitlab-ci.yml`) to deploy your site.
1. A specific `job` called `pages` in the configuration file
that will make GitLab aware that you are deploying a GitLab Pages website
1. A `public` directory with the content of the website
that will make GitLab aware that you are deploying a GitLab Pages website.
1. A `public` directory with the static content of the website.
Optional Features:
......@@ -140,7 +136,7 @@ where you'll find its default URL.
repository to you local computer and moving your site files into it,
you can run `git init` in your local website directory, add the
remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`,
then add, commit, and push.
then add, commit, and push to GitLab.
## URLs and Baseurls
......@@ -173,4 +169,4 @@ baseurl: ""
## Custom Domains
GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS.
Please check the [next part](getting_started_part_three.md) of this series for an overview.
See [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) for more information.
doc/user/project/pages/index.md
View file @ fabca7ab
---
description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.'
last_updated: 2019-03-05
last_updated: 2019-06-04
type: index, reference
---
# GitLab Pages
......@@ -140,7 +141,7 @@ To learn more about configuration options for GitLab Pages, read the following:
| [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. |
| [Exploring GitLab Pages](introduction.md) | Technical aspects, specific configuration options, custom 404 pages, limitations. |
| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, custom 404 pages, limitations, FAQ. |
|---+---|
| [Custom domains and SSL/TLS Certificates](getting_started_part_three.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
| [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. |
......
doc/user/project/pages/introduction.md
View file @ fabca7ab
---
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?
......
doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
View file @ fabca7ab
---
description: "How to secure GitLab Pages websites with Let's Encrypt."
type: howto
last_updated: 2019-06-04
---
# Let's Encrypt for GitLab Pages
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7