使用 API 触发流水线

要为特定分支或标签触发流水线，您可以使用对流水线触发器 API 端点的 API 调用。

使用 API 进行身份验证时，您可以使用：

创建触发器令牌

您可以通过生成触发器令牌，并使用它来验证 API 调用来触发分支或标签的流水线。令牌模拟用户的项目访问和权限。

先决条件：

  • 您必须至少具有该项目的维护者角色。

创建触发器令牌：

  1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
  2. 在左侧边栏中，选择 设置 > CI/CD。
  3. 展开 流水线触发器。
  4. 输入描述并选择 添加触发器。
    • 您可以查看和复制您创建的所有触发器的完整令牌。
    • 您只能看到其他项目成员创建的令牌的前 4 个字符。
caution 在公共项目中以纯文本形式保存令牌存在安全风险。潜在的攻击者可以使用在 .gitlab-ci.yml 文件中公开的触发器令牌来模拟创建令牌的用户。使用隐藏 CI/CD 变量来提高触发器令牌的安全性。

触发流水线

在您创建一个触发器令牌之后，您可以使用它，通过一个可以访问 API 的工具或一个 Webhook 来触发流水线。

使用 cURL

您可以使用 cURL 通过流水线触发器 API 端点来触发流水线。 例如：

  • 使用多行 cURL 命令：

    curl --request POST \
     --form token=<token> \
     --form ref=<ref_name> \
     "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline"

  • 使用 cURL 并在查询字符串中传递 <token> 和 <ref_name>：

    curl --request POST \
    "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>"

在示例中，替换：

  • 使用您的实例的 URL。
  • <token>：使用您的触发器令牌。
  • <ref_name>：分支或标签名称，如 main。
  • <project_id>：您的项目 ID，比如 123456。项目 ID 显示在每个项目的登录页面的顶部。

使用 CI/CD 作业

您可以使用带有触发器令牌的 CI/CD 作业，在另一个流水线运行时触发流水线。

例如，要在 project-A 中创建标签时，触发 project-B 的 main 分支上的流水线，请将以下作业添加到项目 A 的 .gitlab-ci.yml 文件中：

trigger_pipeline:
  stage: deploy
  script:
    - 'curl --fail --request POST --form token=$MY_TRIGGER_TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"'
  rules:
    - if: $CI_COMMIT_TAG
  environment: production

在此例中：

  • 1234 是 project-B 的项目 ID。项目 ID 显示在每个项目的登录页面的顶部。
  • rules 导致作业在每次将标签添加到 project-A 时运行。
  • MY_TRIGGER_TOKEN 是一个隐藏 CI/CD 变量，包含触发器令牌。

使用 Webhook

要从另一个项目的 Webhook 触发流水线，请对推送和标签事件使用如下所示的 Webhook URL：

https://gitlab.example.com/api/v4/projects/<project_id>/ref/<ref_name>/trigger/pipeline?token=<token>

在示例中，替换：

  • 使用您的实例的 URL。
  • <project_id>：您的项目 ID，比如 123456。项目 ID 显示在每个项目的登录页面的顶部。
  • <ref_name> 带有分支或标签名称，例如 main。此值优先于 Webhook 有效负载中的 ref_name。有效负载的 ref 是在源仓库中触发触发器的分支。如果 ref_name 包含斜杠，则必须对其进行 URL 编码。
  • <token> 与您的触发令牌。

使用 Webhook 负载

  • 引入于 13.9 版本。
  • 功能标志移除于 13.11 版本。

如果您使用 Webhook 触发流水线，则可以使用 TRIGGER_PAYLOAD 预定义 CI/CD 变量 访问 Webhook 负载。 负载作为文件类型变量公开，因此您可以使用 cat $TRIGGER_PAYLOAD 或类似命令访问数据。

在 API 调用中传递 CI/CD 变量

您可以在触发器 API 调用中传递任意数量的 CI/CD 变量。 这些变量具有最高优先级，并覆盖所有具有相同名称的变量。

参数的形式为 variables[key]=value，例如：

curl --request POST \
  --form token=TOKEN \
  --form ref=main \
  --form "variables[UPLOAD_TO_S3]=true" \
  "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"

触发流水线中的 CI/CD 变量显示在每个作业的页面上，但只有拥有所有者和维护者角色的用户才能查看这些值。

Job variables in UI

撤销触发器令牌

撤销触发器令牌：

  1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
  2. 在左侧边栏中，选择 设置 > CI/CD。
  3. 展开 流水线触发器。
  4. 在要撤销的触发器令牌的左侧，选择 撤销 ( )。

被撤销的触发器令牌不能被添加回来。

配置 CI/CD 作业以在触发的流水线中运行

在触发的流水线中配置何时运行作业：

$CI_PIPELINE_SOURCE 值 only/except 关键字 触发方式
trigger triggers 在使用触发器令牌，并由流水线触发 API 触发的流水线中。
pipeline pipelines 在多项目流水线中使用流水线触发器 API 触发，并在 CI/CD 配置文件通过$CI_JOB_TOKEN，或使用 trigger 关键字。

此外，$CI_PIPELINE_TRIGGERED 预定义的 CI/CD 变量在由触发器令牌触发的流水线中设置为 true。

查看使用了哪个触发器令牌

您可以通过访问单个作业页面来查看哪个触发器导致作业运行。 触发器令牌的一部分显示在页面右侧的作业详细信息下方：

Marked as triggered on a single job page

在使用触发器令牌触发的流水线中，作业在 构建 > 作业 中被标记为 triggered。

故障排查

触发流水线时 404 not found

触发流水线时 {"message":"404 Not Found"} 的响应可能是由于使用个人访问令牌引起的，而不是触发器令牌。创建新的触发器令牌 并使用它代替个人访问令牌。

触发流水线时 The requested URL returned error: 400

如果您尝试使用不存在的分支名称 ref 来触发流水线，极狐GitLab 将返回 The requested URL returned error: 400。

例如，您可能不小心在一个项目中使用了 main 作为分支名称，而该项目的默认分支使用了不同的分支名称。