CI/CD 流水线

CI/CD 流水线是 GitLab CI/CD 的核心组件。流水线通过 .gitlab-ci.yml 文件中的 YAML 关键字 进行配置。

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

流水线由以下部分组成：

• 全局 YAML 关键字：控制项目流水线的整体行为。
• Jobs：执行命令以完成任务。例如，job 可编译、测试或部署代码。Jobs 之间相互独立，由 runners 执行。
• 阶段（Stages）：定义如何将 jobs 分组。阶段按顺序运行，而同一阶段内的 jobs 并行执行。例如，早期阶段可包含代码检查和编译的 jobs，后续阶段可包含测试和部署的 jobs。若某阶段所有 jobs 成功，流水线进入下一阶段；若任一 job 失败，则下一阶段通常不会执行，流水线提前终止。

小型流水线可能包含三个阶段，按以下顺序执行：

• 构建（build）阶段：包含名为 compile 的 job，用于编译项目代码。
• 测试（test）阶段：包含名为 test1 和 test2 的两个 jobs，对代码执行多项测试。这些测试仅在 compile job 成功完成后运行。
• 部署（deploy）阶段：包含名为 deploy-to-production 的 job。该 job 仅在 test 阶段的所有 jobs 成功启动并完成后运行。

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

流水线类型

流水线可通过多种方式配置：

• 基础流水线：每个阶段内的 jobs 并发执行，随后进入下一阶段。
• 使用 needs 关键字的流水线：基于 jobs 间的依赖关系运行，可比基础流水线更快。
• 合并请求流水线：仅针对合并请求运行（而非每次提交）。
• 合并结果流水线：模拟源分支的更改已合并到目标分支的合并请求流水线。
• 合并列车（Merge trains）：使用合并结果流水线按顺序排队合并。
• 父子流水线：将复杂流水线拆分为一个父流水线（可触发多个子流水线），所有子流水线在同一项目和相同 SHA 下运行。此架构常用于单体仓库。
• 多项目流水线：组合不同项目的流水线。

配置流水线

流水线及其组件 jobs 和阶段通过项目 CI/CD 流水线配置文件中的 YAML 关键字 定义。在 GitLab 中编辑 CI/CD 配置时，应使用 流水线编辑器。

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

• 项目的流水线设置。
• 流水线调度。
• 自定义 CI/CD 变量。

若使用 VS Code 编辑 GitLab CI/CD 配置，VS Code 的 GitLab Workflow 扩展 可帮助您验证配置和查看流水线状态。

手动运行流水线

流水线可手动执行，支持预定义或手动指定的 变量。

当流水线结果（例如代码构建）需要在流水线标准操作之外使用时，可执行此操作。

手动执行流水线的步骤：

1. 在左侧边栏选择 Search or go to 并找到您的项目。
2. 选择 Build > Pipelines。
3. 选择 New pipeline。
4. 在 Run for branch name or tag 字段中，选择运行流水线的分支或标签。
5. （可选）输入：
   • 流水线运行所需的 Inputs。Inputs 的默认值已预填充，但可修改。输入值必须符合预期类型。
   • CI/CD 变量。您可配置变量使其在表单中预填充值。使用 Inputs 控制流水线行为比 CI/CD 变量更安全灵活。
6. 选择 New pipeline。

流水线现在按配置执行 jobs。

手动流水线中预填充变量

您可使用 description 和 value 关键字定义流水线级（全局）变量，在手动运行流水线时预填充。使用 description 说明变量用途及有效值。描述中支持 Markdown。

Job 级变量无法预填充。

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

您可修改预填充的值，该值将覆盖单次流水线运行的值。通过此过程覆盖的变量会被展开而非屏蔽。若未在配置文件中为变量定义 value，变量名称仍会列出，但值字段为空。

例如：

variables:
  DEPLOY_CREDENTIALS:
    description: "部署凭据。"
  DEPLOY_ENVIRONMENT:
    description: "选择部署目标。有效选项：'canary'（金丝雀）、'staging'（预发布）、'production'（生产）或您选择的稳定分支。"
    value: "canary"

在此示例中：

• DEPLOY_CREDENTIALS 列在 New pipeline 页面，但未设置值。每次手动运行流水线时需用户定义值。
• DEPLOY_ENVIRONMENT 在 New pipeline 页面预填充为默认值 canary，描述中说明其他选项。

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

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

例如：

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    options:
      - "production"
      - "staging"
      - "canary"
    description: "部署目标。默认设置为 'staging'。"

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

您可使用查询字符串预填充 New pipeline 页面。例如，查询字符串 .../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar 会预填充：

• Run for 字段：my_branch。
• Variables 部分：
  • 变量：
    • 键：foo
    • 值：bar
  • 文件：
    • 键：file_foo
    • 值：file_bar

pipelines/new URL 的格式为：

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

支持以下参数：

• ref：指定填充 Run for 字段的分支。
• var：指定 Variable 变量。
• file_var：指定 File 变量。

每个 var 或 file_var 需提供键和值。

在流水线中添加手动交互

手动 jobs 要求在流水线继续前需手动操作。

您可直接从流水线图中操作。选择 Run（ ）执行特定 job。

例如，流水线可自动启动，但需手动操作才能部署到生产环境。在以下示例中，production 阶段包含需手动操作的 job：

启动阶段中的所有手动 jobs

若某阶段仅包含手动 jobs，可通过选择阶段上方的 Run all manual（ ）同时启动所有 jobs。若阶段包含非手动 jobs，则不显示该选项。

跳过流水线

要提交代码而不触发流水线，在提交消息中添加 [ci skip] 或 [skip ci]（任意大小写）。

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

删除流水线

项目 Owner 角色用户可删除流水线：

1. 在左侧边栏选择 Search or go to 并找到您的项目。
2. 选择 Build > Pipelines。
3. 选择要删除的流水线 ID（例如 #123456789）或流水线状态图标（例如 Passed）。
4. 在流水线详情页面右上角选择 Delete。

删除流水线不会自动删除其子流水线。详情请参见 issue 39503。

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

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

若用户有权限合并或推送到该特定分支，则允许以下操作：

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

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

标记为 受保护 的 runners 仅能在受保护分支上运行 jobs，防止不受信任的代码在受保护 runner 上执行，避免意外访问部署密钥和其他凭据。为确保应在受保护 runners 上执行的 jobs 不使用普通 runners，必须相应标记。

请查阅文档了解合并请求流水线中受保护变量和 runners 的访问控制。

请查阅部署安全页面获取保护流水线的其他安全建议。

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

您可配置项目，使其根据不同项目中的标签自动触发流水线。当订阅项目的新标签流水线完成时，无论其成功、失败或取消，都会触发您项目默认分支上的流水线。

先决条件：

• 上游项目必须为公开项目。
• 用户在上游项目中需具有 Developer 角色。

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

1. 在左侧边栏选择 Search or go to 并找到您的项目。
2. 选择 Settings > CI/CD。
3. 展开 Pipeline subscriptions。
4. 选择 Add project。
5. 输入要订阅的项目，格式为 <namespace>/<project>。例如，若项目为 https://gitlab.com/gitlab-org/gitlab，则使用 gitlab-org/gitlab。
6. 选择 Subscribe。

默认情况下，上游和下游项目的上游流水线订阅数上限均为 2。在 GitLab Self-Managed 上，管理员可更改此限制。

流水线持续时间计算方式

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

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

这意味着若 job 被重试或手动重运行，仅最新运行的时长计入总运行时间。

每个 job 表示为一个 Period，包含：

• Period#first（job 开始时间）。
• Period#last（job 结束时间）。

简单示例如下：

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

在示例中：

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

可视化表示为：

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

因 A 被重试，忽略 A 仅计算 A’。 B、A’ 和 C 的并集为 (1, 4) 和 (6, 7)。因此总运行时间为：

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

查看流水线

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

1. 在左侧边栏选择 Search or go to 并找到您的项目。
2. 选择 Build > Pipelines。

您可按以下条件筛选 Pipelines 页面：

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

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

例如：

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

流水线详情

选择流水线打开流水线详情页面，显示流水线中的所有 jobs。从此页面可取消运行中的流水线、重试失败的 jobs 或删除流水线。

流水线详情页面显示流水线所有 jobs 的图表：

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

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

按阶段或 needs 配置分组 jobs

当使用 needs 关键字配置 jobs 时，您有两种选项在流水线详情页面分组 jobs。要按阶段配置分组，在 Group jobs by 部分选择 stage：

要按 needs 配置分组，选择 Job dependencies。可选择 Show dependencies 渲染依赖关系线。

最左侧列的 jobs 先运行，依赖它们的 jobs 分组在后续列中。在此示例中：

• lint-job 配置为 needs: [] 且不依赖任何 jobs，因此显示在第一列，尽管它属于 test 阶段。
• test-job1 依赖 build-job1，test-job2 依赖 build-job1 和 build-job2，因此两个测试 jobs 显示在第二列。
• 两个 deploy jobs 依赖第二列的 jobs（这些 jobs 又依赖更早的 jobs），因此部署 jobs 显示在第三列。

在 Job dependencies 视图中悬停 job 时，所有必须在选定 job 之前运行的 jobs 将高亮显示：

流水线迷你图

流水线迷你图占用空间更少，可快速查看所有 jobs 是否通过或失败。它们显示单个提交的所有相关 jobs 及流水线各阶段的最终结果。您可快速定位问题并修复。

流水线迷你图始终按阶段分组，在 GitLab 中显示流水线或提交详情时可见。

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

下游流水线图

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

在流水线详情视图中，右侧的流水线图旁会显示每个触发下游流水线的卡片。悬停卡片查看触发下游流水线的 job。选择卡片在流水线图右侧显示下游流水线。

在流水线迷你图中，所有触发的下游流水线状态显示为迷你图右侧的附加状态图标。选择下游流水线状态图标跳转至其详情页。

流水线成功率和持续时间图表

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

流水线徽章

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

流水线 API

GitLab 提供 API 端点用于：

• 执行基础功能。更多信息请参阅 Pipelines API。
• 维护流水线调度。更多信息请参阅 Pipeline schedules API。
• 触发流水线运行。更多信息请参阅：
  • 通过 API 触发流水线。
  • Pipeline triggers API。

Runners 的 Ref specs

当 runner 选取流水线 job 时，GitLab 提供 job 的元数据，包括 Git refspecs，指示从项目仓库检出哪个 ref（如分支或标签）和提交（SHA1）。

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

refs/heads/<name> 和 refs/tags/<name> 存在于您的项目仓库中。GitLab 在运行流水线 job 期间生成特殊 ref refs/pipelines/<id>。此 ref 可在关联分支或标签删除后创建，因此对自动停止环境和可能在分支删除后运行的合并列车等功能很有用。

故障排除

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

当用户删除 GitLab.com 账户时，删除操作不会立即生效，有七天宽限期。此期间内，该用户创建的流水线订阅仍以用户原始权限运行。为防止未授权的流水线执行，请立即更新已删除用户的流水线订阅设置。