下游流水线

下游流水线是由另一个流水线触发的任何极狐GitLab CI/CD 流水线。 下游流水线可以是：

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

父子流水线和多项目流水线有时可用于类似目的，但存在一些关键差异。

父子流水线：

  • 在与父流水线相同的项目、ref 和提交 SHA 下运行。
  • 影响流水线运行的 ref 的整体状态。例如，如果主分支的流水线出现故障，通常会说“主分支已损坏”。子流水线的状态不会直接影响 ref 的状态，除非子流水线由 strategy:depend 触发。
  • 如果流水线配置为 interruptible，则在为同一 ref 创建新流水线时自动取消。
  • 在流水线索引页面中仅显示父流水线。子流水线在访问其父流水线页面时可见。
  • 仅限于 2 级嵌套。一个父流水线可以触发多个子流水线，而这些子流水线可以触发多个子流水线（A -> B -> C）。

多项目流水线：

  • 从另一个流水线触发，但上游（触发）流水线对下游（被触发）流水线没有太多控制。但是，它可以选择下游流水线的 ref，并将 CI/CD 变量传递给它。
  • 影响它运行的项目的 ref 的整体状态，但不影响触发流水线的 ref 的状态，除非用 strategy:depend。
  • 如果在上游流水线中为相同的 ref 运行新流水线，则在使用 interruptible 时不会在下游项目中自动取消。如果为下游项目上的相同 ref 触发了新流水线，它们可以自动取消。
  • 多项目流水线是独立流水线，因为它们是恰好由外部项目触发的正常流水线。它们都在流水线索引页面上可见。
  • 是独立的，因此没有嵌套限制。

多项目流水线

您可以跨多个项目设置极狐GitLab CI/CD，以便一个项目中的流水线可以触发另一个项目中的流水线。您可以在一个地方可视化整个流水线，包括所有跨项目的相互依赖关系。

例如，您可以从极狐GitLab 中的三个不同项目部署您的 Web 应用程序。 每个项目都有自己的构建、测试和部署过程。使用多项目流水线，您可以可视化整个流水线，包括所有三个项目的所有构建和测试阶段。

如果您在下游私有项目中触发流水线，在上游项目的流水线页面，您可以查看：

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

如果您的公共项目可以在私有项目中触发下游流水线，请确保不存在保密问题。

从 .gitlab-ci.yml 文件中的作业触发多项目流水线

当在您的 .gitlab-ci.yml 文件中创建一个多项目流水线时，创建了所谓的触发作业。例如： 

rspec:
  stage: test
  script: bundle exec rspec

staging:
  variables:
    ENVIRONMENT: staging
  stage: deploy
  trigger: my/deployment

在这个例子中，在 rspec 作业在 test 阶段成功后，staging 触发器作业开始。此作业的初始状态为 pending。

系统然后在 my/deployment 项目中创建一个下游流水线，一旦创建流水线，staging 作业就会成功。项目的完整路径是 my/deployment。

您可以查看流水线的状态，也可以显示下游流水线的状态。

创建上游流水线的用户也必须能够在下游项目（my/deployment）中创建流水线。如果未找到下游项目，或者用户没有在那里创建流水线的权限，则 staging 作业将标记为 failed。

指定下游流水线分支

您可以为要使用的下游流水线指定分支名称。极狐GitLab 使用分支头部的提交来创建下游流水线。 

rspec:
  stage: test
  script: bundle exec rspec

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

使用：

  • project 关键字指定下游项目的完整路径。15.3 及更高版本支持变量扩展。
  • branch 关键字用于指定由 project 指定的项目中的分支名称。12.4 及更高版本支持变量扩展。

在下游项目中的受保护分支上触发的流水线，使用在上游项目中运行触发器作业的用户的角色。如果用户无权针对受保护分支运行 CI/CD 流水线，则流水线将失败。请参阅受保护分支的流水线安全。

对多项目流水线使用 rules 或 only/except

对于多项目流水线，您可以使用 CI/CD 变量或 rules 关键字来控制作业行为。当使用 trigger 关键字触发下游流水线时，$CI_PIPELINE_SOURCE 预定义变量的值作为所有作业的 pipeline 值。

如果您使用 only/except 来控制作业行为，请使用 pipelines 关键字。

使用 API 触发多项目流水线

当您使用 CI_JOB_TOKEN 触发流水线 时，系统会识别作业令牌的来源。流水线变得相关，因此您可以在流水线图上可视化它们的关系。

这些关系通过显示上游和下游流水线依赖项的入站和出站连接显示在流水线图中。

使用时：

查看下游流水线

在流水线图视图中，下游流水线显示为图表右侧的卡片列表。

重试下游流水线

  • 从图表视图重试功能引入于 15.0 版本，功能标志为 downstream_retry_action。默认禁用。
  • 从图表视图重试功能一般可用于 15.1 版本。功能标志删除。

要重试已完成的下游流水线，请选择 重试 ()：

  • 从下游流水线的详细信息页面。
  • 在流水线图视图中的流水线卡上。

取消下游流水线

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

  • 从下游流水线的详细信息页面。
  • 在流水线图视图中的流水线卡上。

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

您可以使用 strategy:depend 将流水线从触发流水线镜像到源触发作业。例如： 

trigger_job:
  trigger:
    project: my/project
    strategy: depend

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

当您触发多项目流水线时，下游流水线会显示在流水线图的右侧。

Multi-project pipeline graph

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

Multi-project pipeline mini graph

将产物传递到下游流水线

您可以使用 needs:project 将产物传递到下游流水线。

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

  2. 使用触发作业触发下游流水线： 

    build_artifacts:
  stage: build
  script:
    - echo "This is a test artifact!" >> artifact.txt
  artifacts:
    paths:
      - artifact.txt

deploy:
  stage: deploy
  trigger: my/downstream_project

  3. 在下游流水线的作业中，使用 needs:project 从上游流水线获取产物。将 job 设置为上游流水线中的作业，从中获取产物，将 ref 设置为分支，并设置 artifacts: true。 

    test:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - project: my/upstream_project
      job: build_artifacts
      ref: main
      artifacts: true

从合并请求流水线传递产物

当您使用 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 流水线获取产物，请使用变量继承将此变量传递给下游流水线：

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

  2. 在触发下游流水线的作业中，使用变量继承传递 $CI_MERGE_REQUEST_REF_PATH 变量： 

    build_artifacts:
  stage: build
  script:
    - echo "This is a test artifact!" >> artifact.txt
  artifacts:
    paths:
      - artifact.txt

upstream_job:
  variables:
    UPSTREAM_REF: $CI_MERGE_REQUEST_REF_PATH
  trigger:
    project: my/downstream_project
    branch: my-branch

  3. 在下游流水线的作业中，使用 needs:project 从上游流水线获取产物。将 ref 设置为 UPSTREAM_REF 变量，并将 job 设置为上游流水线中的作业，以从以下位置获取产物： 

    test:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - project: my/upstream_project
      job: build_artifacts
      ref: UPSTREAM_REF
      artifacts: true

此方法适用于从常规合并请求父流水线获取产物，但不支持从合并结果流水线获取产物。

将 CI/CD 变量传递到下游流水线

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

传递 YAML 定义的 CI/CD 变量

您可以使用 variables 关键字将 CI/CD 变量传递到下游流水线，就像处理任何其他作业一样。

例如，在多项目流水线中： 

rspec:
  stage: test
  script: bundle exec rspec

staging:
  variables:
    ENVIRONMENT: staging
  stage: deploy
  trigger: my/deployment

ENVIRONMENT 变量被传递给下游流水线中定义的每个作业。当极狐GitLab Runner 选择作业时，它可以作为变量使用。

在以下配置中，MY_VARIABLE 变量被传递到在 trigger-downstream 作业排队时创建的下游流水线。这是因为 trigger-downstream 作业继承了全局变量块中声明的变量，然后我们将这些变量传递给下游流水线。 

variables:
  MY_VARIABLE: my-value

trigger-downstream:
  variables:
    ENVIRONMENT: something
  trigger: my/project

防止全局变量被传递

您可以使用 inherit:variables 关键字阻止全局变量到达下游流水线。 例如，在多项目流水线中： 

variables:
  MY_GLOBAL_VAR: value

trigger-downstream:
  inherit:
    variables: false
  variables:
    MY_LOCAL_VAR: value
  trigger: my/project

在此示例中，MY_GLOBAL_VAR 变量在触发流水线中不可用。

传递一个预定义的变量

您可能希望使用预定义的变量传递有关上游流水线的一些信息。 为此，您可以使用插值来传递任何变量。例如，在多项目流水线中： 

downstream-job:
  variables:
    UPSTREAM_BRANCH: $CI_COMMIT_REF_NAME
  trigger: my/project

在这种情况下，具有上游流水线 $CI_COMMIT_REF_NAME 值的 UPSTREAM_BRANCH 变量被传递给 downstream-job。它在所有下游构建的上下文中可用。

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

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

传递作业中创建的 dotenv 变量

您可以使用 dotenv 变量继承 和 needs:project。

例如，在多项目流水线中：

  1. 将变量保存在 .env 文件中。
  2. 将 .env 文件保存为 dotenv 报告。

  3. 触发下游流水线。 

    build_vars:
  stage: build
  script:
    - echo "BUILD_VERSION=hello" >> build.env
  artifacts:
    reports:
      dotenv: build.env

deploy:
  stage: deploy
  trigger: my/downstream_project

  4. 在下游流水线中设置 test 作业以从具有 needs 的上游项目中的 build_vars 作业继承变量。test 作业继承了 dotenv 报告中的变量，它可以访问脚本中的 BUILD_VERSION： 

    test:
  stage: test
  script:
    - echo $BUILD_VERSION
  needs:
    - project: my/upstream_project
      job: build_vars
      ref: master
      artifacts: true