Exploring GitLab Pages

原文：https://docs.gitlab.com/ee/user/project/pages/introduction.html

• GitLab Pages requirements
• GitLab Pages on GitLab.com
• Example projects
• Custom error codes Pages
• Redirects in GitLab Pages
• GitLab Pages Access Control
• Unpublishing your Pages
• Limitations

• Specific configuration options for Pages

  • .gitlab-ci.yml for plain HTML websites
  • .gitlab-ci.yml for a static site generator
  • .gitlab-ci.yml for a repository where there’s also actual code
  • Serving compressed assets
  • Resolving ambiguous URLs

• Frequently Asked Questions

  • Can I download my generated pages?
  • Can I use GitLab Pages if my project is private?
  • Do I need to create a user/group website before creating a project website?

• Known issues

Exploring GitLab Pages

本文档是用户指南，用于探索 GitLab Pages 提供的选项和设置.

首先要熟悉 GitLab 页面：

• 阅读有关 GitLab Pages的介绍 .
• Learn how to get started with Pages.
• 在管理员文档中了解如何在整个 GitLab 实例上启用 GitLab 页面.

GitLab Pages requirements

简而言之，这是您需要在 GitLab 页面中上传网站的内容：

1. 实例的域：用于 GitLab 页面的域名（询问管理员）.
2. GitLab CI / CD：一个.gitlab-ci.yml文件，在存储库的根目录中有一个名为pages的特定作业.
3. 您网站存储库中一个名为public的目录，其中包含要发布的内容.
4. 为项目启用了 GitLab Runner.

GitLab Pages on GitLab.com

如果您使用GitLab.com上的GitLab 页面来托管您的网站，则：

• The domain name for GitLab Pages on GitLab.com is gitlab.io.
• 自定义域和 TLS 支持已启用.
• 共享运行器默认情况下处于启用状态，免费提供，可用于构建您的网站. 如果您愿意，仍然可以携带自己的跑步者.

Example projects

访问GitLab 页面组以获得示例项目的完整列表. 欢迎捐款.

Custom error codes Pages

您可以通过在将包含在工件中的public/目录的根目录中分别创建403.html和404.html文件来提供自己的 403 和 404 错误页面. 通常，这是项目的根目录，但是根据您的静态生成器配置，它可能有所不同.

如果是404.html ，则有不同的方案. 例如：

• 如果您使用项目 Pages（在/projectname/ ）并尝试访问/projectname/non/existing_file ，则 GitLab Pages 将尝试首先提供/projectname/404.html ，然后提供/404.html .
• 如果您使用用户/组页面（在/下提供）并尝试访问/non/existing_file GitLab Pages 将尝试提供/404.html .
• 如果您使用自定义域并尝试访问/non/existing_file ，则 GitLab Pages 将尝试仅提供/404.html .

Redirects in GitLab Pages

由于您不能使用任何自定义服务器配置文件（例如.htaccess或任何.conf文件），因此，如果要将页面重定向到其他位置，可以使用HTTP meta refresh 标签 .

一些静态网站生成器提供了该功能的插件，因此您不必手动创建和编辑 HTML 文件. 例如，Jekyll 具有redirect-from 插件 .

GitLab Pages Access Control

要限制对您网站的访问，请启用GitLab 页面访问控制 .

Unpublishing your Pages

如果您需要清除 Pages 内容，可以通过右上角的齿轮图标进入项目设置，然后导航至Pages . 点击删除页面按钮，您的页面网站将被删除.

Limitations

在 GitLab 实例的常规域（ *.example.io ）下使用 Pages 时， 不能将 HTTPS 与子子域一起使用. 这意味着，如果你的用户名或组名称中包含一个圆点，例如foo.bar ，域https://foo.bar.example.io将无法正常工作. 这是HTTP Over TLS 协议的限制. 如果您不将 HTTP 重定向到 HTTPS，HTTP 页面将继续工作.

GitLab 网页不支持组为网站分组 . 您只能创建最高级别的群组网站.

Specific configuration options for Pages

了解如何针对特定用例设置 GitLab CI / CD.

.gitlab-ci.yml for plain HTML websites

假设您的存储库包含以下文件：

├── index.html
├── css
│   └── main.css
└── js
    └── main.js 

然后，下面的.gitlab-ci.yml示例仅将所有文件从项目的根目录移至public/目录. .public解决方法是， cp不会在无限循环中将public/复制到自身：

pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master 

.gitlab-ci.yml for a static site generator

请参阅本文档，以获取分步指南 .

.gitlab-ci.yml for a repository where there’s also actual code

请记住，默认情况下，GitLab 页面是分支/标签不可知的，它们的部署仅取决于您在.gitlab-ci.yml指定.gitlab-ci.yml . 每当将新的提交推送到专门用于页面的分支时，就可以使用only参数限制pages作业.

这样，您可以将项目的代码保存在master分支中，并使用一个孤儿分支（将其命名为pages ）来托管您的静态生成器站点.

您可以这样创建一个新的空分支：

git checkout --orphan pages 

在这个新分支上进行的第一次提交将没有父母，这将是与所有其他分支和提交完全脱节的新历史的根源. 在pages分支中推送静态生成器的源文件.

以下是.gitlab-ci.yml的副本，其中最重要的一行是最后一行，指定要执行pages分支中的所有pages ：

image: ruby:2.6

pages:
  script:
    - gem install jekyll
    - jekyll build -d public/
  artifacts:
    paths:
      - public
  only:
    - pages 

请参见一个示例，该示例在master分支中具有不同的文件，而 Jekyll 的源文件在pages分支中 ，该分支还包含.gitlab-ci.yml .

Serving compressed assets

大多数现代的浏览器都支持下载压缩格式的文件. 通过减小文件大小，可以加快下载速度.

Pages 将提供未压缩的文件之前，将检查是否存在扩展名为.gz的相同文件. 如果支持，并且浏览器支持接收压缩文件，它将使用该版本而不是未压缩版本.

要利用此功能，您上传到页面的工件应具有以下结构：

public/
├─┬ index.html
│ └ index.html.gz
│
├── css/
│   └─┬ main.css
│     └ main.css.gz
│
└── js/
    └─┬ main.js
      └ main.js.gz 

这可以通过在.gitlab-ci.yml页面作业中包含以下script:来实现：

pages:
  # Other directives
  script:
    # Build the public/ directory first
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \; 

通过预压缩文件并在工件中包括两个版本，Pages 可以处理对压缩和未压缩内容的请求，而无需按需压缩文件.

Resolving ambiguous URLs

在 GitLab 11.8 中引入

当接收到不包含扩展名的 URL 的请求时，GitLab Pages 会假设要提供哪些文件.

考虑使用以下文件部署的 Pages 站点：

public/
├─┬ index.html
│ ├ data.html
│ └ info.html
│
├── data/
│   └── index.html
├── info/
│   └── details.html
└── other/
    └── index.html 

页面支持通过几个不同的 URL 来访问每个文件. 特别是，如果 URL 仅指定目录，它将始终寻找index.html文件. 如果该 URL 引用了一个不存在的文件，但是将.html添加到该 URL 中会导致该文件确实存在，将改为提供该文件. 以下是在上述 Pages 网站上发生的情况的一些示例：

注意：当存在public/data/index.html时，对于/data和/data/ URL 路径，其优先于public/data.html文件.

Frequently Asked Questions

Can I download my generated pages?

当然. 您需要做的就是从作业页面下载工件存档.

Can I use GitLab Pages if my project is private?

是. GitLab Pages 不在乎将项目的可见性级别设置为私有，内部还是公共.

Do I need to create a user/group website before creating a project website?

不，你没有. 您可以先创建您的项目，然后将在http(s)://namespace.example.io/projectname下对其进行访问.

Known issues

有关已知问题的列表，请访问 GitLab 的公共问题跟踪器 .