极狐GitLab Pages

所有级别

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

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

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

入门#

要创建一个 Pages 网站：

要更新 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 时可能遵循的工作流程。

访问您的 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：

javascript
1// 安全方式: 这个cookie 仅对 example.gitlab.io 可见
2document.cookie = "key=value";
3
4// 不安全方式: 这个cookie 对 example.gitlab.io 和它的子域名可见
5// 不考虑前面出现的 . 号.
6document.cookie = "key=value;domain=.example.gitlab.io";
7document.cookie = "key=value;domain=example.gitlab.io";

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

共享 cookies#

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

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

唯一域名#

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

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

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

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

过期部署**(PREMIUM SELF)**#

你可以在配置 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 示例使用 用户自定义的作业名称

恢复一个停止的部署#

先决条件：

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

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

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

并行部署 (PREMIUM SELF)#

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

使用 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 部署：

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

限制#

并行部署的数量是被根级别命名空间限制的，对于特定的限制：

• 私有化部署实例。 查看 并行部署的数量

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

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

过期#

默认情况下并行部署是在他们被删除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 示例使用的是用户自定义的作业名称

删除一个部署#

要删除一个部署：

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

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

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

自动清理#

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

用户自定义的作业名称#

要为任意作业触发一个 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