CI/CD pipelines

CI/CD 流水线#

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

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

流水线由以下部分组成：

• 控制项目流水线整体行为的全局 YAML 关键字。
• 执行命令以完成任务的作业。例如，一个作业可以编译、测试或部署代码。作业相互独立运行，并由runners执行。
• 阶段，用于定义如何将作业分组。阶段按顺序运行，而一个阶段中的作业则并行运行。例如，一个早期阶段可以有作业来进行代码的语法检查和编译，而后期阶段可以有作业进行代码的测试和部署。如果一个阶段中的所有作业都成功，流水线将进入下一个阶段。如果一个阶段中的任何作业失败，通常不会执行下一个阶段，流水线会提前结束。

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

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

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

流水线类型#

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

• 基础流水线在每个阶段中并发运行所有内容，然后是下一个阶段。
• 使用 needs 关键字的流水线基于作业之间的依赖关系运行，并且可以比基础流水线运行得更快。
• 合并请求流水线仅为合并请求运行（而不是每个提交）。
• 合并结果流水线是合并请求流水线，其表现为源分支的更改已合并到目标分支中。
• 合并列车使用合并结果流水线依次排队合并。
• 父子流水线将复杂的流水线分解为一个父流水线，可以触发多个子子流水线，它们都在同一个项目中并使用相同的 SHA 运行。这种流水线架构常用于单一代码库。
• 多项目流水线将不同项目的流水线组合在一起。

配置流水线#

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

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

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

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

手动运行流水线#

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

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

要手动执行流水线：

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

流水线现在根据配置执行作业。

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

你可以使用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 推送选项。ci.skip 推送选项不会跳过合并请求流水线。

删除流水线#

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

1. 在左侧边栏中，选择 搜索或转到 并找到你的项目。
2. 选择 构建 > 流水线。
3. 选择要删除的流水线的流水线 ID（例如 #123456789）或流水线状态图标（例如 已通过）。
4. 在流水线详细信息页面的右上角，选择 删除。

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

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

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

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

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

标记为保护的变量可供在保护分支的流水线中运行的作业访问。仅将用户分配合并到保护分支的权利，如果他们有权限访问敏感信息，如部署凭据和令牌。

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

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

如何计算流水线持续时间#

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

• 任何重试或手动重新运行的作业的初始运行时长。
• 任何挂起（队列）时间。

这意味着如果作业被重试或手动重新运行，则仅包含最新运行的时长在总运行时间中。

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

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

一个简单的例子是：

• 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 结束。

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

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/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。

Runners 的 Ref 规格#

当 runner 选择流水线作业时，极狐GitLab 提供该作业的元数据。这包括Git refspecs，指示从你的项目存储库中检出的 ref（例如分支或标签）和提交（SHA1）。

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

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

故障排除#

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

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