Refactor intro guide
Remove redundancies: - Domains - User/group/project sites
This commit is contained in:
Marcia Ramos
Achilleas Pipinellis
parent
4d39435ea8
commit
4dfd4d2744
8 changed files with 92 additions and 367 deletions
|
|
@ -167,7 +167,7 @@ Here's a list of what you can't do with subgroups:
|
|||
- [GitLab Pages](../../project/pages/index.md) supports projects hosted under
|
||||
a subgroup, but not subgroup websites.
|
||||
That means that only the highest-level group supports
|
||||
[group websites](../../project/pages/introduction.html#user-or-group-pages),
|
||||
[group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names),
|
||||
although you can have project websites under a subgroup.
|
||||
- It is not possible to share a project with a group that's an ancestor of
|
||||
the group the project is in. That means you can only share as you walk down
|
||||
|
|
|
|||
|
|
@ -1,42 +1,11 @@
|
|||
---
|
||||
last_updated: 2018-02-16
|
||||
author: Marcia Ramos
|
||||
author_gitlab: marcia
|
||||
level: beginner
|
||||
article_type: user guide
|
||||
date: 2017-02-22
|
||||
---
|
||||
|
||||
# Static sites and GitLab Pages domains
|
||||
|
||||
This document is the beginning of a comprehensive guide, made for those who want to
|
||||
publish a website with GitLab Pages but aren't familiar with
|
||||
the entire process involved.
|
||||
|
||||
This [first document](#what-you-need-to-know-before-getting-started) of this series will present you to the concepts of
|
||||
static sites, and go over how the default Pages domains work.
|
||||
|
||||
The [second document](getting_started_part_two.md) covers how to get started with GitLab Pages: deploy
|
||||
a website from a forked project or create a new one from scratch.
|
||||
|
||||
The [third document](getting_started_part_three.md) will show you how to set up a custom domain or subdomain
|
||||
to your site already deployed.
|
||||
|
||||
The [fourth document](getting_started_part_four.md) will show you how to create and tweak GitLab CI for
|
||||
GitLab Pages.
|
||||
|
||||
To **enable** GitLab Pages for GitLab CE (Community Edition)
|
||||
and GitLab EE (Enterprise Edition), please read the
|
||||
[admin documentation](https://docs.gitlab.com/ce/administration/pages/index.html),
|
||||
and/or watch this [video tutorial](https://youtu.be/dD8c7WNcc6s).
|
||||
|
||||
>**Note:**
|
||||
For this guide, we assume you already have GitLab Pages
|
||||
server up and running for your GitLab instance.
|
||||
|
||||
## What you need to know before getting started
|
||||
|
||||
Before we begin, let's understand a few concepts first.
|
||||
On this docucument, learn how to name your project for GitLab Pages
|
||||
according to your intended website's URL.
|
||||
|
||||
## Static sites
|
||||
|
||||
|
|
@ -48,20 +17,10 @@ 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.
|
||||
|
||||
### Further reading
|
||||
See the [further reading](#further-reading) section below for
|
||||
references on static site concepts.
|
||||
|
||||
- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/)
|
||||
- Understand [how modern Static Site Generators work](https://about.gitlab.com/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/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 domain
|
||||
|
||||
If you set up a GitLab Pages project on GitLab.com,
|
||||
it will automatically be accessible under a
|
||||
[subdomain of `namespace.gitlab.io`](introduction.md#gitlab-pages-on-gitlabcom).
|
||||
The `namespace` is defined by your username on GitLab.com,
|
||||
or the group name you created this project under.
|
||||
## GitLab Pages domain names
|
||||
|
||||
>**Note:**
|
||||
If you use your own GitLab instance to deploy your
|
||||
|
|
@ -70,11 +29,32 @@ Pages wildcard domain. This guide is valid for any GitLab instance,
|
|||
you just need to replace Pages wildcard domain on GitLab.com
|
||||
(`*.gitlab.io`) with your own.
|
||||
|
||||
Learn more about [namespaces](../../group/index.md#namespaces).
|
||||
If you set up a GitLab Pages project on GitLab,
|
||||
it will automatically be accessible under a
|
||||
subdomain of `namespace.example.io`.
|
||||
The [`namespace`](../../group/index.md#namespaces)
|
||||
is defined by your username on GitLab.com,
|
||||
or the group name you created this project under.
|
||||
For GitLab self-managed instances, replace `example.io`
|
||||
with your instance's Pages domain. For GitLab.com,
|
||||
Pages domains are `*.gitlab.io`.
|
||||
|
||||
### Practical examples
|
||||
| Type of GitLab Pages | The name of the project created in GitLab | Website URL |
|
||||
| -------------------- | ------------ | ----------- |
|
||||
| User pages | `username.example.io` | `http(s)://username.example.io` |
|
||||
| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` |
|
||||
| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` |
|
||||
| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`|
|
||||
| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`|
|
||||
|
||||
#### Project Websites
|
||||
CAUTION: **Warning:**
|
||||
There are some known [limitations](introduction.md#limitations)
|
||||
regarding namespaces served under the general domain name and HTTPS.
|
||||
Make sure to read that section.
|
||||
|
||||
To understand Pages domains clearly, read the examples below.
|
||||
|
||||
### Project website examples
|
||||
|
||||
- You created a project called `blog` under your username `john`,
|
||||
therefore your project URL is `https://gitlab.com/john/blog/`.
|
||||
|
|
@ -92,7 +72,7 @@ Learn more about [namespaces](../../group/index.md#namespaces).
|
|||
GitLab Pages for this project, the site will live under
|
||||
`https://engineering.gitlab.io/docs/workflows`.
|
||||
|
||||
#### User and Group Websites
|
||||
### User and Group website examples
|
||||
|
||||
- Under your username, `john`, you created a project called
|
||||
`john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`.
|
||||
|
|
@ -103,8 +83,6 @@ Learn more about [namespaces](../../group/index.md#namespaces).
|
|||
Once you enable GitLab Pages for your project,
|
||||
your website will be published under `https://websites.gitlab.io`.
|
||||
|
||||
> Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
|
||||
|
||||
**General example:**
|
||||
|
||||
- On GitLab.com, a project site will always be available under
|
||||
|
|
@ -115,3 +93,10 @@ Learn more about [namespaces](../../group/index.md#namespaces).
|
|||
Pages server domain. Ask your sysadmin for this information.
|
||||
|
||||
_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._
|
||||
|
||||
### Further reading
|
||||
|
||||
- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/)
|
||||
- Understand [how modern Static Site Generators work](https://about.gitlab.com/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/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
|
||||
|
|
@ -177,9 +177,6 @@ Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionho
|
|||
although it's usually a matter of minutes to complete. Until it does, verification
|
||||
will fail and attempts to visit your domain will respond with a 404.
|
||||
|
||||
Read through the [general documentation on GitLab Pages](introduction.md#add-a-custom-domain-to-your-pages-website) to learn more about adding
|
||||
custom domains to GitLab Pages sites.
|
||||
|
||||
### Redirecting `www.domain.com` to `domain.com` with Cloudflare
|
||||
|
||||
If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both
|
||||
|
|
|
|||
|
|
@ -104,8 +104,8 @@ from the Pages group into a **user/group** website, you'll need to:
|
|||
### Create a project from scratch
|
||||
|
||||
1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**,
|
||||
click **New project**, and name it considering the
|
||||
[practical examples](getting_started_part_one.md#practical-examples).
|
||||
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**:
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 3.7 KiB |
BIN
doc/user/project/pages/img/remove_pages.png
Normal file
BIN
doc/user/project/pages/img/remove_pages.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
|
|
@ -5,6 +5,11 @@ last_updated: 2019-03-05
|
|||
|
||||
# GitLab Pages
|
||||
|
||||
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80) in GitLab Enterprise Edition 8.3.
|
||||
> - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173) in GitLab Enterprise Edition 8.5.
|
||||
> - [Ported](https://gitlab.com/gitlab-org/gitlab-ce/issues/14605) to GitLab Community Edition in GitLab 8.17.
|
||||
> Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
|
||||
|
||||
**GitLab Pages is a feature that allows you to publish static websites
|
||||
directly from a repository in GitLab.**
|
||||
|
||||
|
|
@ -83,7 +88,7 @@ that will build your site and publish it to the GitLab Pages server. The sequenc
|
|||
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.
|
||||
|
||||
You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain),
|
||||
You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-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.
|
||||
|
||||
|
|
@ -128,7 +133,7 @@ To learn more about GitLab Pages, read the following tutorials:
|
|||
- [Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls
|
||||
- [GitLab Pages 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
|
||||
- [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site
|
||||
- [Technical aspects, custom 404 pages, limitations](introduction.md)
|
||||
- [Exploring GitLab Pages](introduction.md): Technical aspects, specific configuration options, custom 404 pages, limitations
|
||||
|
||||
### GitLab Pages with Static Site Generators (SSGs)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,178 +1,44 @@
|
|||
# Exploring GitLab Pages
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - 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.
|
||||
> - GitLab Pages [was ported][ce-14605] to Community Edition in GitLab 8.17.
|
||||
> - This document is about the user guide. To learn how to enable GitLab Pages
|
||||
> across your GitLab instance, visit the [administrator documentation](../../../administration/pages/index.md).
|
||||
This document is a user guide to explore the options and settings
|
||||
GitLab Pages offers.
|
||||
|
||||
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.
|
||||
To familiarize yourself with GitLab Pages first:
|
||||
|
||||
Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) for specific
|
||||
information, if you are using GitLab.com to host your website.
|
||||
- Read an [introduction to GitLab Pages](index.md#overview).
|
||||
- Learn [how to get started with Pages](index.md#getting-started).
|
||||
- Learn how to enable GitLab Pages
|
||||
across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md).
|
||||
|
||||
## Getting started with GitLab Pages domains
|
||||
|
||||
> **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 types of pages one might create:
|
||||
|
||||
- Pages per user (`username.example.io`) or per group (`groupname.example.io`)
|
||||
- Pages per project (`username.example.io/projectname` or `groupname.example.io/projectname`)
|
||||
|
||||
In GitLab, usernames and groupnames are unique and we often refer to them
|
||||
as [namespaces](../../group/index.md#namespaces). There can be only one namespace
|
||||
in a GitLab instance. Below you
|
||||
can see the connection between the type of GitLab Pages, what the project name
|
||||
that is created on GitLab looks like and the website URL it will be ultimately
|
||||
be served on.
|
||||
|
||||
| Type of GitLab Pages | The name of the project created in GitLab | Website URL |
|
||||
| -------------------- | ------------ | ----------- |
|
||||
| User pages | `username.example.io` | `http(s)://username.example.io` |
|
||||
| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` |
|
||||
| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` |
|
||||
| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`|
|
||||
| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`|
|
||||
|
||||
> **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 requirements
|
||||
## Pages requirements
|
||||
|
||||
In brief, this is what you need to upload your website in GitLab Pages:
|
||||
|
||||
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
|
||||
1. Push a [`.gitlab-ci.yml` file][yaml] in the root directory
|
||||
of your repository with a specific job named [`pages`][pages]
|
||||
1. Set up a GitLab Runner to build your website
|
||||
1. Domain of the instance: domain name that is used for GitLab Pages
|
||||
(ask your administrator).
|
||||
1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`][pages] in the root directory of your repository.
|
||||
1. A directory called `public` in your site's repo containing the content
|
||||
to be published.
|
||||
1. GitLab Runner enabled for the project.
|
||||
|
||||
> **Note:**
|
||||
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.
|
||||
## GitLab Pages on GitLab.com
|
||||
|
||||
### User or group Pages
|
||||
If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to host your website, then:
|
||||
|
||||
For user and group pages, the name of the project should be specific to the
|
||||
username or groupname and the general domain name that is used for GitLab Pages.
|
||||
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.
|
||||
- The domain name for GitLab Pages on GitLab.com is `gitlab.io`.
|
||||
- Custom domains and TLS support are enabled.
|
||||
- Shared runners are enabled by default, provided for free and can be used to
|
||||
build your website. If you want you can still bring your own Runner.
|
||||
|
||||
To create a group page, the steps are the same like when creating a website for
|
||||
users. Just make sure that you are creating the project within the group's
|
||||
namespace.
|
||||
## Example projects
|
||||
|
||||
|
||||
Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete list of example projects. Contributions are very welcome.
|
||||
|
||||
---
|
||||
## Specific configuration options for Pages
|
||||
|
||||
After you push some static content to your repository and GitLab Runner uploads
|
||||
the artifacts to GitLab CI, you will be able to access your website under
|
||||
`http(s)://username.example.io`. Keep reading to find out how.
|
||||
Learn how to set up GitLab CI/CD for specific use cases.
|
||||
|
||||
>**Note:**
|
||||
If your username/groupname contains a dot, for example `foo.bar`, you will not
|
||||
be able to use the wildcard domain HTTPS, read more at [limitations](#limitations).
|
||||
|
||||
### Project Pages
|
||||
|
||||
GitLab Pages for projects can be created by both user and group accounts.
|
||||
The steps to create a project page for a user or a group are identical:
|
||||
|
||||
1. Create a new project
|
||||
1. Push a [`.gitlab-ci.yml` file][yaml] in the root directory
|
||||
of your repository with a specific job named [`pages`][pages].
|
||||
1. Set up a GitLab Runner to build your website
|
||||
|
||||
A user's project will be served under `http(s)://username.example.io/projectname`
|
||||
whereas a group's project under `http(s)://groupname.example.io/projectname`.
|
||||
|
||||
For practical examples for group and project Pages, read through the guide
|
||||
[GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#practical-examples).
|
||||
|
||||
## Quick Start
|
||||
|
||||
Read through [GitLab Pages Quick Start Guide][pages-quick] or watch the video tutorial on
|
||||
[how to publish a website with GitLab Pages on GitLab.com from a forked project][video-pages-fork].
|
||||
|
||||
See also [All you Need to Know About GitLab Pages][pages-index-guide] for a list with all the resources we have for GitLab Pages.
|
||||
|
||||
### Explore the contents of `.gitlab-ci.yml`
|
||||
|
||||
The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that
|
||||
gives you absolute control over the build process. You can actually watch your
|
||||
website being built live by following the CI job traces.
|
||||
|
||||
For a simplified user guide on setting up GitLab CI/CD for Pages, read through
|
||||
the article [GitLab Pages from A to Z: Part 4 - Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
|
||||
|
||||
> **Note:**
|
||||
> Before reading this section, make sure you familiarize yourself with GitLab CI
|
||||
> and the specific syntax of[`.gitlab-ci.yml`][yaml] by
|
||||
> following our [quick start guide].
|
||||
|
||||
To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the
|
||||
rules below:
|
||||
|
||||
1. A special job named [`pages`][pages] must be defined
|
||||
1. Any static content which will be served by GitLab Pages must be placed under
|
||||
a `public/` directory
|
||||
1. `artifacts` with a path to the `public/` directory must be defined
|
||||
|
||||
In its simplest form, `.gitlab-ci.yml` looks like:
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
script:
|
||||
- my_commands
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
```
|
||||
|
||||
When the Runner reaches to build the `pages` job, it executes whatever is
|
||||
defined in the `script` parameter and if the job completes with a non-zero
|
||||
exit status, it then uploads the `public/` directory to GitLab Pages.
|
||||
|
||||
The `public/` directory should contain all the static content of your website.
|
||||
Depending on how you plan to publish your website, the steps defined in the
|
||||
[`script` parameter](../../../ci/yaml/README.md#script) may differ.
|
||||
|
||||
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#onlyexcept-basic),
|
||||
whenever a new commit is pushed to whatever branch or tag, the Pages will be
|
||||
overwritten. In the example below, we limit the Pages to be deployed whenever
|
||||
a commit is pushed only on the `master` branch:
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
script:
|
||||
- my_commands
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
only:
|
||||
- master
|
||||
```
|
||||
|
||||
We then tell the Runner to treat the `public/` directory as `artifacts` and
|
||||
upload it to GitLab. And since all these parameters were all under a `pages`
|
||||
job, the contents of the `public` directory will be served by GitLab Pages.
|
||||
|
||||
#### How `.gitlab-ci.yml` looks like when the static content is in your repository
|
||||
### `.gitlab-ci.yml` for plain HTML websites
|
||||
|
||||
Supposed your repository contained the following files:
|
||||
|
||||
|
|
@ -201,55 +67,11 @@ pages:
|
|||
- master
|
||||
```
|
||||
|
||||
#### How `.gitlab-ci.yml` looks like when using a static generator
|
||||
### `.gitlab-ci.yml` for a static site generator
|
||||
|
||||
In general, GitLab Pages support any kind of [static site generator][staticgen],
|
||||
since `.gitlab-ci.yml` can be configured to run any possible command.
|
||||
See this document for a [step-by-step guide](getting_started_part_four.md).
|
||||
|
||||
In the root directory of your Git repository, place the source files of your
|
||||
favorite static generator. Then provide a `.gitlab-ci.yml` file which is
|
||||
specific to your static generator.
|
||||
|
||||
The example below, uses [Jekyll] to build the static site:
|
||||
|
||||
```yaml
|
||||
image: ruby:2.1 # the script will run in Ruby 2.1 using the Docker image ruby:2.1
|
||||
|
||||
pages: # the build job must be named pages
|
||||
script:
|
||||
- gem install jekyll # we install jekyll
|
||||
- jekyll build -d public/ # we tell jekyll to build the site for us
|
||||
artifacts:
|
||||
paths:
|
||||
- public # this is where the site will live and the Runner uploads it in GitLab
|
||||
only:
|
||||
- master # this script is only affecting the master branch
|
||||
```
|
||||
|
||||
Here, we used the Docker executor and in the first line we specified the base
|
||||
image against which our jobs will run.
|
||||
|
||||
You have to make sure that the generated static files are ultimately placed
|
||||
under the `public` directory, that's why in the `script` section we run the
|
||||
`jekyll` command that jobs the website and puts all content in the `public/`
|
||||
directory. Depending on the static generator of your choice, this command will
|
||||
differ. Search in the documentation of the static generator you will use if
|
||||
there is an option to explicitly set the output directory. If there is not
|
||||
such an option, you can always add one more line under `script` to rename the
|
||||
resulting directory in `public/`.
|
||||
|
||||
We then tell the Runner to treat the `public/` directory as `artifacts` and
|
||||
upload it to GitLab.
|
||||
|
||||
---
|
||||
|
||||
See the [jekyll example project][pages-jekyll] to better understand how this
|
||||
works.
|
||||
|
||||
For a list of Pages projects, see the [example projects](#example-projects) to
|
||||
get you started.
|
||||
|
||||
#### How to set up GitLab Pages in a repository where there's also actual code
|
||||
### `.gitlab-ci.yml` for a repository where there's also actual code
|
||||
|
||||
Remember that GitLab Pages are by default branch/tag agnostic and their
|
||||
deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit
|
||||
|
|
@ -294,28 +116,6 @@ also includes `.gitlab-ci.yml`.
|
|||
[jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master
|
||||
[jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages
|
||||
|
||||
## Next steps
|
||||
|
||||
So you have successfully deployed your website, congratulations! Let's check
|
||||
what more you can do with GitLab Pages.
|
||||
|
||||
### 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/pages/plain-html)
|
||||
- [Jekyll](https://gitlab.com/pages/jekyll)
|
||||
- [Hugo](https://gitlab.com/pages/hugo)
|
||||
- [Middleman](https://gitlab.com/pages/middleman)
|
||||
- [Hexo](https://gitlab.com/pages/hexo)
|
||||
- [Brunch](https://gitlab.com/pages/brunch)
|
||||
- [Metalsmith](https://gitlab.com/pages/metalsmith)
|
||||
- [Harp](https://gitlab.com/pages/harp)
|
||||
|
||||
Visit the GitLab Pages group for a full list of example projects:
|
||||
<https://gitlab.com/groups/pages>.
|
||||
|
||||
### Serving compressed assets
|
||||
|
||||
Most modern browsers support downloading files in a compressed format. This
|
||||
|
|
@ -408,52 +208,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.
|
||||
|
||||
### Add a custom domain to your Pages website
|
||||
|
||||
For a complete guide on Pages domains, read through the article
|
||||
[GitLab Pages from A to Z: Part 3 - GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md)
|
||||
|
||||
If this setting is enabled by your GitLab administrator, you should be able to
|
||||
see the **New Domain** button when visiting your project's settings through the
|
||||
gear icon in the top right and then navigating to **Pages**.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
You can add multiple domains pointing to your website hosted under GitLab.
|
||||
Once the domain is added, you can see it listed under the **Domains** section.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
As a last step, you need to configure your DNS and add a CNAME pointing to your
|
||||
user/group page. Click on the **Details** button of a domain for further
|
||||
instructions.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
>**Note:**
|
||||
Currently there is support only for custom domains on per-project basis. That
|
||||
means that if you add a custom domain (`example.com`) for your user website
|
||||
(`username.example.io`), a project that is served under `username.example.io/foo`,
|
||||
will not be accessible under `example.com/foo`.
|
||||
|
||||
### Secure your custom domain website with TLS
|
||||
|
||||
When you add a new custom domain, you also have the chance to add a TLS
|
||||
certificate. If this setting is enabled by your GitLab administrator, you
|
||||
should be able to see the option to upload the public certificate and the
|
||||
private key when adding a new domain.
|
||||
|
||||
|
||||
|
||||
For a complete guide on Pages domains, read through the article
|
||||
[GitLab Pages from A to Z: Part 3 - GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md)
|
||||
|
||||
### Custom error codes pages
|
||||
|
||||
You can provide your own 403 and 404 error pages by creating the `403.html` and
|
||||
|
|
@ -472,29 +226,17 @@ If the case of `404.html`, there are different scenarios. For example:
|
|||
- If you use a custom domain and try to access `/non/existing_file`, GitLab
|
||||
Pages will try to serve only `/404.html`.
|
||||
|
||||
### Remove the contents of your pages
|
||||
### Redirects in GitLab 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. Simple as that.
|
||||
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 on GitLab.com
|
||||
|
||||
If you are using GitLab.com to host your website, then:
|
||||
|
||||
- The general domain name for GitLab Pages on GitLab.com is `gitlab.io`.
|
||||
- Custom domains and TLS support are enabled.
|
||||
- Shared runners are enabled by default, provided for free and can be used to
|
||||
build your website. If you want you can still bring your own Runner.
|
||||
|
||||
The rest of the guide still applies.
|
||||
|
||||
See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain).
|
||||
|
||||
## GitLab Pages access control **[CORE ONLY]**
|
||||
### GitLab Pages Access Control **[CORE ONLY]**
|
||||
|
||||
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
|
||||
|
||||
|
|
@ -536,6 +278,15 @@ 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.
|
||||
|
||||
|
||||
|
||||
## Limitations
|
||||
|
||||
When using Pages under the general domain of a GitLab instance (`*.example.io`),
|
||||
|
|
@ -550,16 +301,6 @@ don't redirect HTTP to HTTPS.
|
|||
GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations).
|
||||
You can only create the highest-level group website.
|
||||
|
||||
## 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).
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
### Can I download my generated pages?
|
||||
|
|
@ -581,8 +322,6 @@ No, you don't. You can create your project first and it will be accessed under
|
|||
For a list of known issues, visit GitLab's [public issue tracker].
|
||||
|
||||
[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
|
||||
[gitlab ci]: https://about.gitlab.com/gitlab-ci
|
||||
[gitlab runner]: https://docs.gitlab.com/runner/
|
||||
|
|
@ -592,7 +331,6 @@ For a list of known issues, visit GitLab's [public issue tracker].
|
|||
[pages-jekyll]: https://gitlab.com/pages/jekyll
|
||||
[metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh
|
||||
[public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=pages
|
||||
[ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605
|
||||
[quick start guide]: ../../../ci/quick_start/README.md
|
||||
[pages-index-guide]: index.md
|
||||
[pages-quick]: getting_started_part_one.md
|
||||
|
|
|
|||
Loading…
Reference in a new issue