Triggering pipelines through the API

原文：https://docs.gitlab.com/ee/ci/triggers/README.html

Triggering pipelines through the API

版本历史

注意事项 ：

触发器可用于通过 API 调用强制重新运行特定ref （分支或标签）的管道.

Authentication tokens

支持以下身份验证方法：

如果使用$CI_PIPELINE_SOURCE 预定义环境变量来限制在管道中运行的作业，则值可以是pipeline或trigger ，具体取决于所使用的触发器方法.

$CI_PIPELINE_SOURCE value 触发方式
pipeline 使用 CI / CD 配置文件中的trigger:关键字，或将触发器 API 与$CI_JOB_TOKEN .
trigger 使用生成的触发令牌使用触发 API

当使用pipelines或使用only/except传统only/except基本语法only/except triggers关键字时，这也适用.

Trigger token

A unique trigger token can be obtained when adding a new trigger.

危险：在公共项目中传递纯文本令牌是一个安全问题. 潜在的攻击者可以在.gitlab-ci.yml文件中假冒公开暴露其触发令牌的用户. 使用变量来保护触发令牌.

CI job token

You can use the CI_JOB_TOKEN variable (used to authenticate with the GitLab Container Registry) in the following cases.

When used with multi-project pipelines

版本历史

  • 在GitLab Premium 9.3 中引入了CI_JOB_TOKEN在多项目管道中的使用.
  • 在 GitLab 12.4 的所有层中都可以将CI_JOB_TOKEN用于多项目管道.

这种触发方式只能在.gitlab-ci.yml内部调用时使用，并且会在管道图上创建可见的依赖管道关系. 例如：

  1. build_docs:
  2.   stage: deploy
  3.   script:
  4.     - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
  5.   only:
  6.     - tags

以这种方式触发的管道还公开了一个特殊变量： CI_PIPELINE_SOURCE=pipeline .

阅读有关管道触发器 API 的更多信息.

When a pipeline depends on the artifacts of another pipeline

在GitLab Premium 9.5 中引入了在工件下载 API 中使用CI_JOB_TOKEN .

随着不同项目之间的依赖关系的引入，其中一个项目可能需要访问由前一个项目创建的工件. 必须为授权访问授予此过程，并且可以使用标识特定作业的CI_JOB_TOKEN变量完成此过程. 例如：

  1. build_submodule:
  2.   image: debian
  3.   stage: test
  4.   script:
  5.     - apt update && apt install -y unzip
  6.     - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"
  7.     - unzip artifacts.zip
  8.   only:
  9.     - tags

这使您可以将其用于多项目管道，并从您有权访问的任何项目下载工件，因为这遵循与权限模型相同的原则.

了解有关Jobs API 的更多信息.

Adding a new trigger

您可以通过在”触发器”下转到项目的“设置”➔CI / CD来添加新触发器 . 添加触发器按钮将创建一个新令牌，然后您可以使用该令牌来触发此特定项目管道的重新运行.

您创建的每个新触发器都会被分配一个不同的令牌，然后您可以在脚本或.gitlab-ci.yml使用该令牌. 您还可以很好地了解上一次使用触发器的时间.

Triggers page overview

Revoking a trigger

您可以随时通过单击” 触发器”下项目的“设置”➔CI / CD并单击” 撤消”按钮来撤消 触发器 . 动作是不可逆的.

Triggering a pipeline

Notes:

  • 有效的引用只是分支和标签. 如果通过提交 SHA 作为参考，它将不会触发作业.

要触发作业，您需要向 gitLab 的 API 端点发送POST请求：

  1. POST /projects/:id/trigger/pipeline

必需的参数是触发器的token和将在其上执行触发器的 Git ref . 有效的引用是分支和标签. 可以通过查询 API或访问CI / CD设置页面（提供不言自明的示例）来找到项目的:id .

触发管道的重新运行时，该信息会在 GitLab 的 UI 中显示在Jobs页面下，并且作业被标记为”由 API 触发”.

Marked rebuilds as on jobs page

您可以通过访问单个作业页面查看是哪个触发器导致了重建. 从下图中可以看到，触发器的令牌的一部分显示在 UI 中.

Marked rebuilds as triggered on a single job page

通过使用 cURL，您可以以最小的努力触发管道重新运行，例如：

  1. curl --request POST \
  2.      --form token=TOKEN \
  3.      --form ref=master \
  4.      https://gitlab.example.com/api/v4/projects/9/trigger/pipeline

在这种情况下，ID 9的项目将在master分支上重建.

或者，您可以在查询字符串中传递token和ref参数：

  1. curl --request POST \
  2.     "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master"

您还可以在.gitlab-ci.yml使用触发器来.gitlab-ci.yml . 假设您有两个项目 A 和 B，并且每当在项目 A 上创建标签时，您都希望在项目 B 的master分支上触发重建. 这是您需要在项目 A 的.gitlab-ci.yml添加的工作：

  1. build_docs:
  2.   stage: deploy
  3.   script:
  4.     - "curl  --request  POST  --form  token=TOKEN  --form  ref=master  https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
  5.   only:
  6.     - tags

这意味着每当在项目 A 上添加新标签时，该作业就会运行，并且build_docs作业将被执行，从而触发项目 B 的重建build_docs stage: deploy确保该作业仅在所有带有stage: test作业之后运行成功完成.

Triggering a pipeline from a webhook

版本历史

注意事项 ：

  • 在 GitLab 8.14 中引入.
  • ref应该作为 URL 的一部分传递，以便优先于来自 Webhook 主体的ref ，该 Webhook 主体指定了触发源存储库中的触发器的分支 ref.
  • ref包含斜杠，则应进行 URL 编码.

要从另一个项目的 Webhook 触发作业，您需要为 Push 和 Tag 事件添加以下 Webhook URL（更改项目 ID，ref 和 token）：

  1. https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN

Making use of trigger variables

您可以在触发器 API 调用中传递任意数量的任意变量，这些变量将在 GitLab CI / CD 中可用，以便可以在您的.gitlab-ci.yml文件中使用. 参数的形式为：

  1. variables[key]=value

此信息也显示在 UI 中. 请注意，只有所有者和维护者才能看到这些值 .

Job variables in UI

出于多种原因，使用触发器变量可能被证明是有用的：

  • 可识别的工作. 由于该变量在 UI 中公开，因此您可以通过传递解释目的的变量来知道为什么触发了重建.
  • 有条件的作业处理. 您可以让有条件的作业在存在某个变量时运行.

考虑以下.gitlab-ci.yml ，我们在其中设置了三个阶段 ，仅当测试和构建阶段中的所有作业都通过时， upload_package作业才运行. 当UPLOAD_TO_S3变量不为零时，运行make upload .

  1. stages:
  2.   - test
  3.   - build
  4.   - package
  6. run_tests:
  7.   stage: test
  8.   script:
  9.     - make test
  11. build_package:
  12.   stage: build
  13.   script:
  14.     - make build
  16. upload_package:
  17.   stage: package
  18.   script:
  19.     - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi

然后，您可以在传递UPLOAD_TO_S3变量时触发重建，并且upload_package作业的脚本将运行：

  1. curl --request POST \
  2.   --form token=TOKEN \
  3.   --form ref=master \
  4.   --form "variables[UPLOAD_TO_S3]=true" \
  5.   https://gitlab.example.com/api/v4/projects/9/trigger/pipeline

触发变量在所有类型的变量中具有最高优先级 .

Using cron to trigger nightly pipelines

注意：以下行为也可以通过 GitLab 的 UI 与管道计划一起实现 .

无论您编写脚本还是直接运行 cURL，都可以与 cron 一起触发作业. 以下示例每晚00:30在 ID 为9的项目的master分支上触发一个作业：

  1. 30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline

Legacy triggers

在 GitLab 9.0 之前创建的旧触发器将被标记为旧触发器.

具有旧标签的触发器没有关联的用户，只能访问当前项目. 它们被认为已弃用，并将在将来的 GitLab 版本中删除.