CI/CD 流水线

CI/CD 流水线是极狐GitLab CI/CD 的基础组件。流水线使用 YAML 关键字 配置在 .gitlab-ci.yml 文件中。

流水线可以为特定事件自动运行，诸如推送到某个分支、创建合并请求或按计划运行。当然，需要时也可以手动运行。

流水线包括：

  • 管局 YAML 关键字：用以控制项目流水线的行为。
  • 作业：执行命令以完成任务。比如，作业可以是编译、测试或部署代码。作业之间独立运行，并由 runners 执行。
  • Stages：作业的合集。Stages 是按顺序执行的，但作业在每个阶段是并行执行的。比如，一个早运行的 stage 有 lint 和编译代码两个作业，一个晚运行的 stage 有个测试和部署代码两个作业。如果 stage 中的所有作业成功，则流水线走线下一步。如果 stage 中的任何一个作业发生了失败，则下一个 stage 将不会被执行，流水线被提前结束。

一个典型的流水线可能包含四个阶段，按以下顺序执行：

  • 一个 build 阶段，有一个名为 compile 的作业。
  • 一个 test 阶段，有两个名为 test1 和 test2 的作业。这些测试只有在 compile 作业完成以后才会运行。
  • 一个 deploy 阶段，有一个名为 deploy-to-production 的作业。部署作业只有在 test 作业完成以后才会运行。
note 如果您有一个极狐GitLab 从中拉取的镜像仓库，您可能需要在项目的 设置 > 仓库 > 镜像仓库 > 触发镜像更新的流水线。

流水线类型

流水线可以通过多种不同的方式进行配置：

  • 基本流水线：同时运行每个阶段的所有内容，然后是下一个阶段。
  • 使用 needs 关键字的流水线：基于作业之间的依赖而运行，而且比基本流水线运行更快。
  • 合并请求的流水线：仅针对合并请求运行（而不是针对每次提交）。
  • 合并结果的流水线：是来自源分支的更改已经合并到目标分支的合并请求流水线。
  • 合并队列：使用合并结果流水线将合并一个接一个地排队
  • 多项目流水线：将不同项目的流水线组合在一起。
  • 父子流水线：将复杂的流水线分解为一个可以触发多个子流水线的父流水线，这些子流水线都运行在同一个项目中并具有相同的 SHA。这种流水线架构通常用于 mono-repos。

配置流水线

每个项目的流水线都用 YAML 关键字 配置在 .gitlab-ci.yml 文件中。当在极狐GitLab 中编辑 CI/CD 配置时，您应该使用 流水线编辑器。

您还可以通过极狐GitLab UI 对流水线的特定方面进行配置：

如果您在使用 VS Code 来编辑您的极狐GitLab CI/CD 配置，VS Code GitLab Workflow 扩展能够帮助您验证您的配置并查看您的流水线状态。

手动运行流水线

可以使用预定义或手动指定的变量手动执行流水线。

如果在流水线的正常操作之外需要流水线的结果（例如，代码构建），您可能会这样做。

要手动执行流水线：

  1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
  2. 在左侧边栏中，选择 构建 > 流水线。
  3. 选择 运行流水线。
  4. 在 为分支名称或标签运行 字段中，选择要为其运行流水线的分支或标签。
  5. 输入流水线运行所需的任何环境变量。您可以设置特定变量以使其值在表单中预填充。
  6. 选择 运行流水线。

流水线现在按照配置执行作业。

手动流水线中的预填充变量

引入于 13.7 版本

您可以使用 value 和 description 关键字来定义在手动运行流水线时，预填充的流水线级（全局）变量。使用描述来解释信息，例如变量的用途以及可接受的值是什么。

作业级变量不能预填入。

您可以更改预填入值，该值覆盖用于单个流水线运行的值。 使用此过程覆盖的任何变量都是可扩展的，不是隐藏的。 如果您没有在配置文件中为变量定义 value，变量名仍会列出，但值字段为空。

例如：

variables:
  DEPLOY_CREDENTIALS:
    description: "The deployment credentials."
  DEPLOY_ENVIRONMENT:
    description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice."
    value: "canary"

在此示例中：

  • DEPLOY_CREDENTIALS 列在 运行流水线 页面中，但未设置任何值。每次手动运行流水线时，用户都应定义该值。
  • DEPLOY_ENVIRONMENT 列在 运行流水线 页面中预先填入默认值 canary，并且消息解释了其他选项。

配置可选择的预填入变量值列表

  • 引入于 15.5 版本，功能标志为 run_pipeline_graphql。默认禁用。
  • options 关键字引入于 15.7 版本。
  • 一般可用于 15.7 版本。功能标志 run_pipeline_graphql 删除。

您可以定义一组 CI/CD 变量值，用户可以在手动运行流水线时从中进行选择。 这些值位于 运行流水线 页面的下拉列表中。将值选项列表添加到 options 并使用 value 设置默认值。value 中的字符串也必须包含在 options 列表中。

例如：

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    options:
      - "production"
      - "staging"
      - "canary"
    description: "The deployment target. Set to 'staging' by default."

使用 URL 查询字符串运行流水线

您可以使用查询字符串预填充 运行流水线 页面。例如，查询字符串 .../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar 预先填充 运行流水线 页面：

  • 运行字段：my_branch。
  • 变量部分：
    • 变量：
      • 键：foo
      • 值：bar
    • 文件：
      • 键：file_foo
      • 值：file_bar

pipelines/new URL 的格式为：

.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value>

支持以下参数：

  • ref：指定用于填充 运行 字段的分支。
  • var：指定一个 Variable 变量。
  • file_var：指定一个 File 变量。

对于每个 var 或 file_var，都需要一个键和值。

向您的流水线添加手动交互

手动作业允许您在推进流水线之前需要手动交互。

您可以直接从流水线图中执行此操作。只需单击运行按钮即可执行该特定作业。

例如，您的流水线可以自动启动，但需要手动操作才能部署到生产。 在下面的示例中，production 阶段有一个带有手动操作的作业：

Pipelines example

在一个阶段启动多个手动操作

如果一个 stage 只包含手动作业，您可以在上面的 stage 中通过选择 Run all manual ( ) 来同时启动所有作业。如果 stage 不包含手动作业，则不会展示此选项。

跳过流水线

要在不触发流水线的情况下推送提交，请使用任何大写形式在提交消息中添加 [ci skip] 或 [skip ci]。

或者，如果您使用的是 Git 2.10 或更高版本，请使用 ci.skip Git 推送选项。 ci.skip 推送选项不会跳过合并请求流水线。

删除流水线

具有拥有者角色的项目用户可以删除流水线：

  1. 在左侧导航栏，选择 查找或前往 并找到您的项目。
  2. 选择 构建 > 流水线。
  3. 选择要删除流水线的流水线 ID（比如 #123456789）或流水线状态图标（比如 通过）。
  4. 在流水线详情页面的右上角，选择 删除流水线。

删除流水线不会自动删除其子流水线。

caution 删除流水线会使所有流水线缓存过期，并立即删除所有相关对象，例如构建、日志、产物和触发器。此操作无法撤消。

受保护分支上的流水线安全

在受保护分支上执行流水线时，需要遵守严格的安全模式。

仅当用户在该特定分支上允许合并或推送时，才允许在受保护分支上执行以下操作：

  • 运行手动流水线（使用 Web UI 或 pipelines API）。
  • 运行计划流水线。
  • 使用触发器运行流水线。
  • 运行按需 DAST 扫描。
  • 在现有流水线上触发手动操作。
  • 重试或取消现有作业（使用 Web UI 或流水线 API）。

标记为 受保护 的 变量 只能由在受保护分支上运行的作业访问，防止不受信任的用户意外访问敏感信息，如部署凭据和令牌。

标记为 受保护 的 Runners 只能在受保护的分支上运行作业，防止不受信任的代码在受保护的 runner 上执行，并保护部署密钥和其他凭据不被无意访问。为了确保要在受保护 runner 上执行的作业不使用常规 runner，必须相应地标记它们。

对于加强流水线的额外安全推荐，可以查看部署安全页面。

当上游项目重建时触发流水线（弃用）

caution 此功能已经在极狐GitLab 17.6 中被弃用，并计划在 18.0 中被移除。取而代之，使用具有流水线触发器令牌的 CI/CD 作业。这是一个巨大变更。

您还可以童工配置实现基于不同项目上的标签来自动触发流水线。当订阅项目上的新标签流水线结束时，它就会在您项目的默认分支上触发流水线，无论该标签流水线是否成功、失败或取消。

先决条件：

  • 上游项目必须是公共的。
  • 用户必须在上游项目中具有开发人员角色。

如要在上游项目重建时触发流水线：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 流水线订阅。
  4. 选择 添加项目。
  5. 输入您要订阅的项目，格式为 <namespace>/<project>。例如，如果项目是 https://gitlab.com/gitlab-org/gitlab，则使用 gitlab-org/gitlab。
  6. 选择 订阅。

上游流水线订阅的最大数量默认是 2，上游和下游项目都一样。在私有化部署实例上，管理员可以更改此限制。

如何计算流水线持续时间

给定管道的总运行时间不包括重试和挂起（排队）时间。

每个作业都表示为一个 Period，它包括：

  • Period#first（作业开始时）。
  • Period#last（当工作完成时）。

一个简单的例子是：

  • A (1, 3)
  • B (2, 4)
  • C (6, 7)

在示例中：

  • A 从 1 开始，到 3 结束。
  • B 从 2 开始，到 4 结束。
  • C 从 6 点开始，到 7 点结束。

它可以被视为：

0  1  2  3  4  5  6  7
   AAAAAAA
      BBBBBBB
                  CCCC

A、B 和 C 的并集是 (1, 4) 和 (6, 7)。 因此，总运行时间为：

(4 - 1) + (7 - 6) => 4

查看流水线

要查看项目运行的所有流水线：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的项目。
  2. 选择 构建 > 流水线。

您可以通过如下方式来过滤 流水线：

  • 触发者
  • 分支名称
  • 状态
  • 标签
  • 源

在顶部的下拉菜单中选择 流水线 ID（实例内唯一的 ID）。选择 流水线 IID 来展示流水线 IID（内部 ID，仅在项目内唯一）

比如：

Pipelines list page

如要查看与指定流水线相关的流水线，前往合并请求的 流水线 选项卡。

流水线详情

  • 流水线详情查看已在极狐GitLab 16.6 中更新，使用名为 new_pipeline_graph 的功能标志。默认禁用。
  • 更新的流水线详情视图已在极狐GitLab 16.8 中在 JihuLab.com 上启用。

选择流水线来打开流水线详情页面，其中显示了流水线中的每个作业。从此页面上您可以取消运行的流水线、重试失败的作业或删除流水线。

流水线详情页面以图表形式展示流水线中的所有作业：

Pipeline detail page

您可以使用标准的 URL 来访问特定流水线的详情：

  • gitlab.example.com/my-group/my-project/-/pipelines/pipelines/latest： 项目中默认分支上最新提交的最新流水线的详细信息页面。
  • gitlab.example.com/my-group/my-project/-/pipelines/<branch>/latest： 项目中分支 上最近一次提交的最新流水线的详细信息页面。

通过 stage 或 needs 配置对作业进行分组

当您使用 needs 关键字配置作业时，您有两种选项来在流水线详情页面上对作业进行分组。通过 stage 配置进行作业分组，在 作业分组 部分选择 stage：

jobs grouped by stage

通过 needs 配置进行作业分组，选择 作业依赖。您还可以选择性地选择 显示依赖项以在作业之间渲染依赖项线。

jobs grouped by job dependencies

最左侧列中的作业先运行，并且依赖于它们的作业被分组在下一列中。在本例中：

  • lint-job 是通过 needs: [] 配置的，所以它不依赖于任何作业，因此它显示在第一列，尽管它位于 test 阶段。
  • test-job1 依赖于 build-job1，而 test-job2 同时依赖于 build-job1 和 build-job2，所以这两个测试作业都显示在第二列中。
  • deploy 作业都依赖于第二列中的作业（他们又依赖于其他较早的作业），因此依赖作业显示在第三列中。

当您将鼠标悬停在作业依赖视图中的一个作业上时，在所选作业之前必须运行的每个作业都会被高亮显示：

pipeline dependency view on hover

流水线迷你图

流水线迷你图使用较少的空间，并可以快速了解哪些作业通过了，哪些失败了。它们显示了单个提交的所有相关作业，并显示了流水线的每个阶段的结果。您可以快速查看失败的内容并修复它。

流水线迷你图总是按 stage 分组，可以在极狐GitLab 中的任何地方显示流水线或提交的详细信息。

Pipeline mini graph

流水线迷你图中的 stage 是可扩展的。将鼠标悬停在每个阶段上，以查看名称和状态，然后选择一个 stage 以展开其作业列表。

下游流水线图标

当流水线包含一个触发下游流水线的作业时，您可以在流水线详情视图和迷你图中看到下游流水线。

在流水线详情查看中，您可以在流水线图的右侧看到每个触发的下游流水线的卡片。将鼠标悬停在卡片上，以查看触发下游流水线的作业。选择一个卡片以在流水线图的右侧显示下游流水线。

在流水线迷你图中，每个触发的下游流水线的状态显示为迷你图右侧的附加状态图标。选择一个下游流水线状态图标以转到该下游流水线的详细页面。

流水线成功和持续图标

流水线在 CI/CD 分析 页面上可用。

流水线徽章

流水线状态和测试覆盖率报告徽章对每一个项目都是可用且可配置的。关于给项目添加流水线徽章的详情，可以查看流水线徽章。

流水线 API

极狐GitLab 为如下内容提供 API 端点：

Ref specs for runners

当 runner 选择流水线作业时，系统会提供该作业的元数据，包括 Git refspecs，指示哪个引用（分支、标签等）和提交（SHA1) 从您的项目仓库中检出。

下表列出了为每种流水线类型注入的 refspecs：

流水线类型 Refspecs
分支流水线 +<sha>:refs/pipelines/<id> 和 +refs/heads/<name>:refs/remotes/origin/<name>
标签流水线 +<sha>:refs/pipelines/<id> 和 +refs/tags/<name>:refs/tags/<name>
合并请求流水线 +<sha>:refs/pipelines/<id>

refs refs/heads/<name> 和 refs/tags/<name> 存在于您的项目仓库中。极狐GitLab 在运行流水线作业期间，生成特殊引用 refs/pipelines/<id>。即使在删除关联的分支或标记后，也可以创建此引用。因此，它在某些功能中很有用，例如自动停止环境和可能运行流水线的合并队列分支删除后。

故障排查

用户删除后流水线订阅还在继续

当用户要删除他们的 JihuLab.com 账号时，删除在 7 天之内不会发生。在此期间，任何由该用户创建的流水线订阅都会继续使用该用户的原始权限运行。为了防止未经授权的流水线执行，立即更新已删除用户的流水线订阅设置。