diff options
Diffstat (limited to 'doc/user/project/pages')
| -rw-r--r-- | doc/user/project/pages/custom_domains_ssl_tls_certification/index.md | 16 | ||||
| -rw-r--r-- | doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md | 19 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started/fork_sample_project.md | 61 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started/new_or_existing_website.md | 45 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started/pages_bundled_template.md | 29 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started_part_one.md | 53 | ||||
| -rw-r--r-- | doc/user/project/pages/getting_started_part_two.md | 171 | ||||
| -rw-r--r-- | doc/user/project/pages/img/new_project_for_pages_v12_5.png | bin | 0 -> 71618 bytes | |||
| -rw-r--r-- | doc/user/project/pages/img/pages_workflow_v12_5.png | bin | 0 -> 29541 bytes | |||
| -rw-r--r-- | doc/user/project/pages/index.md | 85 | ||||
| -rw-r--r-- | doc/user/project/pages/introduction.md | 35 | ||||
| -rw-r--r-- | doc/user/project/pages/lets_encrypt_for_gitlab_pages.md | 4 | ||||
| -rw-r--r-- | doc/user/project/pages/pages_access_control.md | 48 |
13 files changed, 261 insertions, 305 deletions
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 326a2d302d2..2f16606c5a8 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -169,6 +169,22 @@ from the GitLab project. in place: your domain will be periodically reverified, and may be disabled if the record is removed. +##### Troubleshooting Pages domain verification + +To manually verify that you have properly configured the domain verification +`TXT` DNS entry, you can run the following command in your terminal: + +``` +dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT +``` + +Expect the output: + +``` +;; ANSWER SECTION: +_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" +``` + ### Adding more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index c9b504dc6ee..1d64e843e46 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -5,7 +5,8 @@ description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." # GitLab Pages integration with Let's Encrypt -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). +This feature is in **beta** and may still have bugs. See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) for more information. The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains @@ -16,19 +17,11 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. CAUTION: **Caution:** -This feature is in **beta** and might present bugs and UX issues -such as [#64870](https://gitlab.com/gitlab-org/gitlab-foss/issues/64870). -See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) -for more information. - -CAUTION: **Caution:** -This feature covers only certificates for **custom domains**, -not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. -Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). ## Requirements -Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: +Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have: - Created a [project](../getting_started_part_two.md) in GitLab containing your website's source code. @@ -36,7 +29,7 @@ Before you can enable automatic provisioning of a SSL certificate for your domai pointing it to your Pages website. - [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) and verified your ownership. -- Have your website up and running, accessible through your custom domain. +- Verified your website is up and running, accessible through your custom domain. NOTE: **Note:** GitLab's Let's Encrypt integration is enabled and available on GitLab.com. @@ -45,7 +38,7 @@ For **self-managed** GitLab instances, make sure your administrator has ## Enabling Let's Encrypt integration for your custom domain -Once you've met the requirements, to enable Let's Encrypt integration: +Once you've met the requirements, enable Let's Encrypt integration: 1. Navigate to your project's **Settings > Pages**. 1. Find your domain and click **Details**. diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md new file mode 100644 index 00000000000..ac1a29ca2a0 --- /dev/null +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -0,0 +1,61 @@ +--- +type: reference, howto +--- + +# New Pages website from a forked sample + +To get started with GitLab Pages from a sample website, the easiest +way to do it is by using one of the [bundled templates](pages_bundled_template.md). +If you don't find one that suits your needs, you can opt by +forking (copying) a [sample project from the most popular Static Site Generators](https://gitlab.com/pages). + +<table class="borderless-table center fixed-table middle width-80"> + <tr> + <td style="width: 30%"><img src="../img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="../img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="../img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Fork an example project</em></td> + <td></td> + <td><em>Deploy your website</em></td> + <td></td> + <td><em>Visit your website's URL</em></td> + </tr> +</table> + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** + +1. [Fork](../../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. +1. 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. +1. Once the pipeline has finished successfully, find the link to visit your + website from your project's **Settings > Pages**. It can take aproximatelly + 30 minutes to be deployed. + +You can also take some **optional** further steps: + +- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: + +  + +- _Make it a user or group website._ To turn a **project website** forked + from the Pages group into a **user/group** website, you'll need to: + - Rename it to `namespace.gitlab.io`: go to your project's + **Settings > General** and expand **Advanced**. Scroll down to + **Rename repository** and change the path to `namespace.gitlab.io`. + - Adjust your SSG's [base URL](../getting_started_part_one.md#urls-and-baseurls) from `"project-name"` to + `""`. This setting will be at a different place for each SSG, as each of them + have their own structure and file tree. Most likely, it will be in the SSG's + config file. diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md new file mode 100644 index 00000000000..62b5fa33117 --- /dev/null +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -0,0 +1,45 @@ +--- +type: reference, howto +--- + +# Start a new Pages website from scratch or deploy an existing website + +If you already have a website and want to deploy it with GitLab Pages, +or, if you want to start a new site from scratch, you'll need to: + +- Create a new project in GitLab to hold your site content. +- Set up GitLab CI/CD to deploy your website to Pages. + +To do so, follow the steps below. + +1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, + click **New project**, and name it according to the + [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names). +1. Clone it to your local computer, add your website + files to your project, add, commit and push to GitLab. + Alternativelly, you can run `git init` in your local directory, + add the remote URL: + `git remote add origin git@gitlab.com:namespace/project-name.git`, + then add, commit, and push to GitLab. +1. From the your **Project**'s page, click **Set up CI/CD**: + +  + +1. Choose one of the templates from the dropbox menu. + Pick up the template corresponding to the SSG you're using (or plain HTML). + +  + + Note that, if you don't find a corresponding template, you can look into + [GitLab Pages group of sample projects](https://gitlab.com/pages), + you may find one among them that suits your needs, from which you + can copy `.gitlab-ci.yml`'s content and adjust for your case. + If you don't find it there either, [learn how to write a `.gitlab-ci.yml` + file for GitLab Pages](../getting_started_part_four.md). + +Once you have both site files and `.gitlab-ci.yml` in your project's +root, GitLab CI/CD will build your site and deploy it with Pages. +Once the first build passes, you access your site by +navigating to your **Project**'s **Settings** > **Pages**, +where you'll find its default URL. It can take approximately 30 min to be +deployed. diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md new file mode 100644 index 00000000000..802abeb3cc2 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -0,0 +1,29 @@ +--- +type: reference, howto +--- + +# New Pages website from a bundled template + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) +in GitLab 11.8. + +The simplest way to create a GitLab Pages site is to use one of the most +popular templates, which come already bundled with GitLab and are ready to go. + +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**: + +  + +1. 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. +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. + +Your website is then visible on your domain and you can modify your files +as you wish. For every modification pushed to your repository, GitLab CI/CD +will run a new pipeline to immediately publish your changes to the server. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 0b1cae9ab4c..b876e547ba5 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -3,25 +3,12 @@ last_updated: 2018-06-04 type: concepts, reference --- -# Static sites and GitLab Pages domains +# GitLab Pages domain names, URLs, and baseurls On this document, learn how to name your project for GitLab Pages according to your intended website's URL. -## Static sites - -GitLab Pages only supports static websites, meaning, -your output files must be HTML, CSS, and JavaScript only. - -To create your static site, you can either hardcode in HTML, -CSS, and JS, or use a [Static Site Generator (SSG)](https://www.staticgen.com/) -to simplify your code and build the static site for you, -which is highly recommendable and much faster than hardcoding. - -See the [further reading](#further-reading) section below for -references on static site concepts. - -## GitLab Pages domain names +## GitLab Pages default domain names >**Note:** If you use your own GitLab instance to deploy your @@ -93,11 +80,35 @@ To understand Pages domains clearly, read the examples below. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ +## URLs and baseurls + +Every Static Site Generator (SSG) default configuration expects +to find your website under a (sub)domain (`example.com`), not +in a subdirectory of that domain (`example.com/subdir`). Therefore, +whenever you publish a project website (`namespace.gitlab.io/project-name`), +you'll have to look for this configuration (base URL) on your SSG's +documentation and set it up to reflect this pattern. + +For example, for a Jekyll site, the `baseurl` is defined in the Jekyll +configuration file, `_config.yml`. If your website URL is +`https://john.gitlab.io/blog/`, you need to add this line to `_config.yml`: + +```yaml +baseurl: "/blog" +``` + +On the contrary, if you deploy your website after forking one of +our [default examples](https://gitlab.com/pages), the baseurl will +already be configured this way, as all examples there are project +websites. If you decide to make yours a user or group website, you'll +have to remove this configuration from your project. For the Jekyll +example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: + +```yaml +baseurl: "" +``` -### Further reading +## Custom domains -- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) -- Understand [how modern Static Site Generators work](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site -- You can use [any SSG with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -- Fork an [example project](https://gitlab.com/pages) to build your website based upon +GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. +See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index ff752917087..70e84f5d486 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,172 +1,5 @@ --- -last_updated: 2019-06-04 -type: reference, howto +redirect_to: 'index.md' --- -# Projects for GitLab Pages and URL structure - -## What you need to get started - -To get started with GitLab Pages, you need: - -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 static content of the website. - -Optional Features: - -1. A custom domain or subdomain. -1. A DNS pointing your (sub)domain to your Pages site. - 1. **Optional**: an SSL/TLS certificate so your custom - domain is accessible under HTTPS. - -The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)). - -## Project - -Your GitLab Pages project is a regular project created the -same way you do for the other ones. To get started with GitLab Pages, you have three ways: - -- [Use one of the popular project templates bundled with GitLab](#use-one-of-the-popular-pages-templates-bundled-with-gitlab). -- [Fork one of the templates from Page Examples](#fork-a-project-to-get-started-from). -- [Create a new project from scratch](#create-a-project-from-scratch). - -### Use one of the popular Pages templates bundled with GitLab - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) -in GitLab 11.8. - -The simplest way to create a GitLab Pages site is to -[use one of the most popular templates](index.md#getting-started), -which come already bundled with GitLab and are ready to go. - -### Fork a project to get started from - -If you don't find an existing project template that suits you, -we've created this [group](https://gitlab.com/pages) of default projects -containing the most popular SSGs templates to get you started. - -<table class="borderless-table center fixed-table middle width-80"> - <tr> - <td style="width: 30%"><img src="img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Fork an example project</em></td> - <td></td> - <td><em>Deploy your website</em></td> - <td></td> - <td><em>Visit your website's URL</em></td> - </tr> -</table> - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** - -1. [Fork](../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. -1. 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. -1. Once the pipeline has finished successfully, find the link to visit your - website from your project's **Settings > Pages**. - -You can also take some **optional** further steps: - -- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: - -  - -- _Make it a user or group website._ To turn a **project website** forked - from the Pages group into a **user/group** website, you'll need to: - - Rename it to `namespace.gitlab.io`: go to your project's - **Settings > General** and expand **Advanced**. Scroll down to - **Rename repository** and change the path to `namespace.gitlab.io`. - - Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to - `""`. This setting will be at a different place for each SSG, as each of them - have their own structure and file tree. Most likely, it will be in the SSG's - config file. - -### Create a project from scratch - -1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, - click **New project**, and name it according to the - [Pages domain names](getting_started_part_one.md#gitlab-pages-domain-names). -1. Clone it to your local computer, add your website - files to your project, add, commit and push to GitLab. -1. From the your **Project**'s page, click **Set up CI/CD**: - -  - -1. Choose one of the templates from the dropbox menu. - Pick up the template corresponding to the SSG you're using (or plain HTML). - -  - -Once you have both site files and `.gitlab-ci.yml` in your project's -root, GitLab CI/CD will build your site and deploy it with Pages. -Once the first build passes, you see your site is live by -navigating to your **Project**'s **Settings** > **Pages**, -where you'll find its default URL. - -> **Notes:** -> -> - GitLab Pages [supports any SSG](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but, -> if you don't find yours among the templates, you'll need -> to configure your own `.gitlab-ci.yml`. To do that, please -> read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among -> the [example projects](https://gitlab.com/pages). If you set -> up a new one, please -> [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) -> to our examples. -> -> - The second step _"Clone it to your local computer"_, can be done -> differently, achieving the same results: instead of cloning the bare -> 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 to GitLab. - -## URLs and Baseurls - -Every Static Site Generator (SSG) default configuration expects -to find your website under a (sub)domain (`example.com`), not -in a subdirectory of that domain (`example.com/subdir`). Therefore, -whenever you publish a project website (`namespace.gitlab.io/project-name`), -you'll have to look for this configuration (base URL) on your SSG's -documentation and set it up to reflect this pattern. - -For example, for a Jekyll site, the `baseurl` is defined in the Jekyll -configuration file, `_config.yml`. If your website URL is -`https://john.gitlab.io/blog/`, you need to add this line to `_config.yml`: - -```yaml -baseurl: "/blog" -``` - -On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the baseurl will -already be configured this way, as all examples there are project -websites. If you decide to make yours a user or group website, you'll -have to remove this configuration from your project. For the Jekyll -example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: - -```yaml -baseurl: "" -``` - -## Custom Domains - -GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. -See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. +This document was moved to [another location](index.md#getting-started). diff --git a/doc/user/project/pages/img/new_project_for_pages_v12_5.png b/doc/user/project/pages/img/new_project_for_pages_v12_5.png Binary files differnew file mode 100644 index 00000000000..8d2dc0bf9f5 --- /dev/null +++ b/doc/user/project/pages/img/new_project_for_pages_v12_5.png diff --git a/doc/user/project/pages/img/pages_workflow_v12_5.png b/doc/user/project/pages/img/pages_workflow_v12_5.png Binary files differnew file mode 100644 index 00000000000..ca5190fca79 --- /dev/null +++ b/doc/user/project/pages/img/pages_workflow_v12_5.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 7d533c6f9d1..abd67c90dd6 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -19,38 +19,7 @@ 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. -<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> +<img src="img/pages_workflow_v12_5.png" alt="Pages websites workflow" class="image-noshadow"> Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate). @@ -73,6 +42,7 @@ publish any website written directly in plain HTML, CSS, and JavaScript.</p> 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. @@ -80,67 +50,50 @@ becomes available automatically. To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md), 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](getting_started_part_four.md) at will. +`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain-names), +You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.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](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). -- Use a bundled project template ready to go: - -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**: - -  +- [Use a bundled website template ready to go](getting_started/pages_bundled_template.md). +- [Copy an existing sample](getting_started/fork_sample_project.md). +- [Create a website from scratch or deploy an existing one](getting_started/new_or_existing_website.md). -1. 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. -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. +<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> -Your website is then visible on your domain and you can modify your files -as you wish. For every modification pushed to your repository, GitLab CI/CD -will run a new pipeline to immediately publish your changes to the server. +Optional features: -_Advanced options:_ +- Use a [custom domain or subdomain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain). +- Add an [SSL/TLS certificate to secure your site under the HTTPS protocol](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages). -- [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 +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. ## Availability If you're using GitLab.com, your website will be publicly available to the internet. + +To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). + 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. -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](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 Pages domain names, URLs, and baseurls](getting_started_part_one.md) | Understand how GitLab Pages default domains work. | | [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) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. | |---+---| diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 86257e2aa03..01e1909f6d6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -69,40 +69,7 @@ don't have to create and edit HTML files manually. For example, Jekyll has the ## GitLab Pages Access Control **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. - -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. +To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). ## Unpublishing your Pages diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 1338c7e58f5..c9bd3e35a5f 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -21,8 +21,8 @@ open source Certificate Authority. To follow along with this tutorial, we assume you already have: -- Created a [project](getting_started_part_two.md) in GitLab which - contains your website's source code. +- [Created a project](index.md#getting-started) in GitLab + containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) pointing it to your Pages website. - [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md new file mode 100644 index 00000000000..cd715c6e3b9 --- /dev/null +++ b/doc/user/project/pages/pages_access_control.md @@ -0,0 +1,48 @@ +--- +type: reference, howto +--- + +# GitLab Pages Access Control + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. +> - Available on GitLab.com in GitLab 12.4. + +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. + +## Terminating a Pages session + +If you want to log out from your Pages website, +you can do so by revoking application access token for GitLab Pages: + +1. Navigate to your profile's **Settings > Applications**. +1. Find **Authorized applications** at the bottom of the page. +1. Find **GitLab Pages** and press the **Revoke** button. |
