debian-mirror-gitlab/doc/user/project/pages/index.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

141 lines
7.7 KiB
Markdown
Raw Normal View History

2018-11-08 19:23:39 +05:30
---
description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.'
2022-06-21 17:19:12 +05:30
stage: Create
group: Editor
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2018-11-08 19:23:39 +05:30
---
2021-09-04 01:27:46 +05:30
# GitLab Pages **(FREE)**
2018-03-17 18:26:18 +05:30
2021-11-18 22:05:49 +05:30
With GitLab Pages, you can publish static websites directly from a repository
in GitLab.
2018-12-05 23:21:45 +05:30
<div class="row">
<div class="col-md-9">
<p style="margin-top: 18px;">
2020-06-23 00:09:42 +05:30
<ul>
<li>Use for any personal or business website.</li>
<li>Use any Static Site Generator (SSG) or plain HTML.</li>
<li>Create websites for your projects, groups, or user account.</li>
<li>Host your site on your own GitLab instance or on GitLab.com for free.</li>
<li>Connect your custom domains and TLS certificates.</li>
<li>Attribute any license to your content.</li>
</ul>
</p>
2018-12-05 23:21:45 +05:30
</div>
2021-01-29 00:20:46 +05:30
<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="middle display-block"></div>
2018-12-05 23:21:45 +05:30
</div>
2021-11-18 22:05:49 +05:30
To publish a website with Pages, you can use any static site generator,
like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also
2020-06-23 00:09:42 +05:30
publish any website written directly in plain HTML, CSS, and JavaScript.
2018-12-05 23:21:45 +05:30
2021-11-18 22:05:49 +05:30
Pages does not support dynamic server-side processing, for instance, as `.php` and `.asp` requires.
2020-06-23 00:09:42 +05:30
Learn more about
[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/).
## Getting started
To create a GitLab Pages website:
| Document | Description |
2021-11-18 22:05:49 +05:30
|----------|-------------|
| [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. |
2020-07-28 23:09:34 +05:30
| [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. |
2021-11-18 22:05:49 +05:30
| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. |
| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. |
2020-06-23 00:09:42 +05:30
To update a GitLab Pages website:
| Document | Description |
2021-11-18 22:05:49 +05:30
|----------|-------------|
2020-06-23 00:09:42 +05:30
| [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md) | Learn about GitLab Pages default domains. |
2021-11-18 22:05:49 +05:30
| [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, and FAQ. |
2020-06-23 00:09:42 +05:30
| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. |
| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. |
2020-11-24 15:15:51 +05:30
| [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. |
2020-06-23 00:09:42 +05:30
Learn more and see examples:
| Document | Description |
2021-11-18 22:05:49 +05:30
|----------|-------------|
2020-06-23 00:09:42 +05:30
| [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | Static versus dynamic site overview. |
| [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | SSG overview. |
| [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | Use SSGs for GitLab Pages. |
2019-12-26 22:10:19 +05:30
2020-06-23 00:09:42 +05:30
## How it works
To use GitLab Pages, you must create a project in GitLab to upload your website's
files to. These projects can be either public, internal, or private.
2021-11-18 22:05:49 +05:30
GitLab always deploys your website from a specific folder called `public` in your
2020-06-23 00:09:42 +05:30
repository. When you create a new project in GitLab, a [repository](../repository/index.md)
2018-12-05 23:21:45 +05:30
becomes available automatically.
2021-09-30 23:02:18 +05:30
To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/index.md)
2019-07-31 22:56:46 +05:30
to build your site and publish it to the GitLab Pages server. The sequence of
2018-12-05 23:21:45 +05:30
scripts that GitLab CI/CD runs to accomplish this task is created from a file named
2021-03-08 18:12:59 +05:30
`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md).
A specific `job` called `pages` in the configuration file makes GitLab aware that you're deploying a
GitLab Pages website.
2018-12-05 23:21:45 +05:30
2021-02-22 17:27:13 +05:30
You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names),
2021-03-08 18:12:59 +05:30
`*.gitlab.io`, or your own domain (`example.com`). In that case, you
2022-04-04 11:22:00 +05:30
must be an administrator in your domain's registrar (or control panel) to set it up with Pages.
2018-12-05 23:21:45 +05:30
2020-06-23 00:09:42 +05:30
The following diagrams show the workflows you might follow to get started with Pages.
2018-12-05 23:21:45 +05:30
2021-01-29 00:20:46 +05:30
<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages">
2018-03-17 18:26:18 +05:30
2020-06-23 00:09:42 +05:30
## Access to your Pages site
2018-03-17 18:26:18 +05:30
2021-11-18 22:05:49 +05:30
If you're using GitLab Pages default domain (`.gitlab.io`), your website is
automatically secure and available under HTTPS. If you're using your own custom
domain, you can optionally secure it with SSL/TLS certificates.
2018-03-17 18:26:18 +05:30
2021-03-08 18:12:59 +05:30
If you're using GitLab.com, your website is publicly available to the internet.
2019-12-26 22:10:19 +05:30
To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md).
2021-11-18 22:05:49 +05:30
If you're using a self-managed instance, your websites are published on your
own server, according to the [Pages settings](../../../administration/pages/index.md)
chosen by your sysadmin, who can make them public or internal.
2018-03-17 18:26:18 +05:30
2020-06-23 00:09:42 +05:30
## Pages examples
2018-03-17 18:26:18 +05:30
2021-11-18 22:05:49 +05:30
These GitLab Pages website examples can teach you advanced techniques to use
and adapt for your own needs:
2018-12-05 23:21:45 +05:30
2019-12-21 20:55:43 +05:30
- [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/blog/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/blog/2016/07/29/the-basics-of-gitlab-ci/).
2021-04-17 20:07:23 +05:30
- [GitLab CI: Deployment & environments](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/).
2019-12-21 20:55:43 +05:30
- [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/blog/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/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/).
2018-03-17 18:26:18 +05:30
2020-06-23 00:09:42 +05:30
## Administer GitLab Pages for self-managed instances
2018-03-17 18:26:18 +05:30
2021-11-18 22:05:49 +05:30
If you are running a self-managed instance of GitLab,
2020-06-23 00:09:42 +05:30
[follow the administration steps](../../../administration/pages/index.md) to configure Pages.
2018-03-17 18:26:18 +05:30
2020-06-23 00:09:42 +05:30
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) about how to get started with GitLab Pages administration.
2021-01-03 14:25:43 +05:30
## Security for GitLab Pages
2021-11-18 22:05:49 +05:30
If your username is `example`, your GitLab Pages website is located at `example.gitlab.io`.
GitLab allows usernames to contain a `.`, so a user named `bar.example` could create
a GitLab Pages website `bar.example.gitlab.io` that effectively is a subdomain of your
`example.gitlab.io` website. Be careful if you use JavaScript to set cookies for your website.
2021-01-03 14:25:43 +05:30
The safe way to manually set cookies with JavaScript is to not specify the `domain` at all:
```javascript
2021-11-18 22:05:49 +05:30
// Safe: This cookie is only visible to example.gitlab.io
2021-01-03 14:25:43 +05:30
document.cookie = "key=value";
2021-11-18 22:05:49 +05:30
// Unsafe: This cookie is visible to example.gitlab.io and its subdomains,
2021-01-03 14:25:43 +05:30
// regardless of the presence of the leading dot.
2021-11-18 22:05:49 +05:30
document.cookie = "key=value;domain=.example.gitlab.io";
document.cookie = "key=value;domain=example.gitlab.io";
2021-01-03 14:25:43 +05:30
```
This issue doesn't affect users with a custom domain, or users who don't set any
cookies manually with JavaScript.