入门
工作原理
访问您的 Pages 网站
为私有化部署实例管理极狐GitLab Pages
极狐GItLab Pages 安全
- 命名空间包含 .
- 共享 cookies
唯一域名
过期部署
- 恢复一个停止的部署
并行部署
用户自定义的作业名称

极狐GitLab Pages

使用极狐GitLab Pages，您可以直接从极狐GitLab 的仓库中发布静态网站。

用于任何个人或商业网站。
使用任何静态站点生成器 (SSG) 或纯 HTML。
为您的项目、群组或用户账户创建网站。
在您自己的极狐GitLab 私有化部署实例上免费托管您的网站。
连接您的自定义域名和 TLS 证书。
将任何许可证归于您的内容。

要使用 Pages 发布网站，您可以使用任何静态网站生成器，例如 Gatsby、Jekyll、Hugo、Middleman、Harp、Hexo 或 Brunch。您还可以发布任何直接用纯 HTML、CSS 和 JavaScript 编写的网站。

Pages 不支持动态服务器端处理，例如，.php 和 .asp 需要。

入门

要创建一个 Pages 网站：

文档	描述
使用极狐GitLab UI 创建一个简单的 `.gitlab-ci.yml`	添加一个 Pages 站点到现有项目，使用 UI 设置一个简单的 `.gitlab-ci.yml`
从头开始创建一个 `.gitlab-ci.yml` 文件	将 Pages 网站添加到现有项目。如何创建和配置您自己的 CI 文件。
使用 `.gitlab-ci.yml` 模板	将 Pages 网站添加到现有项目。使用预填充的 CI 模板文件。
派生示例项目	通过派生一个示例项目，使用已经配置的 Pages 创建一个新项目。
使用项目模板	通过已使用模板配置的 Pages 创建一个新项目。

要更新 Pages 网站：

文档	描述
极狐GitLab Pages 域名, URLs, 和基础 URLs	学习极狐GitLab Pages 默认域名
探索极狐GitLab Pages	要求、技术理念、特定的极狐GitLab CI/CD 配置项、访问控制、自定义404页面, 限制和FAQ。
自定义域名和 SSL/TLS 证书	自定义域名和子域名、DNS 记录和 SSL/TLS 证书
Let’s Encrypt 集成	使用 Let’s Encrypt 证书保护您的 Pages 站点，极狐GitLab 能能自动和更新证书
重定向	配置 HTTP 重定向把一个页面转到另外一个

学习和查看更多示例:

文档	描述
静态 vs 动态站点	Static versus dynamic site overview.
现代静态站点生成器	SSG 概览
使用极狐GitLab Pages 构建任意 SSG 站点	Use SSGs for GitLab Pages.

工作原理

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

极狐GitLab 始终从仓库中名为 public 的特定文件夹部署您的网站。当您在极狐GitLab 中创建新项目时，仓库会自动变为可用。

为了部署您的站点，极狐GitLab 使用内置工作极狐GitLab CI/CD 来构建您的站点，并将其发布到 Pages 服务器。极狐GitLab CI/CD 为完成此任务而运行的脚本序列是从 .gitlab-ci.yml 文件中创建的，您可以创建和修改。配置文件中里用户定义的带有 pages: true 属性的特定 job 让极狐GitLab 知晓您正在部署 Pages 网站。

您可以使用 Pages 网站的默认域名或您自己的域名 (example.com)。在这种情况下，您必须是域名注册商（或控制面板）的管理员才能使用 Pages 进行设置。

下图显示了您在开始使用 Pages 时可能遵循的工作流程。

New projects for GitLab Pages

访问您的 Pages 网站

您使用的是私有化部署版实例，您的网站将根据您的系统管理员选择的 Pages 设置，在您自己的服务器上发布，管理员可以将它们设置为公开或内部。

为私有化部署实例管理极狐GitLab Pages

如果您正在运行极狐GitLab 的私有化部署实例，请按照管理步骤配置 Pages。

极狐GItLab Pages 安全

命名空间包含 `.`

如果您的用户名是 example，那么您的 GitLab Pages 网站位于 example.gitlab.io。极狐GitLab 允许用户名包含 .，因此名为 bar.example 的用户可以创建一个 Pages 网站 bar.example.gitlab.io，它实际上是您的 example.gitlab.io 网站的子域名。如果您使用 JavaScript 为您的网站设置 cookie，请务必小心。使用 JavaScript 手动设置 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";

这个问题不影响使用自定义域名或者不使用 JavaScripts 手动设置任意cookie 的用户。

共享 cookies

默认情况下，同一个群组里的每个项目共享相同的域名，例如 group.gitlab.io，这意味着同一个群组里的每个项目也共享 cookies。

要保证每个项目使用不同的 cookies，为你的项目启用 Pages 唯一域名

唯一域名

在极狐GitLab 15.9 版本通过标志 pages_unique_domain 引入，默认禁用。

在极狐GitLab 15.11 版本默认启用。

在极狐GitLab 16.3 版本移除功能标志。

在极狐GitLab 17.4 版本修改唯一域名为简短域名。

默认情况下，每个新项目使用 pages 唯一域名。这是为了避免相同群组里的项目共享 cookies。

项目维护者可以禁用这个功能：

在左侧栏，点击 搜索或转到 并找到您的项目。
点击 **部署 > Pages **。
清除 使用唯一域名 选择框。
点击 保存更改

实例URL，查看极狐GitLab Pages 默认域名

过期部署

在极狐GitLab 17.4 版本引入。

你可以在配置 pages.expire_in 指定一个周期，让您的Pages 部署在经过一段时间后自动删除。

deploy-pages:
  stage: deploy
  script:
    - ...
  pages:  # specifies that this is a Pages job
    expire_in: 1 week
  artifacts:
    paths:
      - public

默认情况下，并行部署在24小时后自动过期。要禁用这个特性，设置pages.expire_in 为 never。

过期的部署会被一个每10分钟运行一次的定时作业停止。停止的部署会被之后另一个每10分钟运行一次的定时作业给删除。要恢复它，根据恢复一个停止的部署中的步骤操作。

一个停止的或者删除的部署在网页上不可用，用户会在它的 URL 上看到一个 404 Not Found 错误。直到同一个 URL 配置上创建了另一个部署为止。

前面的 YAML 示例使用用户自定义的作业名称

恢复一个停止的部署

先决条件：

你必须至少是项目的维护者角色

要恢复一个还没有删除的已停止部署：

在左侧栏，点击 搜索或转到 并找到您的项目。
点击 部署 > Pages。
在部署旁边打开 包含已停止的部署 切换按钮。如果您的部署还没有被删除，它会包含在这个列表里。
展开你希望恢复的部署并点击恢复。

并行部署

在极狐GitLab 16.7版本里以实验标志 pages_multiple_versions_setting 引入，默认禁用。

在极狐GitLab 17.4版本里把 “多部署” 重命名为 “并行部署”.

在极狐GitLab 17.4版本里在私有化部署中启用。

这个功能的可用性是通过一个功能标志控制的，更多信息请查看历史记录。这个功能是测试可用，还没有在生产环境就绪。

使用 pages.path_prefix CI/CD 选项为极狐GitLab Pages URL配置一个前缀。前缀让你可以在多个GitLab Pages部署之间进行区分：

主部署，使用空白 path_prefix 创建的 Pages 部署
并行部署，使用非空白 path_prefix 创建的 Pages 部署

pages.path_prefix 的值是：

转换为小写
缩短到 63 字节
数字（0-9）和字母（a-z）以外的字符都会被替换为中划线（-）。
头部和尾部的中划线（-）会被移除。

示例配置

考虑类似 https://gitlab.example.com/namespace/project 这样的一个项目。默认情况下，主Pages 部署可以通过下面的方式访问：

使用唯一域名：https://project-namespace-123456.gitlab.io。
没有使用唯一域名：https://namespace.gitlab.io/project。

启用并行部署

要启用并行极狐GitLab Pages 部署：

在左侧栏，点击 搜索或转到并找到您的项目。
点击 部署 > Pages。
点击 启用并行部署。

限制

并行部署的数量是被根级别命名空间限制的，对于特定的限制： - 私有化部署实例。查看并行部署的数量

要立即减少您命名空间里活跃的部署数量，删除一些部署，更多信息请查看删除一个部署

要配置一个过期时间来自动删除过时的部署，请查看过期部署

过期

默认情况下并行部署是在他们被删除24小时后过期，如果你使用的是私有化部署的实例，您的实例管理员可以配置一个不同的默认周期

要自定义过期时间，配置 pages.expire_in。

路径冲突

pages.path_prefix 可以从 CI/CD 变量中获取动态的值，可以用来创建 pages 部署。但是可能会和您的站点已有的路径冲突。例如给已有的极狐GitLab Pages站点下面的路径：

/index.html
/documents/index.html

如果 pages.path_prefix 是 documents，这个版本会覆盖已有的路径。换句话说，https://namespace.gitlab.io/project/documents/index.html 会指向这个站点的 deployment 部署的 /index.html。代替了站点 main 部署的 documents/index.html 部署。

把其他字符串和 CI/CD 变量混用可以减少路径冲突的可能性，例如：

deploy-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}"
  variables:
    PAGES_PREFIX: "" # 默认情况没有前缀 (master)
  pages:  # 指定这是一个 Pages 作业
    path_prefix: "$PAGES_PREFIX"
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 在默认分支上云霄 (使用默认的 PAGES_PREFIX)
    - if: $CI_COMMIT_BRANCH == "staging" # Run on master ( 使用默认的PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # _stg 前缀用于 staging 分支
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # 有条件地为合并请求变更前缀
      when: manual # 在合并请求上手动运行 Pages
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' #  mr-<iid> 前缀, 像 `mr-123`

其他一些字符串和变量混用的动态前缀示例：

pages.path_prefix: 'mr-$CI_COMMIT_REF_SLUG'：分支或者标签名使用mr-前缀，例如mr-branch-name。
pages.path_prefix: '_${CI_MERGE_REQUEST_IID}_'：合并请求编号前后加上 _，例如 _123_

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

使用并行部署来创建 Pages 环境

你可以使用并行极狐GitLab Pages 部署来创建一个新的环境，例如：

deploy-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}"
  variables:
    PAGES_PREFIX: "" # 默认没有前缀 (master)
  pages:  # 指定这是一个 Pages 作业
    path_prefix: "$PAGES_PREFIX"
  environment:
    name: "Pages ${PAGES_PREFIX}"
    url: "${CI_PAGES_URL}/${PAGES_PREFIX}"
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_BRANCH == "staging" # 保证运行在 master (使用默认的 PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # _stg 前缀用于 staging 分支
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # 在合并请求上有条件地变更前缀
      when: manual # 在合并请求上手动运行 pages
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # 使用 mr-<iid> 前缀, 像 `mr-123`

使用这个配置，用户可以通过UI 访问每个极狐GitLab Pages 部署。当使用 Pages 的环境，所有pages 环境都会在项目环境列表里列出。

你也可以把类似的环境组织到一起。

上面的 YAML 示例使用的是用户自定义的作业名称

删除一个部署

要删除一个部署：

在左侧栏，点击 搜索或转到并找到您的项目。
点击 部署 > Pages。
在部署下面，点击你要删除的部署任意区域，会展开部署详情。
点击删除。

当你点击删除，你的部署会立即停止。已停止的部署会被一个每10分钟运行一次的定时作业删除。

要恢复一个还没有被删除的已停止部署，请查看恢复一个已停止的部署

自动清理

合并请求使用 path_refix 前缀创建的并行 Pages 部署，在合并请求关闭或者合并的时候自动删除。

用户自定义的作业名称

在极狐GitLab 17.5版本里使用标志 customizable_pages_job_name 引入，默认禁用。

在极狐GitLab 17.6版本里正式发布，标志 customizable_pages_job_name移除。

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

例如使用 true：

deploy-my-pages-site:
  stage: deploy
  script:
    - npm run build
  pages: true  # 指定这是一个 Pages 作业
  artifacts:
    paths:
      - public

例如，使用一个哈希

deploy-pages-review-app:
  stage: deploy
  script:
    - npm run build
  pages:  # 指定这是一个 Pages 作业
    path_prefix: '/_staging'
  artifacts:
    paths:
    - public

如果一个叫做 pages 的作业的 pages 属性设置为 false，不会触发任何部署：

pages:
  pages: false

极狐GitLab Pages

入门

工作原理

访问您的 Pages 网站

为私有化部署实例管理极狐GitLab Pages

极狐GItLab Pages 安全

命名空间包含 .

共享 cookies

唯一域名

过期部署

恢复一个停止的部署

并行部署

示例配置

启用并行部署

限制

过期

路径冲突

使用并行部署来创建 Pages 环境

删除一个部署

自动清理

用户自定义的作业名称

命名空间包含 `.`