GitLab Pages

GitLab Pages 直接从 GitLab 仓库发布静态网站。

这些网站：

• 通过 GitLab CI/CD 管道自动部署。
• 支持任何静态网站生成器（如 Hugo、Jekyll 或 Gatsby）或纯 HTML、CSS 和 JavaScript。
• 在 GitLab 提供的基础设施上运行，无需额外费用。
• 可连接自定义域名和 SSL/TLS 证书。
• 通过内置的身份验证控制访问权限。
• 可靠地扩展个人、业务或项目文档网站。

要使用 Pages 发布网站，可以使用任何静态网站生成器，如 Gatsby、Jekyll、Hugo、Middleman、Harp、Hexo 或 Brunch。 Pages 也支持直接用纯 HTML、CSS 和 JavaScript 编写的网站。 不支持动态服务器端处理（如 .php 和 .asp）。 有关更多信息，请参阅 静态网站与动态网站。

入门指南

要创建 GitLab Pages 网站：

要更新 GitLab Pages 网站：

有关更多信息，请参阅：

使用 GitLab Pages

要使用 GitLab Pages，您必须在 GitLab 中创建一个项目来上传您的网站文件。 这些项目可以是公开的、内部的或私有的。

默认情况下，GitLab 从您仓库中名为 public 的特定文件夹部署您的网站。 您也可以 设置要随 Pages 部署的自定义文件夹。 当您在 GitLab 中创建新项目时，会自动提供一个 仓库。

要部署您的网站，GitLab 使用其内置的 GitLab CI/CD 工具来构建您的网站并将其发布到 GitLab Pages 服务器。 GitLab CI/CD 运行以完成此任务的脚本序列来自一个名为 .gitlab-ci.yml 的文件，您可以 创建和修改 该文件。 配置文件中带有 pages: true 属性的用户定义 job 会让 GitLab 知道您正在部署 GitLab Pages 网站。

您可以使用 GitLab GitLab Pages 网站的默认域名， *.gitlab.io，或者您自己的域名（example.com）。在这种情况下， 您必须是您域名注册商（或控制面板）的管理员才能将其设置为 Pages。

访问您的 Pages 网站

如果您使用 GitLab Pages 默认域名（.gitlab.io），您的网站会自动通过 HTTPS 安全可用。 如果您使用自己的自定义域名，可以选择使用 SSL/TLS 证书来保护它。

如果您使用 GitLab.com，您的网站对互联网公开可用。 要限制对您网站的访问，请启用 GitLab Pages 访问控制。

如果您使用 GitLab Self-Managed 实例，您的网站会根据系统管理员选择的 Pages 设置 发布在您自己的服务器上，他们可以将网站设为公开或内部。

Pages 示例

这些 GitLab Pages 网站示例可以教您高级技术，以便根据您的需求使用和调整：

• 从 iOS 发布到您的 GitLab Pages 博客。
• GitLab CI：按顺序、并行运行作业或构建自定义管道。
• GitLab CI：部署与环境。
• 使用 Nanoc、GitLab CI 和 GitLab Pages 构建新的 GitLab 文档网站。
• 使用 GitLab Pages 发布代码覆盖率报告。

管理 GitLab Self-Managed 实例的 GitLab Pages

如果您正在运行 GitLab Self-Managed 实例， 请遵循管理步骤 来配置 Pages。

观看关于如何开始 GitLab Pages 管理的 视频教程。

在 Helm Chart (Kubernetes) 实例中配置 GitLab Pages

要在使用 Helm chart (Kubernetes) 部署的实例上配置 GitLab Pages，请使用以下任一方法：

• 使用 gitlab-pages 子图表。
• 使用外部 GitLab Pages 实例。

GitLab Pages 的安全性

包含 . 的命名空间

如果您的用户名是 example，您的 GitLab Pages 网站位于 example.gitlab.io。 GitLab 允许用户名包含 .，因此名为 bar.example 的用户可以创建一个 GitLab Pages 网站 bar.example.gitlab.io， 这实际上是您 example.gitlab.io 网站的子域名。如果您使用 JavaScript 为您的网站设置 cookie，请小心。 手动设置 cookie 的安全方法是根本不指定 domain：

// 安全：此 cookie 仅对 example.gitlab.io 可见
document.cookie = "key=value";

// 不安全：此 cookie 对 example.gitlab.io 及其子域都可见，
// 无论是否存在前导点。
document.cookie = "key=value;domain=.example.gitlab.io";
document.cookie = "key=value;domain=example.gitlab.io";

此问题不影响使用自定义域名的用户，或者不使用 JavaScript 手动设置任何 cookie 的用户。

共享 cookie

默认情况下，组中的每个项目都共享同一个域，例如 group.gitlab.io。这意味着组中所有项目的 cookie 也是共享的。

为确保每个项目使用不同的 cookie，请为您的项目启用 Pages 唯一域名 功能。

唯一域名

默认情况下，每个新项目都使用唯一的页面域名。这是为了避免同一组中的项目共享 cookie。

项目维护者可以在以下位置禁用此功能：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > Pages。
3. 清除 使用唯一域名 复选框。
4. 选择 保存更改。

有关示例 URL，请参阅 GitLab Pages 默认域名。

主域名

当您将 GitLab Pages 与自定义域名一起使用时，您可以将所有对 GitLab Pages 的请求重定向到主域名。 选择主域名后，用户会收到 308 永久重定向 状态，该状态会将浏览器重定向到 所选的主域名。浏览器可能会缓存此重定向。

先决条件：

• 您必须至少拥有项目的维护者角色。
• 必须设置 自定义域名。

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > Pages。
3. 从 主域名 下拉列表中，选择要重定向到的域名。
4. 选择 保存更改。

过期部署

您可以通过在 pages.expire_in 中指定持续时间， 来配置您的 Pages 部署在经过一段时间后自动删除：

create-pages:
  stage: deploy
  script:
    - ...
  pages:  # 指定这是一个 Pages 作业并发布默认的 public 目录
    expire_in: 1 week

过期的部署会被一个每 10 分钟运行一次的 cron 作业停止。 停止的部署随后会被另一个每 10 分钟运行一次的 cron 作业删除。 要恢复它，请按照 恢复已停止的部署 中描述的步骤操作。

已停止或已删除的部署在网络上不再可用。您 会在其 URL 上看到 404 未找到错误页面，直到创建另一个具有相同 URL 配置的部署。

上面的 YAML 示例使用了 用户定义的作业名称。

恢复已停止的部署

先决条件：

• 您必须至少拥有项目的维护者角色。

要恢复尚未删除的已停止部署：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > Pages。
3. 在 部署 附近，打开 包含已停止的部署 开关。 如果您的部署尚未被删除，它应该包含在 列表中。
4. 展开您要恢复的部署并选择 恢复。

删除部署

要删除部署：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > Pages。
3. 在 部署 下，选择您要删除的部署上的任何区域。 部署详细信息会展开。
4. 选择 删除。

当您选择 删除 时，您的部署会立即停止。 停止的部署会被每 10 分钟运行一次的 cron 作业删除。

要恢复尚未删除的已停止部署，请参阅 恢复已停止的部署。

用户定义的作业名称

要从任何作业触发 Pages 部署，请在作业定义中包含 pages 属性。 它可以是设置为 true 的布尔值，也可以是一个哈希值。

例如，使用 true：

deploy-my-pages-site:
  stage: deploy
  script:
    - npm run build
  pages: true  # 指定这是一个 Pages 作业并发布默认的 public 目录

例如，使用哈希值：

deploy-pages-review-app:
  stage: deploy
  script:
    - npm run build
  pages:  # 指定这是一个 Pages 作业并发布默认的 public 目录
    path_prefix: '_staging'

如果名为 pages 的作业的 pages 属性设置为 false，则不会 触发任何部署：

pages:
  pages: false

并行部署

要同时为您的项目创建多个部署，例如创建审查应用，请参阅 并行部署 的文档。