极狐GitLab CI/CD `workflow` 关键字

workflow:rules 的常用 if 子句
workflow: rules 示例
workflow:rules 模板（已弃用）
故障排除
- 合并请求卡在 Checking pipeline status. 消息

Tier: 基础版, 专业版, 旗舰版
Offering: JihuLab.com, 私有化部署

使用 workflow 关键字来控制何时创建流水线。

workflow 关键字在作业之前进行评估。例如，如果某个作业被配置为在标签时运行，但工作流阻止标签流水线，则该作业永远不会运行。

`workflow:rules` 的常用 `if` 子句

以下是 workflow: rules 的一些示例 if 子句：

示例规则	详情
`if: '$CI_PIPELINE_SOURCE == "merge_request_event"'`	控制合并请求流水线的运行时间。
`if: '$CI_PIPELINE_SOURCE == "push"'`	控制分支流水线和标签流水线的运行时间。
`if: $CI_COMMIT_TAG`	控制标签流水线的运行时间。
`if: $CI_COMMIT_BRANCH`	控制分支流水线的运行时间。

查看 common if clauses for rules 以获取更多示例。

`workflow: rules` 示例

在以下示例中：

对于所有 push 事件（分支更改和新标签）运行流水线。
提交消息以 -draft 结尾的 push 事件流水线不运行，因为它们被设置为 when: never。
计划或合并请求的流水线也不运行，因为没有规则对它们评估为真。

workflow:
  rules:
    - if: $CI_COMMIT_MESSAGE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "push"

此示例有严格的规则，流水线在任何其他情况下都不运行。

或者，所有规则都可以是 when: never，并有一个最终的 when: always 规则。与 when: never 规则匹配的流水线不运行。所有其他流水线类型运行。例如：

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - if: $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always

此示例阻止计划的流水线或 push（分支和标签）流水线。最后的 when: always 规则运行所有其他流水线类型，包括合并请求流水线。

在分支流水线和合并请求流水线之间切换

要在创建合并请求后使流水线从分支流水线切换到合并请求流水线，请在 .gitlab-ci.yml 文件中添加 workflow: rules 部分。

如果您同时使用两种流水线类型，重复流水线可能会同时运行。为了防止重复流水线，请使用 CI_OPEN_MERGE_REQUESTS 变量。

以下示例适用于仅运行分支和合并请求流水线的项目，但不运行其他任何情况的流水线。它运行：

当分支没有打开合并请求时的分支流水线。
当分支有打开合并请求时的合并请求流水线。

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

如果极狐GitLab尝试触发：

合并请求流水线，则启动流水线。例如，可以通过推送到关联有打开合并请求的分支来触发合并请求流水线。
分支流水线，但该分支有打开的合并请求，则不运行分支流水线。例如，可以通过对分支的更改、API 调用、计划的流水线等触发分支流水线。
分支流水线，但分支没有打开合并请求，则运行分支流水线。

您还可以向现有的 workflow 部分添加规则，以在创建合并请求时从分支流水线切换到合并请求流水线。

将此规则添加到 workflow 部分的顶部，然后是已经存在的其他规则：

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - # Previously defined workflow rules here

触发的流水线在分支上运行时会设置 $CI_COMMIT_BRANCH，并可能被类似的规则阻止。触发的流水线具有 trigger 或 pipeline 的流水线来源，因此 && $CI_PIPELINE_SOURCE == "push" 确保规则不会阻止触发的流水线。

Git Flow 与合并请求流水线

您可以使用 workflow: rules 与合并请求流水线。通过这些规则，您可以在保持支持多个软件版本的长期分支的同时，使用合并请求流水线功能与特性分支。

例如，仅为您的合并请求、标签和受保护分支运行流水线：

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_TAG
    - if: $CI_COMMIT_REF_PROTECTED == "true"

此示例假设您的长期分支是受保护的。

跳过草稿合并请求的流水线

您可以使用 workflow: rules 跳过草稿合并请求的流水线。通过这些规则，您可以避免在开发完成之前使用计算分钟。

例如，以下规则将禁用标题中包含 [Draft]、(Draft) 或 Draft: 的合并请求的 CI 构建：

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TITLE =~ /^(\[Draft\]|\(Draft\)|Draft:)/
      when: never

stages:
  - build

build-job:
  stage: build
  script:
    - echo "Testing"

`workflow:rules` 模板（已弃用）

workflow:rules 模板在极狐GitLab 17.0 中已被弃用，计划在 18.0 中删除。此更改是重大更改。要在您的流水线中配置 workflow:rules，请明确添加关键字。有关选项，请参见上面的示例。

极狐GitLab 提供了为常见场景设置 workflow: rules 的模板。这些模板有助于防止重复流水线。

Branch-Pipelines 模板使您的流水线为分支和标签运行。

分支流水线状态显示在使用分支作为来源的合并请求中。但是，此流水线类型不支持合并请求流水线提供的任何功能，例如合并结果流水线或合并列车。此模板故意避免这些功能。

要 include 它：

include:
  - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'

MergeRequest-Pipelines 模板使您的流水线为默认分支、标签和所有类型的合并请求流水线运行。如果您使用任何合并请求流水线功能，请使用此模板。

要 include 它：

include:
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'

故障排除

合并请求卡在 `Checking pipeline status.` 消息

如果合并请求显示 Checking pipeline status.，但消息从未消失（“旋转器”从未停止旋转），则可能是由于 workflow:rules 引起的。如果项目启用了 Pipelines must succeed，但 workflow:rules 阻止了合并请求的流水线运行，则可能会发生此问题。

例如，使用此工作流，合并请求无法合并，因为没有流水线可以运行：

workflow:
  rules:
    - changes:
        - .gitlab/**/**.md
      when: never

workflow:rules 的常用 if 子句

workflow: rules 示例