Help us learn about your current experience with the documentation. Take the survey.

使用 API 触发流水线

层级：免费、专业、旗舰
产品：GitLab.com、GitLab 自管版、GitLab 专属版

要为特定分支或标签触发流水线，您可以调用 pipeline triggers API endpoint 的 API。

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

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

流水线触发令牌通过 pipeline triggers API endpoint 来触发分支或标签流水线。
CI/CD 作业令牌来触发多项目流水线。
其他具有 API 访问权限的令牌通过 project pipeline API endpoint 来创建新的流水线。

创建流水线触发令牌

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

前置条件：

您必须至少拥有该项目的 Maintainer 角色。

要创建触发令牌：

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

在公开项目中以纯文本形式保存令牌，或以恶意用户可能访问到的方式存储令牌，存在安全风险。泄露的触发令牌可能被用于强制进行计划外的部署、尝试访问 CI/CD 变量或进行其他恶意活动。隐藏的 CI/CD 变量有助于提高触发令牌的安全性。关于保持令牌安全的更多信息，请参阅安全注意事项。

触发流水线

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

使用 cURL

您可以使用 cURL 通过 pipeline triggers API endpoint 来触发流水线。例如：

使用多行 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 替换为 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 文件中：

trigger_pipeline:
  stage: deploy
  script:
    - 'curl --fail --request POST --form token=$MY_TRIGGER_TOKEN --form ref=main "${CI_API_V4_URL}/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 替换为 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，例如：

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 变量会显示在每个作业的页面上，但只有 Owner 和 Maintainer 角色的用户才能查看其值。

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

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

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

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

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 部分中定义的类型和约束进行验证：

spec:
  inputs:
    environment:
      type: string
      description: "Deployment environment"
      options: [dev, staging, production]
      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`	在通过使用 `$CI_JOB_TOKEN` 由 pipeline triggers API 触发的多项目流水线中，或通过在 CI/CD 配置文件中使用 `trigger` 关键字触发的流水线中。

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

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

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

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

故障排查

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

当您使用 Webhook 触发流水线时，API 可能会返回 {"message":"403 Forbidden"} 响应。为避免触发循环，请不要使用流水线事件来触发流水线。

触发流水线时出现 404 Not Found

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

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

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

例如，您可能在一个使用不同名称作为默认分支的项目中，错误地将 main 用作了分支名称。

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

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

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