GitLab页面

注:

这个特性是介绍了在GitLab EE 8.3中。

支持TLS的自定义cname介绍了在GitLab EE 8.5中。

GitLab页面是移植到GitLab 8.17中的社区版。

本文档主要介绍用户指南。要了解如何在GitLab实例中启用GitLab Pages，请访问管理员文档．

使用GitLab Pages，你可以免费在GitLab上托管静态网站。结合的力量GitLab CI和帮助GitLab跑步您可以为您的单个项目、用户或组部署静态页面。

读在GitLab.com上的GitLab页面如果你正在使用GitLab.com来托管你的网站，你可以获得具体的信息。

阅读关于GitLab Pages你需要知道的一切查看我们为GitLab Pages(网页、文章、指南、博客文章、视频教程)准备的所有学习材料的列表。

开始使用GitLab Pages

注意:在本文档的其余部分中，我们将假设用于GitLab页面的通用域名为example.io．

通常有两种类型的页面可以创建:

每用户页数(username.example.io)或每组(groupname.example.io）
每个项目的页数(username.example.io / projectname或groupname.example.io / projectname）

在GitLab中，用户名和组名是唯一的，我们通常将它们称为名称空间．在一个GitLab实例中只能有一个名称空间。下面你可以看到GitLab页面类型之间的联系，在GitLab上创建的项目名称是什么样子的，最终将在网站URL上提供服务。

GitLab页面的类型	在GitLab中创建的项目的名称	网站网址
用户页面	`username.example.io`	`http (s): / / username.example.io`
组页	`groupname.example.io`	`http (s): / / groupname.example.io`
用户拥有的项目页	`projectname`	`http (s): / / username.example.io / projectname`
由组拥有的项目页	`projectname`	`http (s): / / groupname.example.io / projectname`

警告:有一些已知的限制关于在通用域名和HTTPS下服务的名称空间。一定要阅读这部分内容。

GitLab Pages需求

简单地说，这就是你在GitLab Pages中上传你的网站所需要的:

找出用于GitLab页面的通用域名(询问您的管理员)。这是非常重要的，所以你应该首先确保你做对了。
创建一个项目
按一个.gitlab-ci.yml文件在存储库的根目录中，并指定一个名为页面
建立一个GitLab Runner来建立你的网站

注意:如果共享的跑步者是由您的GitLab管理员启用的，您应该能够使用它们，而不是自己带来。

用户或组

对于用户和组页面，项目的名称应该特定于用户名或组名以及用于GitLab页面的通用域名。浏览支持GitLab Pages的GitLab实例，并创建一个名为username.example.io,在那里用户名是你在GitLab上的用户名。如果项目名称的第一部分与您的用户名不完全匹配，那么它将不起作用，因此请确保它正确。

创建群组页面的步骤与为用户创建网站的步骤相同。只需确保您是在组的名称空间内创建项目。

在您将一些静态内容推送到存储库，GitLab Runner将工件上传到GitLab CI后，您将能够在下面访问您的网站http (s): / / username.example.io．请继续阅读，找出答案。

注意:例如，如果您的用户名/组名包含一个点foo.bar，您将无法使用通配符域HTTPS，阅读更多在限制．

项目页面

项目的GitLab页面可以由用户和组帐户创建。为用户或组创建项目页面的步骤是相同的:

创建一个新项目
按一个.gitlab-ci.yml文件在存储库的根目录中，并指定一个名为页面．
建立一个GitLab Runner来建立你的网站

用户的项目将在http (s): / / username.example.io / projectname而一个小组的项目http (s): / / groupname.example.io / projectname．

有关组页和项目页的实际示例，请通读指南GitLab页面从A到Z:第1部分-静态站点和GitLab页面域．

快速启动

阅读GitLab Pages快速入门指南或者观看视频教程如何从一个分叉的项目发布一个网站与GitLab网页在GitLab.com．

另请参阅关于GitLab Pages你需要知道的一切查看我们为GitLab Pages提供的所有资源的列表。

探索`.gitlab-ci.yml`

关于GitLab Pages的关键是.gitlab-ci.yml文件，它可以让你完全控制构建过程。通过跟踪CI工作轨迹，您实际上可以实时观看您的网站是如何构建的。

有关为Pages设置GitLab CI/CD的简化用户指南，请通读本文GitLab页面从A到Z:第4部分-创建和调整.gitlab-ci.yml用于GitLab Pages

注意:在阅读本节之前，请确保您熟悉GitLab CI和特定的语法.gitlab-ci.yml请按我们的快速入门指南．

的内容才能使用GitLab Pages.gitlab-ci.yml必须遵守以下规则:

一个特殊的工作页面必须定义
任何将由GitLab Pages提供的静态内容必须放在公共/目录
工件的路径公共/必须定义目录

最简单的形式是，.gitlab-ci.yml看起来像:

页面：脚本：-my_commands工件：路径：-公共

当奔跑者到达建造页面方法中定义的任何内容脚本参数，如果作业以非零退出状态完成，则它将上传公共/目录到GitLab Pages。

的公共/目录应该包含你网站的所有静态内容。方法中定义的步骤，取决于您计划如何发布网站脚本参数可能有所不同。

注意page默认情况下是分支/标记不可知的，它们的部署完全依赖于您在.gitlab-ci.yml．如果你不限制页面工作与只有参数当一个新的提交被推送到任何分支或标记时，Pages将被覆盖。在下面的示例中，我们限制在仅在上推送提交时部署Pages主分支机构:

页面：脚本：-my_commands工件：路径：-公共只有：-主

然后我们告诉奔跑者去治疗公共/目录工件并上传到GitLab。因为所有这些参数都在a下页面作业的内容公共目录将由GitLab Pages提供。

如何`.gitlab-ci.yml`看起来就像存储库中的静态内容一样

假设你的存储库包含以下文件:

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

然后.gitlab-ci.yml下面的示例简单地将所有文件从项目的根目录移动到公共/目录中。的学派变通办法是这样的cp也不会复制公共/对自身进行无限循环:

页面：脚本：-mkdir学派-Cp -r * .public-公共的工件：路径：-公共只有：-主

如何`.gitlab-ci.yml`看起来就像用了静电发生器

一般来说，GitLab Pages支持任何类型的静态站点生成器,因为.gitlab-ci.yml可以配置为运行任何可能的命令。

在Git存储库的根目录中，放置您喜欢的静态生成器的源文件。然后提供一个.gitlab-ci.yml特定于静态生成器的文件。

下面的例子使用变身怪医要构建静态站点:

图像：ruby: 2.1#脚本将在Ruby 2.1中运行，使用Docker镜像Ruby:2.1页面：#构建作业必须命名为页面脚本：-Gem安装jekyll#我们安装jekyll-Jekyll build -d public/#我们告诉jekyll为我们建立网站工件：路径：-公共#这是站点将存在的位置，Runner将它上传到GitLab中只有：-主#此脚本只影响主分支

在这里，我们使用Docker执行器，并在第一行中指定了作业将运行的基本映像。

您必须确保生成的静态文件最终放置在公共目录，这就是为什么脚本部分，我们运行变身怪医命令执行该网站，并将所有内容放在公共/目录中。根据您所选择的静态生成器的不同，此命令将有所不同。如果有显式设置输出目录的选项，请在将要使用的静态生成器的文档中搜索。如果没有这样的选项，您总是可以在下面再添加一行脚本中的结果目录重命名公共/．

然后我们告诉奔跑者去治疗公共/目录工件并上传到GitLab。

看到Jekyll示例项目为了更好地理解这是如何工作的。

有关Pages项目的列表，请参见示例项目开始吧。

如何在有实际代码的存储库中设置GitLab页面

记住，GitLab页面默认是分支/标签不可知的，它们的部署完全依赖于您在中指定的内容.gitlab-ci.yml．你可以限制页面工作与只有参数，每当一个新的提交被推到一个将专门用于您的页面的分支。

这样，您就可以将项目代码保存在主分支，并使用一个孤儿分支(让我们命名它页面)，它将托管您的静态生成器站点。

你可以像这样创建一个新的空分支:

git checkout——孤儿页面

在这个新分支上进行的第一次提交将没有父节点，它将是一个与所有其他分支和提交完全断开的新历史的根节点。中的静态生成器的源文件页面分支。

下面是一份.gitlab-ci.yml最重要的行是最后一行，指定执行页面分支机构:

图片:ruby: 2.1页:脚本:-安装jekyll- jekyll build -d public/构件:道路:——公共只有:——页面

中具有不同文件的示例主分支杰基尔的源文件在页面分支它还包括.gitlab-ci.yml．

下一个步骤

你已经成功部署了你的网站，恭喜你!让我们来看看用GitLab Pages还能做些什么。

示例项目

下面是一个带有普通HTML网站或各种静态网站生成器的GitLab Pages示例项目列表。欢迎投稿。

访问GitLab Pages组以获得完整的示例项目列表:https://gitlab.com/groups/pages．

服务压缩资产

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

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

为了利用这个特性，你上传到Pages的工件应该有这样的结构:

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

这可以通过包含一个脚本:在你的.gitlab-ci.yml页面工作:

页面：#其他指令脚本：-#首先构建public/目录-找到公共类型f -iregex”。* \。\ (htm \ \ | txt \ | | html文本\ | js \ | css \)美元的-execdir gzip - f——保持{}\;

通过预压缩文件并在工件中包含两个版本，Pages可以同时为压缩和未压缩的内容提供请求，而不需要按需压缩文件。

为你的Pages网站添加一个自定义域名

有关Pages域的完整指南，请通读本文GitLab page from A to Z: Part 3 -设置自定义域- DNS记录和SSL/TLS证书

如果您的GitLab管理员启用了此设置，则应该能够看到新域按钮时，通过右上方的齿轮图标访问项目的设置，然后导航到页面．

你可以添加多个域名指向你在GitLab下托管的网站。添加域之后，您可以看到它列在域部分。

作为最后一步，您需要配置DNS并添加指向用户/组页面的CNAME。点击细节用于进一步说明的域按钮。

注意:目前，每个项目只支持自定义域。这意味着如果您添加一个自定义域(example.com)下载至你的用户网站(username.example.io)，该项目是在username.example.io / foo，将无法访问下example.com/foo．

使用TLS保护您的自定义域名网站

当您添加新的自定义域时，您也有机会添加TLS证书。如果您的GitLab管理员启用了此设置，那么在添加新域时，您应该能够看到上传公共证书和私钥的选项。

有关Pages域的完整指南，请通读本文GitLab page from A to Z: Part 3 -设置自定义域- DNS记录和SSL/TLS证书

自定义错误代码页面

控件可以提供自己的403和404错误页面html 403.而且html 404.文件的根目录下公共/将包含在工件中的目录。通常这是项目的根目录，但根据静态生成器配置的不同，这可能会有所不同。

如果html 404.在美国，有不同的情况。例如:

如果您使用项目页面(在/ projectname /)，并尝试存取/ projectname /无/ existing_file， GitLab Pages将首先尝试提供服务404. / projectname / html，然后html / 404.．
如果您使用用户/组页面(在/)，并尝试存取/不/ existing_fileGitLab Pages将尝试提供服务html / 404.．
如果您使用自定义域并尝试访问/不/ existing_file， GitLab Pages将尝试只提供服务html / 404.．

删除页面内容

如果你觉得有必要清理Pages内容，你可以通过右上角的齿轮图标进入项目设置，然后导航到页面．撞到删除页面按钮和您的页面网站将被删除。就这么简单。

在GitLab.com上的GitLab页面

如果你使用GitLab.com来托管你的网站，那么:

GitLab.com上的GitLab页面的通用域名是gitlab.io．
启用自定义域和TLS支持。
共享运行器是默认启用的，免费提供，可用于构建您的网站。如果你愿意，你还可以带上你自己的跑步者。

指南的其余部分仍然适用。

参见:GitLab页面从A到Z:第1部分-静态站点和GitLab页面域．

限制

当在GitLab实例的通用域下使用Pages时(* .example.io),你不能使用HTTPS与子子域。例如，如果您的用户名/组名包含一个点foo.bar，定义域https://foo.bar.example.io将不工作。这是一个局限HTTP Over TLS协议．如果不将HTTP重定向到HTTPS, HTTP页面将继续工作。

GitLab页面做不支持子组．只能创建最高级别的群组网站。

在GitLab页面中重定向

因为您不能使用任何自定义服务器配置文件，比如. htaccess或任何. conf文件，如果要将页面重定向到另一个位置，可以使用HTTP元刷新标记．

一些静态网站生成器为该功能提供了插件，因此您不必手动创建和编辑HTML文件。例如，杰基尔有从插件．

常见问题

我可以下载生成的页面吗?

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

如果我的项目是私有的，我可以使用GitLab Pages吗?

是的。GitLab Pages并不关心您将项目的可见性级别设置为私有、内部还是公共。

在创建项目网站之前，我需要创建一个用户/组网站吗?

不，你不需要。您可以先创建您的项目，它将在下面访问http (s): / / namespace.example.io / projectname．

已知的问题

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