Help us learn about your current experience with the documentation. Take the survey.

GitLab Pages 并行部署

  • Tier: Premium, Ultimate
  • Offering: Gitlab.com, GitLab Self-Managed, GitLab Dedicated

使用并行部署，你可以同时发布多个 GitLab Pages 网站版本。每个版本都有基于你指定的路径前缀的唯一 URL。

使用并行部署来：

  • 在合并到生产环境之前，增强在开发分支中测试更改的工作流程。
  • 与利益相关者分享工作预览以获取反馈。
  • 同时为多个软件版本维护文档。
  • 为不同受众发布本地化内容。
  • 在最终发布前创建用于审查的暂存环境。

你网站的每个版本都会获得基于你指定的路径前缀的唯一 URL。 控制这些并行部署存在的时间。 默认情况下，它们在 24 小时后过期，但你可以自定义此持续时间以适应你的审查时间线。

创建并行部署

先决条件：

要创建并行部署：

  1. 在你的 .gitlab-ci.yml 文件中，添加一个带有 path_prefix 的 Pages 作业：

    pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:  # 指定这是一个 Pages 作业并发布默认的公共目录
    path_prefix: "$CI_COMMIT_BRANCH"

    path_prefix 的值：

    • 会被转换为小写。
    • 可以包含数字（0-9）、字母（a-z）和句点（.）。
    • 其他字符会被替换为连字符（-）。
    • 不能以连字符（-）或句点（.）开头或结尾，因此会被移除。
    • 必须是 63 字节或更短。更长的内容会被截断。

  2. 可选。如果你想要动态前缀，在你的 path_prefix 中使用 CI/CD 变量。 例如：

    pages:
  path_prefix: "mr-$CI_MERGE_REQUEST_IID" # 生成类似 mr-123 的路径

  3. 可选。要为部署设置过期时间，添加 expire_in：

    pages:
  pages:
    path_prefix: "$CI_COMMIT_BRANCH"
    expire_in: 1 week

    默认情况下，并行部署在 24 小时后 过期。

  4. 提交你的更改并推送到你的仓库。

部署可以通过以下方式访问：

  • 使用 唯一域名：https://project-123456.gitlab.io/your-prefix-name。
  • 不使用唯一域名：https://namespace.gitlab.io/project/your-prefix-name。

网站域名和公共目录之间的 URL 路径由 path_prefix 决定。 例如，如果你的主部署在 /index.html 有内容，带有前缀 staging 的并行部署可以在 /staging/index.html 访问相同的内容。

为防止路径冲突，避免使用与你网站中现有文件夹名称匹配的路径前缀。 有关更多信息，请参阅 路径冲突。

示例配置

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

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

如果 pages.path_prefix 配置为项目分支名称， 如 path_prefix = $CI_COMMIT_BRANCH，并且有一个名为 username/testing_feature 的分支， 这个并行 Pages 部署可以通过以下方式访问：

  • 使用 唯一域名：https://project-123456.gitlab.io/username-testing-feature。
  • 不使用唯一域名：https://namespace.gitlab.io/project/username-testing-feature。

限制

并行部署的数量受根级命名空间限制。有关具体限制：

要立即减少你命名空间中的活动部署数量， 删除一些部署。有关更多信息，请参阅 删除部署。

要配置自动删除旧部署的过期时间，请参阅 过期部署。

过期

默认情况下，并行部署在 24 小时后 过期， 之后它们会被删除。如果你使用的是自托管实例，你的实例管理员可以 配置不同的默认持续时间。

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

要防止部署自动过期，将 pages.expire_in 设置为 never。

路径冲突

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 指向网站的 documents 部署上的 /index.html，而不是网站的 main 部署上的 documents/index.html。

将 CI/CD 变量 与其他字符串混合可以减少路径冲突的可能性。 例如：

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  variables:
    PAGES_PREFIX: "" # 默认没有前缀（主分支）
  pages:  # 指定这是一个 Pages 作业并发布默认的公共目录
    path_prefix: "$PAGES_PREFIX"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 在默认分支上运行（使用默认的 PAGES_PREFIX）
    - if: $CI_COMMIT_BRANCH == "staging" # 在主分支上运行（使用默认的 PAGES_PREFIX）
      variables:
        PAGES_PREFIX: '_stg' # 为暂存分支添加 _stg 前缀
    - 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 部署来创建一个新的 环境。 例如：

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  variables:
    PAGES_PREFIX: "" # 默认没有前缀（在默认分支上运行）
  pages:  # 指定这是一个 Pages 作业并发布默认的公共目录
    path_prefix: "$PAGES_PREFIX"
  environment:
    name: "Pages ${PAGES_PREFIX}"
    url: $CI_PAGES_URL
  rules:
    - if: $CI_COMMIT_BRANCH == "staging" # 确保在默认分支上运行（使用默认的 PAGES_PREFIX）
      variables:
        PAGES_PREFIX: '_stg' # 为暂存分支添加 _stg 前缀
    - 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 示例使用了 用户定义的作业名称。

自动清理

由带有 path_prefix 的合并请求创建的并行 Pages 部署， 在合并请求关闭或合并时会被自动删除。

与重定向一起使用

重定向使用绝对路径。 因为并行部署在子路径上可用，所以重定向需要对 _redirects 文件进行 额外的修改才能在并行部署中工作。

现有文件始终优先于重定向规则，因此你可以使用通配符占位符 来捕获对前缀路径的请求。

如果你的 path_prefix 是 /mr-${$CI_MERGE_REQUEST_IID}，调整这个 _redirect 文件示例 以重定向主部署和并行部署的请求：

# 重定向主部署
/will-redirect.html /redirected.html 302

# 重定向并行部署
/*/will-redirect.html /:splat/redirected.html 302