使用 API 来触发流水线

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

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

如果您正在迁移到极狐GitLab CI/CD，可以通过从其他提供商的作业中调用 API 端点来触发极狐GitLab CI/CD 流水线。例如，作为从 Jenkins 或 CircleCI 迁移的一部分。

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

流水线触发令牌通过流水线触发器 API 触发分支或标签流水线。
CI/CD 作业令牌来触发多项目流水线。
另一个具有 API 访问权限的令牌来使用项目流水线 API 端点创建新流水线。

创建流水线触发令牌#

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

先决条件：

您必须至少拥有项目的维护者角色。

要创建触发令牌：

在左侧边栏中，选择 搜索或转到 并找到您的项目。
选择 设置 > CI/CD。
展开 流水线触发令牌。
选择 添加新令牌。
输入描述并选择 创建流水线触发令牌。
- 您可以查看和复制您创建的所有触发器的完整令牌。
- 您只能看到其他项目成员创建的令牌的前 4 个字符。

在公共项目中以纯文本保存令牌或以恶意用户可以访问的方式存储它们是一种安全风险。泄露的触发令牌可能会被用来强制执行非计划的部署、尝试访问 CI/CD 变量或其他恶意用途。屏蔽 CI/CD 变量有助于提高触发令牌的安全性。有关保持令牌安全的更多信息，请参见安全注意事项。

触发流水线#

在您创建流水线触发令牌后，您可以使用可以访问 API 的工具或 webhook 来触发流水线。

使用 cURL#

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

使用多行 cURL 命令：

shell
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>：

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

在每个示例中，替换：

URL 为 https://gitlab.com 或您的实例的 URL。
<token> 为您的触发令牌。
<ref_name> 为分支或标签名称，例如 main。
<project_id> 为您的项目 ID，例如 123456。项目 ID 显示在项目概览页面上。

使用 CI/CD 作业#

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

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

yaml
1trigger_pipeline:
2  stage: deploy
3  script:
4    - 'curl --fail --request POST --form token=$MY_TRIGGER_TOKEN --form ref=main "${CI_API_V4_URL}/projects/123456/trigger/pipeline"'
5  rules:
6    - if: $CI_COMMIT_TAG
7  environment: production

在此示例中：

1234 是 project-B 的项目 ID。项目 ID 显示在项目概览页面上。
rules 使作业在每次向 project-A 添加标签时运行。
MY_TRIGGER_TOKEN 是一个包含触发令牌的屏蔽 CI/CD 变量。

使用 webhook#

要从另一个项目的 webhook 触发流水线，请使用以下 webhook URL 进行推送和标签事件：

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

替换：

URL 为 https://gitlab.com 或您的实例的 URL。
<project_id> 为您的项目 ID，例如 123456。项目 ID 显示在项目概览页面上。
<ref_name> 为分支或标签名称，例如 main。此值优先于 webhook 负载中的 ref_name。负载的 ref 是在源存储库中触发触发器的分支。如果 ref_name 包含斜杠，您必须对其进行 URL 编码。
<token> 为您的流水线触发令牌。

访问 webhook 负载#

如果您使用 webhook 触发流水线，您可以使用 TRIGGER_PAYLOAD 预定义的 CI/CD 变量访问 webhook 负载。负载以文件类型变量的形式暴露，因此您可以使用 cat $TRIGGER_PAYLOAD 或类似命令访问数据。

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

您可以在触发 API 调用中传递任意数量的 CI/CD 变量，尽管使用输入来控制流水线行为比 CI/CD 变量提供了更好的安全性和灵活性。

这些变量具有最高优先级，并覆盖所有具有相同名称的变量。

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

shell
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 变量显示在每个作业的页面上，但只有具有所有者和维护者角色的用户可以查看这些值。

作业变量在 UI 中

使用输入来控制流水线行为比 CI/CD 变量提供了更好的安全性和灵活性。

在 API 调用中传递流水线输入#

您可以在触发 API 调用中传递流水线输入。输入提供了一种结构化的方式来参数化您的流水线，并带有内置的验证和文档。

参数格式为 inputs[name]=value，例如：

shell
curl --request POST \
     --form token=TOKEN \
     --form ref=main \
     --form "inputs[environment]=production" \
     "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"

输入值根据您的流水线的 spec:inputs 部分中定义的类型和约束进行验证：

yaml
1spec:
2  inputs:
3    environment:
4      type: string
5      description: "Deployment environment"
6      options: [dev, staging, production]
7      default: dev

撤销流水线触发令牌#

要撤销流水线触发令牌：

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

撤销的触发令牌无法再次添加。

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

要配置作业何时运行在触发的流水线中，您可以：

使用 rules 与 $CI_PIPELINE_SOURCE 预定义的 CI/CD 变量。
使用 only/except 关键字，不过 rules 是首选关键字。

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

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

查看使用了哪个流水线触发令牌#

您可以通过访问单个作业页面查看哪个流水线触发令牌导致了作业运行。在右侧边栏的 作业详情 下方显示部分触发令牌。

在使用触发令牌触发的流水线中，作业在 Build > Jobs 中标记为 triggered。

故障排除#

使用 webhook 触发流水线时出现 403 Forbidden#

当您使用 webhook 触发流水线时，API 可能会返回 {"message":"403 Forbidden"} 响应。为了避免触发循环，请勿使用 pipeline events 来触发流水线。

触发流水线时出现 404 Not Found#

触发流水线时出现 {"message":"404 Not Found"} 响应可能是由于使用了个人访问令牌而非流水线触发令牌导致的。创建一个新的触发令牌并使用它替代个人访问令牌。

触发流水线时请求的 URL 返回错误：400#

如果您尝试使用不存在的分支名称 ref 触发流水线，极狐GitLab 会返回请求的 URL 返回错误：400。

例如，您可能在项目使用其他分支名称作为其默认分支时，不小心使用 main 作为分支名称。

此错误的另一个可能原因是一个规则，该规则在 CI_PIPELINE_SOURCE 值为 trigger 时阻止创建流水线，例如：

yaml
rules:
  - if: $CI_PIPELINE_SOURCE == "trigger"
    when: never

检查您的 workflow:rules 以确保在 CI_PIPELINE_SOURCE 值为 trigger 时可以创建流水线。