CI/CD 流水线

CI/CD 流水线是极狐GitLab CI/CD 的基本组成部分。流水线通过 YAML 关键字在 .gitlab-ci.yml 文件中进行配置。

流水线可以针对特定事件自动运行，例如推送到分支、创建合并请求或按计划运行时。需要时，您也可以手动运行流水线。

流水线由以下部分组成：

• 全局 YAML 关键字，用于控制项目流水线的整体行为。
• 作业，执行命令以完成某项任务。例如，作业可以编译、测试或部署代码。作业彼此独立运行，并由 Runner 执行。
• 阶段，用于定义如何将作业分组。阶段按顺序运行，而同一阶段中的作业并行运行。例如，较早的阶段可以包含对代码进行 lint 和编译的作业，而较晚的阶段可以包含测试和部署代码的作业。如果某个阶段中的所有作业都成功，流水线会进入下一个阶段。如果某个阶段中有任何作业失败，下一个阶段（通常）不会执行，流水线会提前结束。

一个小的流水线可以由三个阶段组成，按以下顺序执行：

• 一个 build 阶段，其中包含一个名为 compile的作业，用于编译项目代码。
• 一个 test 阶段，其中包含两个名为 test1 和 test2的作业，用于对代码运行各种测试。这些测试仅在 compile 作业成功完成后才会运行。
• 一个 deploy 阶段，其中包含一个名为 deploy-to-production的作业。该作业仅在 test 阶段中的两个作业都成功启动并完成后才会运行。

要开始使用您的第一个流水线，请参阅创建并运行您的第一个极狐GitLab CI/CD 流水线。

流水线的类型#

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

• 基础流水线在每个阶段中并发运行所有内容，然后进入下一个阶段。
• 使用 needs 关键字的流水线基于作业之间的依赖关系运行，可以比基础流水线运行得更快。
• 分支流水线在您每次向分支推送提交时运行，无需任何配置。
• 合并请求流水线仅针对合并请求运行（而不是针对每次提交）。
• 合并结果流水线是一种合并请求流水线，其行为如同源分支的更改已合并到目标分支中。
• 合并列车使用合并结果流水线将合并逐一排入队列。
• 工作负载流水线在临时 Git 引用上运行，用于按需执行流水线，而无需创建临时分支。
• 父子流水线将复杂的流水线分解为一个父流水线，该父流水线可以触发多个子流水线，这些子流水线都在同一项目中运行，并使用相同的 SHA。这种流水线架构通常用于单体仓库。
• 多项目流水线将不同项目的流水线组合在一起。

配置流水线#

流水线及其组成部分的作业和阶段，通过每个项目的 CI/CD 流水线配置文件中的 YAML 关键字进行定义。在极狐GitLab 中编辑 CI/CD 配置时，您应使用流水线编辑器。

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

• 每个项目的流水线设置。
• 流水线计划。
• 自定义 CI/CD 变量。

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

手动运行流水线#

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

当流水线的结果（例如代码构建）需要在流水线的标准运行之外使用时，您可能会这样做。

要手动执行流水线：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择构建 > 流水线。
3. 选择新建流水线。
4. 在运行分支或标签名称字段中，选择要为其运行流水线的分支或标签。
5. 可选。输入以下任意内容：
   • 流水线运行所需的输入。输入的默认值已预填，但可以修改。输入值必须符合预期的类型。
   • CI/CD 变量。您可以配置变量，使其值在表单中预填。与 CI/CD 变量相比，使用输入来控制流水线行为可提供更高的安全性和灵活性。
6. 选择新建流水线。

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

查看手动流水线变量#

您可以查看手动运行流水线时指定的所有变量。

先决条件：

• 您必须拥有项目的所有者角色。

所需角色取决于您要执行的操作：

要查看手动流水线变量：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择设置 > CI/CD。
3. 选择显示流水线变量。
4. 转到构建 > 流水线，然后选择手动运行的流水线。
5. 选择手动变量标签页。

变量值默认会被遮盖。如果您拥有开发者、维护者或所有者角色，可以选择眼睛图标以显示值。

在手动流水线中预填变量#

您可以使用 description 和 value 关键字来定义流水线级（全局）变量，这些变量在手动运行流水线时会被预填。使用描述来说明诸如该变量的用途以及可接受的值等信息。您可以在描述中使用 Markdown。

作业级变量无法预填。

在手动触发的流水线中，新建流水线页面会显示所有在 .gitlab-ci.yml 文件中定义了 description的流水线级变量。描述显示在变量下方。

您可以更改预填的值，这会为该次流水线运行覆盖该值。通过此过程覆盖的任何变量都会被展开，而不会被遮盖。如果您未在配置文件中为变量定义 value，变量名称仍会列出，但值字段为空白。

例如：

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

在此示例中：

• DEPLOY_CREDENTIALS 列在新建流水线页面中，但未设置值。用户需要在每次手动运行流水线时定义该值。
• DEPLOY_ENVIRONMENT 在新建流水线页面中预填为默认值 canary，并且消息中说明了其他选项。

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

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

例如：

yaml
1variables:
2  DEPLOY_ENVIRONMENT:
3    value: "staging"
4    options:
5      - "production"
6      - "staging"
7      - "canary"
8    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 的格式为：

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

支持以下参数：

• ref：指定要填充在分支名称或标签中运行字段的分支。
• var：指定一个 Variable 变量。
• file_var：指定一个 File 变量。

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

为流水线添加手动交互#

手动作业允许您在流水线中继续推进之前要求进行手动交互。

您可以直接从流水线图中执行此操作。选择运行（）以执行该特定作业。

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

启动阶段中的所有手动作业#

如果某个阶段仅包含手动作业，您可以通过选择阶段上方的全部手动运行（）同时启动所有作业。如果该阶段包含非手动作业，则不会显示该选项。

跳过流水线#

要在不触发流水线的情况下推送提交，请在提交消息中添加 [ci skip] 或 [skip ci]（大小写不限）。

或者，使用 Git 2.10 或更高版本时，使用 ci.skip Git push 选项。ci.skip push 选项不会跳过合并请求流水线。

当您跳过流水线时：

• 极狐GitLab 中仍会创建一个空的流水线，其中没有作业或阶段。该流水线会显示在 UI 中，并可在 API 响应中返回。
• 该流水线在 UI 中的状态为 Skipped，在 API 中为 skipped。

删除流水线#

先决条件：

• 您必须拥有项目的所有者角色，或具有实例的管理员访问权限。
• 如果实例启用了管理员模式，管理员必须为其会话开启管理员模式。

要删除流水线：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择构建 > 流水线。
3. 选择要删除的流水线的流水线 ID（例如 #123456789）或流水线状态图标（例如 Passed）。
4. 在流水线详情页的右上角，选择删除。

删除流水线不会自动删除其子流水线。更多详情，请参阅议题 39503。

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

在受保护分支上执行流水线时，会强制执行严格的安全模型。

如果用户被允许合并或推送到该特定分支，则允许在受保护分支上执行以下操作：

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

标记为受保护的变量可供在受保护分支的流水线中运行的作业访问。只有在用户有权访问部署凭据和令牌等敏感信息时，才应授予其合并到受保护分支的权限。

标记为受保护的 Runner 只能在受保护分支上运行作业，从而防止不受信任的代码在受保护的 Runner 上执行，并避免部署密钥和其他凭据被意外访问。为确保计划在受保护 Runner 上执行的作业不使用常规 Runner，必须相应地为其添加标签。

请查看合并请求流水线上下文中受保护变量和 Runner 的访问方式。

有关保护流水线的其他安全建议，请查看部署安全页面。

当上游项目重新构建时触发流水线#

您可以设置项目，使其基于另一个项目中的标签自动触发流水线。当订阅项目中的新标签流水线完成时，它会在您项目的默认分支上触发流水线，无论该标签流水线是成功、失败还是取消。

作为替代方案，您可以使用带流水线触发器令牌的 CI/CD 作业在另一个流水线运行时触发流水线。此方法比流水线订阅更可靠、更灵活，是推荐的方法。

先决条件：

• 上游项目必须是公开的。
• 用户必须在上游项目中拥有开发者角色。

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

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择设置 > CI/CD。
3. 展开流水线订阅。
4. 选择添加项目。
5. 输入您要订阅的项目，格式为 <namespace>/<project>。例如，如果项目为 https://gitlab.com/gitlab-org/gitlab，请使用 gitlab-org/gitlab。
6. 选择订阅。

上游流水线订阅的最大数量默认对于上游和下游项目均为 2。在极狐GitLab 私有化部署上，管理员可以更改此限制。

流水线时长如何计算#

给定流水线的总运行时间不包括：

• 任何被重试或手动重新运行的作业的初始运行时长。
• 任何待处理（排队）时间。

这意味着，如果某个作业被重试或手动重新运行，则只有最新一次运行的时长会计入总运行时间。

每个作业表示为一个 Period，它由以下部分组成：

• Period#first（作业开始的时间）。
• Period#last（作业完成的时间）。

例如：

• A (0, 2)
• A' (2, 4)
  • A' 重试 A
• B (1, 3)
• C (6, 7)

在此示例中：

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

从视觉上看，可以表示为：

plaintext
0  1  2  3  4  5  6  7
AAAAAAA
   BBBBBBB
      A'A'A'A
                  CCCC

由于 A 被重试，因此会被忽略，只计算作业 A'。B、A' 和 C 的并集为 (1, 4) 和 (6, 7)。因此，总运行时间为：

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

查看流水线#

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

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择构建 > 流水线。

您可以按以下条件筛选流水线页面：

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

在右上角的下拉列表中选择流水线 ID 以显示流水线 ID（实例范围内的唯一 ID）。选择流水线 IID 以显示流水线 IID（内部 ID，仅在项目范围内唯一）。

要查看与特定合并请求相关的流水线，请转到合并请求中的流水线标签页。

流水线详情#

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

流水线详情页会显示流水线中所有作业的图：

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

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

按阶段或 needs 配置对作业分组#

当您使用 needs 关键字配置作业时，您有两种方式在流水线详情页中对作业进行分组。要按阶段配置对作业分组，请在按...分组作业部分中选择阶段：

要按 needs 配置对作业分组，请选择作业依赖项。您还可以选择显示依赖项以在相互依赖的作业之间绘制连线。

最左侧列中的作业最先运行，依赖于它们的作业会分组在接下来的列中。在此示例中：

• lint-job 配置了 needs: []，不依赖任何作业，因此尽管它位于 test 阶段，仍显示在第一列中。
• test-job1 依赖于 build-job1，而 test-job2 同时依赖于 build-job1 和 build-job2，因此两个测试作业都显示在第二列中。
• 两个 deploy 作业都依赖于第二列中的作业（这些作业本身又依赖于其他更早的作业），因此部署作业显示在第三列中。

当您在作业依赖项视图中将鼠标悬停在某个作业上时，必须先于所选作业运行的所有作业都会高亮显示：

流水线迷你图#

流水线迷你图占用的空间更少，可以让您快速了解所有作业是否通过或是否有作业失败。它们显示单个提交的所有相关作业，以及流水线每个阶段的最终结果。您可以快速查看哪些作业失败并进行修复。

流水线迷你图始终按阶段对作业分组，并在极狐GitLab 中显示流水线或提交详情时显示。

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

下游流水线图#

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

在流水线详情视图中，每个触发的下游流水线都会在流水线图右侧显示一张卡片。将鼠标悬停在卡片上可查看哪个作业触发了该下游流水线。选择卡片可在流水线图右侧显示下游流水线。

在流水线迷你图中，每个触发的下游流水线的状态会作为额外的状态图标显示在迷你图右侧。选择下游流水线状态图标可转到该下游流水线的详情页。

流水线成功率和时长图表#

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

流水线徽章#

每个项目都可以使用并配置流水线状态和测试覆盖率报告徽章。有关向项目添加流水线徽章的信息，请参阅流水线徽章。

流水线 API#

极狐GitLab 提供 API 端点以：

• 执行基本功能。更多信息，请参阅流水线 API。
• 维护流水线计划。更多信息，请参阅流水线计划 API。
• 触发流水线运行。更多信息，请参阅：
  • 通过 API 触发流水线。
  • 流水线触发器令牌 API。

Runner 的 ref 规格#

当 Runner 获取流水线作业时，极狐GitLab 会提供该作业的元数据。其中包括 Git refspec，它指示从您的项目代码仓库中检出哪个 ref（例如分支或标签）和提交（SHA1）。

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

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

故障排除#

用户删除后流水线订阅仍会继续#

当用户删除其 JihuLab.com 账号时，删除不会立即发生，而是在七天后生效。在此期间，该用户创建的任何流水线订阅都会继续以该用户原有的权限运行。为防止未经授权的流水线执行，请立即更新已删除用户的流水线订阅设置。

预填变量未显示在新建流水线页面中#

如果流水线的预定义变量定义在单独的文件中，它们可能不会显示在新建流水线页面中。您必须有权访问该单独文件，否则无法显示预定义变量。