极狐 GitLab

下游流水线

Tier: 基础版,专业版,旗舰版

Offering: JihuLab.com,私有化部署

下游流水线是指由另一条流水线触发的任何极狐GitLab CI/CD 流水线。下游流水线独立于触发它们的上游流水线并发运行。

  • 父子流水线是在与第一条流水线相同的项目中触发的下游流水线。
  • 多项目流水线是在与第一条流水线不同的项目中触发的下游流水线。

有时您可以将父子流水线和多项目流水线用于类似目的,但它们之间存在关键差异。

默认情况下,一条流水线层级最多可包含 1000 条下游流水线。有关此限制及如何更改的更多信息,请参阅限制流水线层级大小。

父子流水线#

父流水线是在同一项目中触发下游流水线的流水线。该下游流水线称为子流水线。

子流水线:

  • 与父流水线在相同的项目、ref 和提交 SHA 下运行。
  • 不会直接影响流水线所针对 ref 的整体状态。例如, 如果主分支的流水线失败,通常会说“主分支已损坏”。 子流水线的状态只有在子流水线通过 trigger:strategy 触发时才会影响 ref 的状态。
  • 如果流水线配置了 interruptible,当为同一 ref 创建新流水线时,会自动取消。
  • 不会显示在项目的流水线列表中。您只能在父流水线的详情页上查看子流水线。

嵌套子流水线#

父流水线和子流水线最多只能有两层子流水线。

父流水线可以触发多个子流水线,这些子流水线也可以触发它们自己的子流水线。您不能再触发下一层子流水线。

多项目流水线#

一个项目中的流水线可以触发另一个项目中的下游流水线,称为多项目流水线。触发上游流水线的用户必须有权在下游项目中启动流水线,否则下游流水线将无法启动。

多项目流水线:

  • 由另一个项目的流水线触发,但上游(触发方)流水线对下游(被触发方)流水线没有太多控制权。不过,它可以选择下游流水线的 ref,并向其传递 CI/CD 变量。
  • 会影响其运行所在项目 ref 的整体状态,但不会影响触发方流水线的 ref 状态,除非它是通过 trigger:strategy 触发的。
  • 当上游流水线中为同一 ref 运行新流水线时,使用 interruptible 不会在下游项目中自动取消。如果在下游项目上为同一 ref 触发新流水线,则它们可以自动取消。
  • 在下游项目的流水线列表中可见。
  • 相互独立,因此没有嵌套限制。

如果您使用公开项目触发私有项目中的下游流水线,请确保不存在保密性问题。上游项目的流水线页面始终显示:

  • 下游项目的名称。
  • 流水线的状态。

从 .gitlab-ci.yml 文件中的作业触发下游流水线#

在您的 .gitlab-ci.yml 文件中使用 trigger 关键字来创建触发下游流水线的作业。此作业称为触发作业。

例如:

yaml
trigger_job: trigger: include: - local: path/to/child-pipeline.yml

触发作业启动后,当极狐GitLab 尝试创建下游流水线时,作业的初始状态为 pending。如果下游流水线创建成功,触发作业显示 passed,否则显示 failed。或者,您可以将触发作业设置为显示下游流水线的状态。

触发作业不使用 Runner,因此长时间处于 pending 状态的触发作业通常意味着极狐GitLab 无法创建下游流水线。有关故障排除步骤,请参阅下游流水线故障排除。

使用 rules 控制下游流水线作业#

使用 CI/CD 变量或 rules 关键字来控制作业行为(在下游流水线中)。

当您使用 trigger 关键字触发下游流水线时,所有作业的 $CI_PIPELINE_SOURCE 预定义变量的值为:

  • 多项目流水线为 pipeline。
  • 父子流水线为 parent_pipeline。

例如,要在同时运行合并请求流水线的项目中控制多项目流水线中的作业:

yaml
1job1: 2 rules: 3 - if: $CI_PIPELINE_SOURCE == "pipeline" 4 script: echo "This job runs in multi-project pipelines only" 5 6job2: 7 rules: 8 - if: $CI_PIPELINE_SOURCE == "merge_request_event" 9 script: echo "This job runs in merge request pipelines only" 10 11job3: 12 rules: 13 - if: $CI_PIPELINE_SOURCE == "pipeline" 14 - if: $CI_PIPELINE_SOURCE == "merge_request_event" 15 script: echo "This job runs in both multi-project and merge request pipelines"

在不同项目中使用子流水线配置文件#

您可以在触发作业中使用 include:project 来使用不同项目中的配置文件触发子流水线:

yaml
1microservice_a: 2 trigger: 3 include: 4 - project: 'my-group/my-pipeline-library' 5 ref: 'main' 6 file: '/path/to/child-pipeline.yml'

合并多个子流水线配置文件#

定义子流水线时,最多可以包含三个配置文件。子流水线的配置由所有合并在一起的配置文件组成:

yaml
1microservice_a: 2 trigger: 3 include: 4 - local: path/to/microservice_a.yml 5 - template: Jobs/SAST.gitlab-ci.yml 6 - project: 'my-group/my-pipeline-library' 7 ref: 'main' 8 file: '/path/to/child-pipeline.yml'

动态子流水线#

您可以从作业中生成的 YAML 文件触发子流水线,而不是使用保存在项目中的静态文件。这种技术对于生成针对已更改内容的流水线或构建目标与架构矩阵非常强大。

包含生成的 YAML 文件的产物必须在实例限制之内。

触发动态子流水线#

要从动态生成的配置文件触发子流水线:

  1. 在作业中生成配置文件,并将其保存为产物:

    yaml
    1generate-config: 2 stage: build 3 script: generate-ci-config > generated-config.yml 4 artifacts: 5 paths: 6 - generated-config.yml
  2. 将触发作业配置为在生成配置文件的作业之后运行。 将 include: artifact 设置为生成的产物,并将 include: job 设置为创建该产物的作业:

    yaml
    1child-pipeline: 2 stage: test 3 trigger: 4 include: 5 - artifact: generated-config.yml 6 job: generate-config

在此示例中,极狐GitLab 检索 generated-config.yml,并使用该文件中的 CI/CD 配置触发子流水线。

产物路径由极狐GitLab 解析,而不是由 Runner 解析,因此该路径必须与运行极狐GitLab 的操作系统语法匹配。如果极狐GitLab 在 Linux 上运行,但使用 Windows Runner 进行测试,则触发作业的路径分隔符为 /。使用 Windows Runner 的作业的其他 CI/CD 配置(如脚本)使用 \。

您不能在动态子流水线配置的 include 部分中使用 CI/CD 变量。

使用合并请求流水线运行子流水线#

当不使用 rules 或 workflow:rules 时,流水线(包括子流水线)默认作为分支流水线运行。要将子流水线配置为在从合并请求(父)流水线触发时运行,请使用 rules 或 workflow:rules。例如,使用 rules:

  1. 将父流水线的触发作业设置为在合并请求上运行:

    yaml
    trigger-child-pipeline-job: trigger: include: path/to/child-pipeline-configuration.yml rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  2. 使用 rules 将子流水线作业配置为在由父流水线触发时运行:

    yaml
    1job1: 2 script: echo "This child pipeline job runs any time the parent pipeline triggers it." 3 rules: 4 - if: $CI_PIPELINE_SOURCE == "parent_pipeline" 5 6job2: 7 script: echo "This child pipeline job runs only when the parent pipeline is a merge request pipeline" 8 rules: 9 - if: $CI_MERGE_REQUEST_ID

在子流水线中,$CI_PIPELINE_SOURCE的值始终为 parent_pipeline,因此:

  • 您可以使用 if: $CI_PIPELINE_SOURCE == "parent_pipeline" 来确保子流水线作业始终运行。
  • 您不能使用 if: $CI_PIPELINE_SOURCE == "merge_request_event" 来配置子流水线作业为合并请求流水线运行。相反,请使用 if: $CI_MERGE_REQUEST_ID 将子流水线作业设置为仅在父流水线是合并请求流水线时运行。父流水线的 CI_MERGE_REQUEST_* 预定义变量会传递给子流水线作业。

为多项目流水线指定分支#

触发多项目流水线时,您可以指定要使用的分支。极狐GitLab 使用分支头部的提交来创建下游流水线。例如:

yaml
staging: stage: deploy trigger: project: my/deployment branch: stable-11-2

使用:

  • project 关键字指定下游项目的完整路径。 您可以使用变量扩展。
  • branch 关键字指定由 project 指定的项目中的分支或标签名称。您可以使用变量扩展。

使用 API 触发多项目流水线#

您可以在 CI/CD 作业内部使用 CI/CD 作业令牌(CI_JOB_TOKEN)和流水线触发令牌 API 端点来触发多项目流水线。极狐GitLab 会将使用作业令牌触发的流水线设置为包含发起 API 调用的作业的流水线的下游流水线。

例如:

yaml
1trigger_pipeline: 2 stage: deploy 3 script: 4 - | 5 curl --request POST \ 6 --form "token=$CI_JOB_TOKEN" \ 7 --form ref=main \ 8 --url "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" 9 rules: 10 - if: $CI_COMMIT_TAG 11 environment: production

查看下游流水线#

在流水线详情页中,下游流水线以卡片列表的形式显示在图表的右侧。在此视图中,您可以:

  • 选择触发作业以查看被触发的下游流水线的作业。
  • 在流水线卡片上选择展开作业 ,以展开视图显示下游流水线的作业。您一次只能查看一条下游流水线。
  • 将鼠标悬停在流水线卡片上,以高亮显示触发下游流水线的作业。

重试下游流水线中失败和已取消的作业#

要重试失败和已取消的作业,请选择重试():

  • 从下游流水线的详情页。
  • 在流水线图表视图中流水线的卡片上。

重新创建下游流水线#

您可以通过重试其对应的触发作业来重新创建下游流水线。新创建的下游流水线会替换流水线图表中的当前下游流水线。

要重新创建下游流水线:

  • 在流水线图谱视图中,选择触发作业卡片上的再次运行()。

取消下游流水线#

要取消仍在运行的下游流水线,请选择取消():

  • 从下游流水线的详情页。
  • 在流水线图表视图中流水线的卡片上。

从下游流水线自动取消父流水线#

您可以将子流水线配置为在其某个作业失败时立即自动取消。

只有在以下情况下,父流水线才会在子流水线中的作业失败时自动取消:

  • 父流水线也设置为在作业失败时自动取消。
  • 触发作业配置了 strategy: mirror。

例如:

  • .gitlab-ci.yml的内容:

    yaml
    1workflow: 2 auto_cancel: 3 on_job_failure: all 4 5trigger_job: 6 trigger: 7 include: child-pipeline.yml 8 strategy: mirror 9 10job3: 11 script: 12 - sleep 120
  • child-pipeline.yml的内容

    yaml
    1# Contents of child-pipeline.yml 2workflow: 3 auto_cancel: 4 on_job_failure: all 5 6job1: 7 script: sleep 60 8 9job2: 10 script: 11 - sleep 30 12 - exit 1

在此示例中:

  1. 父流水线同时触发子流水线和 job3
  2. 子流水线中的 job2 失败,子流水线被取消,同时停止 job1
  3. 子流水线已被取消,因此父流水线被自动取消

在触发作业中镜像下游流水线的状态#

您可以使用 trigger: strategy 在触发作业中镜像下游流水线的状态:

使用 strategy: mirror 时,触发作业始终具有与下游流水线相同的状态。

yaml
trigger_job: trigger: include: - local: path/to/child-pipeline.yml strategy: mirror

不建议使用 strategy: depend,因为触发作业的状态并不总是与下游流水线的状态匹配。请参阅 trigger:strategy 参考中的其他详细信息。

在流水线图表中查看多项目流水线#

触发多项目流水线后,下游流水线会显示在流水线图表的右侧。

在流水线迷你图表中,下游流水线显示在迷你图表的右侧。

在合并请求中查看子流水线报告#

您可以在合并请求小部件中查看和下载子流水线的报告。这提供了跨流水线层级的测试结果和质量检查的统一视图,无需手动浏览多条流水线来识别失败和漏洞。

支持来自子流水线的以下报告类型:

  • 单元测试报告(JUnit)
  • 代码质量报告
  • Terraform 报告
  • 指标报告
  • 安全报告(SAST、密钥检测、依赖扫描、容器扫描、DAST、API 模糊测试)

安全报告适用于来自同一项目的子流水线、动态生成的子流水线以及由流水线执行策略创建的流水线。不支持来自扫描执行策略的报告。

来自子流水线的测试结果和安全发现也会出现在父流水线的测试和安全选项卡中。

子流水线的安全发现可以触发合并请求审批策略。如果子流水线检测到漏洞,您可能需要额外的审批才能合并。

为确保子流水线的报告出现在合并请求小部件中,请为生成产物报告的子流水线使用 strategy: depend 或 strategy: mirror。例如:

yaml
1test-backend: 2 trigger: 3 include: backend-tests.yml 4 strategy: depend 5 6test-frontend: 7 trigger: 8 include: frontend-tests.yml 9 strategy: depend

如果不使用这些策略,父流水线会在子流水线完成之前完成,并且它们的报告不会出现在合并请求中。

从上游流水线获取产物#

Tier: 专业版,旗舰版

Offering: JihuLab.com,私有化部署

使用 needs:pipeline:job 从上游流水线获取产物:

  1. 在上游流水线中,使用 artifacts 关键字将产物保存在作业中,然后使用触发作业触发下游流水线:

    yaml
    1build_artifacts: 2 stage: build 3 script: 4 - echo "This is a test artifact!" >> artifact.txt 5 artifacts: 6 paths: 7 - artifact.txt 8 9deploy: 10 stage: deploy 11 trigger: 12 include: 13 - local: path/to/child-pipeline.yml 14 variables: 15 PARENT_PIPELINE_ID: $CI_PIPELINE_ID
  2. 在下游流水线的作业中使用 needs:pipeline:job 来获取成功作业的产物。

    yaml
    1test: 2 stage: test 3 script: 4 - cat artifact.txt 5 needs: 6 - pipeline: $PARENT_PIPELINE_ID 7 job: build_artifacts

    将 job 设置为上游流水线中创建产物的作业。

请确保上游作业在下游作业开始之前完成,否则您将无法获取产物。 使用 needs 让下游作业等待上游作业。 有关更多信息,请参阅议题 356016。

从上游合并请求流水线获取产物#

当您使用 needs:project 将产物传递给下游流水线时,ref的值通常是分支名称,如 main 或 development。

对于合并请求流水线,ref 值的格式为 refs/merge-requests/<id>/head,其中 id 是合并请求 ID。您可以使用 CI_MERGE_REQUEST_REF_PATH CI/CD 变量检索此 ref。请勿将分支名称用作 ref 与合并请求流水线一起使用,因为下游流水线会尝试从最新的分支流水线获取产物。

先决条件:

  • 下游项目已添加到上游项目的作业令牌范围允许名单中。
  • 触发下游流水线的用户在上游项目中至少具有报告者角色。 将项目添加到允许名单并不会授予此访问权限。

要从上游 merge request 流水线而不是 branch 流水线获取产物,请使用变量继承将 CI_MERGE_REQUEST_REF_PATH 传递给下游流水线:

  1. 在上游流水线的作业中,使用 artifacts 关键字保存产物。

  2. 在触发下游流水线的作业中,传递 $CI_MERGE_REQUEST_REF_PATH 变量:

    yaml
    1build_artifacts: 2 rules: 3 - if: $CI_PIPELINE_SOURCE == 'merge_request_event' 4 stage: build 5 script: 6 - echo "This is a test artifact!" >> artifact.txt 7 artifacts: 8 paths: 9 - artifact.txt 10 11upstream_job: 12 rules: 13 - if: $CI_PIPELINE_SOURCE == 'merge_request_event' 14 variables: 15 UPSTREAM_REF: $CI_MERGE_REQUEST_REF_PATH 16 trigger: 17 project: my/downstream_project 18 branch: my-branch
  3. 在下游流水线的作业中,使用 needs:project 和传递的变量作为 ref 来从上游流水线获取产物:

    yaml
    1test: 2 stage: test 3 script: 4 - cat artifact.txt 5 needs: 6 - project: my/upstream_project 7 job: build_artifacts 8 ref: $UPSTREAM_REF 9 artifacts: true

您可以使用此方法从上游合并请求流水线获取产物,但不能从合并结果流水线获取。

向下游流水线传递输入#

您可以使用 inputs 关键字向下游流水线传递输入值。与变量相比,输入具有类型检查、通过选项进行验证、描述和默认值等优势。

首先,使用 spec:inputs 在目标配置文件中定义输入参数:

yaml
1# Target pipeline configuration 2spec: 3 inputs: 4 environment: 5 description: "Deployment environment" 6 options: [staging, production] 7 version: 8 type: string 9 description: "Application version"

然后在触发流水线时提供值:

yaml
1staging: 2 trigger: 3 include: 4 - local: path/to/child-pipeline.yml 5 inputs: 6 environment: staging 7 version: "1.0.0"

向下游流水线传递 CI/CD 变量#

您可以根据变量的创建或定义位置,使用几种不同的方法将 CI/CD 变量传递给下游流水线。

传递 YAML 定义的 CI/CD 变量#

对于流水线配置,建议使用输入而不是变量,因为它们提供了更高的安全性和灵活性。

您可以使用 variables 关键字将 CI/CD 变量传递给下游流水线。这些变量在变量优先级中属于流水线变量。

例如:

yaml
1variables: 2 VERSION: "1.0.0" 3 4staging: 5 variables: 6 ENVIRONMENT: staging 7 stage: deploy 8 trigger: 9 include: 10 - local: path/to/child-pipeline.yml

ENVIRONMENT 变量在下游流水线中定义的每个作业中都可用。

VERSION 默认变量在下游流水线中也可用,因为流水线中的所有作业(包括触发作业)都会继承默认 variables。

阻止传递默认变量#

您可以使用 inherit:variables 阻止默认 CI/CD 变量传递到下游流水线。您可以列出要继承的特定变量,或阻止所有默认变量。

例如:

yaml
1variables: 2 DEFAULT_VAR: value 3 4trigger-job: 5 inherit: 6 variables: false 7 variables: 8 JOB_VAR: value 9 trigger: 10 include: 11 - local: path/to/child-pipeline.yml

DEFAULT_VAR 变量在被触发的流水线中不可用,但 JOB_VAR 可用。

传递预定义变量#

要使用预定义 CI/CD 变量传递有关上游流水线的信息,请使用插值。将预定义变量保存为触发作业中的新作业变量,该变量会传递给下游流水线。例如:

yaml
1trigger-job: 2 variables: 3 PARENT_BRANCH: $CI_COMMIT_REF_NAME 4 trigger: 5 include: 6 - local: path/to/child-pipeline.yml

UPSTREAM_BRANCH 变量包含上游流水线的 $CI_COMMIT_REF_NAME 预定义 CI/CD 变量的值,该变量在下游流水线中可用。

请勿使用此方法将掩码变量传递给多项目流水线。CI/CD 掩码配置不会传递给下游流水线,并且该变量可能会在下游项目的作业日志中取消掩码。

您不能使用此方法将仅作业变量转发到下游流水线,因为它们在触发作业中不可用。

上游流水线优先于下游流水线。如果上游和下游项目中定义了两个同名变量,则在上游项目中定义的变量优先。

传递作业中创建的 dotenv 变量#

您可以通过 dotenv 变量继承将变量传递给下游流水线。

有关更多信息,请参阅将变量传递给下游流水线。

控制转发到下游流水线的变量类型#

使用 trigger:forward 关键字指定要转发到下游流水线的变量类型。转发的变量被视为触发变量,具有最高优先级。

用于部署的下游流水线#

您可以将 environment 关键字与 trigger 一起使用。如果您的部署项目和应用项目是分开管理的,您可能希望在触发作业中使用 environment。

yaml
deploy: trigger: project: project-group/my-downstream-project environment: production

下游流水线可以预配基础设施、部署到指定环境,并将部署状态返回给上游项目。

您可以从上游项目查看环境和部署。

高级示例#

此示例配置具有以下行为:

  • 上游项目根据分支名称动态组合环境名称。
  • 上游项目使用 UPSTREAM_* 变量将部署上下文传递给下游项目。

上游项目中的 .gitlab-ci.yml:

yaml
1stages: 2 - deploy 3 - cleanup 4 5.downstream-deployment-pipeline: 6 variables: 7 UPSTREAM_PROJECT_ID: $CI_PROJECT_ID 8 UPSTREAM_ENVIRONMENT_NAME: $CI_ENVIRONMENT_NAME 9 UPSTREAM_ENVIRONMENT_ACTION: $CI_ENVIRONMENT_ACTION 10 trigger: 11 project: project-group/deployment-project 12 branch: main 13 strategy: mirror 14 15deploy-review: 16 stage: deploy 17 extends: .downstream-deployment-pipeline 18 environment: 19 name: review/$CI_COMMIT_REF_SLUG 20 on_stop: stop-review 21 22stop-review: 23 stage: cleanup 24 extends: .downstream-deployment-pipeline 25 environment: 26 name: review/$CI_COMMIT_REF_SLUG 27 action: stop 28 when: manual

下游项目中的 .gitlab-ci.yml:

yaml
1deploy: 2 script: echo "Deploy to ${UPSTREAM_ENVIRONMENT_NAME} for ${UPSTREAM_PROJECT_ID}" 3 rules: 4 - if: $CI_PIPELINE_SOURCE == "pipeline" && $UPSTREAM_ENVIRONMENT_ACTION == "start" 5 6stop: 7 script: echo "Stop ${UPSTREAM_ENVIRONMENT_NAME} for ${UPSTREAM_PROJECT_ID}" 8 rules: 9 - if: $CI_PIPELINE_SOURCE == "pipeline" && $UPSTREAM_ENVIRONMENT_ACTION == "stop"