APIによるパイプラインのトリガー

認証トークン
- トリガートークン
- CIジョブトークン
  - マルチプロジェクトパイプラインで使用する場合
  - パイプラインが他のパイプラインのアーティファクトに依存する場合
新しいトリガーの追加
トリガーの取り消し
パイプラインのトリガー
webhook からのパイプラインのトリガー
トリガー変数の利用
cronを使った夜間パイプラインのトリガー
レガシートリガー

APIによるパイプラインのトリガー

注意事項

GitLab 7.14 で導入されました。
GitLab 8.12では、ジョブの権限システムが完全に再設計されました。新しいモデルとその意味についてすべてお読みください。

トリガーを使用すると、APIコールで特定のref （ブランチまたはタグ）のパイプラインを強制的に再実行できます。

認証トークン

以下の認証方法がサポートされています：

トリガートークン
CIジョブトークン

どのジョブがパイプラインで実行されるかを制限するために$CI_PIPELINE_SOURCE 定義済み環境変数を使用する場合、どのトリガー方法が使用されるかに応じて、値はpipeline またはtriggerのいずれかになります。

`$CI_PIPELINE_SOURCE` 価値	トリガー方式
`pipeline`	CI/CD 設定ファイルで`trigger:` キーワードを使うか、トリガー API を`$CI_JOB_TOKEN`.
`trigger`	生成されたトリガートークンを使用したトリガAPIの使用

これは、pipelines またはtriggers キーワードを、レガシーなonly/except 基本構文とともに使用する場合にも適用されます。

トリガートークン

一意なトリガートークンは、新しいトリガを追加する際に取得することができます。

危険：公開プロジェクトでプレーンテキストのトークンを渡すことはセキュリティ上のイシューです。潜在的な攻撃者は、.gitlab-ci.yml ファイルでトリガートークンを公開したユーザになりすますことができます。変数を使用してトリガートークンを保護してください。

CIジョブトークン

以下の場合にCI_JOB_TOKEN 変数（GitLab コンテナレジストリとの認証に使用）を使用できます。

マルチプロジェクトパイプラインで使用する場合

マルチプロジェクトパイプラインのためのCI_JOB_TOKEN の使用はGitLab Premium9.3 で導入されました。
マルチプロジェクトパイプラインのためのCI_JOB_TOKEN の使用は、GitLab 12.4 で全ての階層で利用できるようになりました。

このトリガー方法は、.gitlab-ci.ymlの内部で呼び出された場合にのみ使用でき、パイプライングラフ上で見える依存パイプライン関係を作成します。例えば、以下のようになります：

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

この方法でトリガーされたパイプラインは、特別な変数CI_PIPELINE_SOURCE=pipelineも公開します。

パイプライントリガーAPIについての詳細はこちらをご覧ください。

パイプラインが他のパイプラインのアーティファクトに依存する場合

アーティファクトダウンロードAPIでのCI_JOB_TOKEN の使用はGitLab Premium9.5で導入されました。

異なるプロジェクト間の依存関係の導入により、あるプロジェクトが以前のプロジェクトによって作成されたアーティファクトにアクセスする必要があるかもしれません。このプロセスは、許可されたアクセスに対して許可されなければならず、特定のジョブを識別する変数CI_JOB_TOKEN を使って行うことができます。たとえば、次のようになります：

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

これは、マルチプロジェクトパイプラインに使用することができ、権限モデルと同じ原則に従っているため、アクセス権のあるプロジェクトからアーティファクトをダウンロードすることができます。

ジョブAPIについて詳しく読む

新しいトリガーの追加

プロジェクトの設定 ➔ CI/CDのTriggersで新しいトリガーを追加することができます。Add triggerボタンを押すと新しいトークンが作成され、このトークンを使って特定のプロジェクトのパイプラインの再実行をトリガーすることができます。

新しいトリガーを作成するごとに、異なるトークンが割り当てられ、スクリプトや.gitlab-ci.ymlの内部で使用することができます。また、トリガーが最後に使用された時間の概要も表示されます。

トリガーの取り消し

プロジェクトの設定 ➔ CI/CDの トリガーの下にあるRevokeボタンを押すことで、いつでもトリガーを取り消すことができます。このアクションは不可逆です。

パイプラインのトリガー

注意事項

有効なリファレンスはブランチとタグのみです。リファレンスとしてコミット SHA を渡した場合、ジョブは起動しません。

ジョブをトリガーするには、GitLabのAPIエンドポイントにPOST リクエストを送る必要があります：

POST /projects/:id/trigger/pipeline

必要なパラメータは、トリガーのtokenと、トリガーが実行される Gitref です。有効な参照はブランチとタグです。プロジェクトの:id は、API に問い合わせるか、CI/CD の設定ページにアクセスして見つけることができます。

パイプラインの再実行がトリガーされると、その情報は GitLab の UI のJobsページで公開され、ジョブは ‘by API’ でトリガーされたとマークされます。

どのトリガーが再構築を引き起こしたかは、単一ジョブのページにアクセスすることで確認できます。下の画像からわかるように、トリガーのトークンの一部が UI で公開されています。

cURLを使用することで、例えば最小限の労力でパイプラインの再実行をトリガーすることができます：

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

この場合、9 という ID のプロジェクトはmaster ブランチにリビルドされます。

あるいは、token とref の引数をクエリー文字列で渡すこともできます：

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

また、.gitlab-ci.ymlでトリガーを使用することもできます。たとえば、A と B の 2 つのプロジェクトがあり、プロジェクト A のタグが作成されるたびに、プロジェクト B のmasterブランチの再構築をトリガーしたいとします。このジョブは、プロジェクト A の.gitlab-ci.ymlに追加する必要があります：

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

これは、新しいタグがプロジェクトAにプッシュされるたびに、ジョブが実行され、build_docs ジョブが実行され、プロジェクトBの再構築がトリガーされることを意味します。stage: deploy は、stage: test を持つすべてのジョブが正常に完了した後にのみ、このジョブが実行されることを保証します。

webhook からのパイプラインのトリガー

注意事項

GitLab 8.14 で導入されました。
は、ソースリポジトリでトリガーを発火させたブランチ ref を指定する webhookref 本体よりも優先されるように、URL の一部として渡されなければrefなりません。
ref スラッシュを含む場合はURLエンコードする必要があります。

他のプロジェクトのwebhookからジョブをトリガーするには、PushとTagイベント用に以下のwebhook URLを追加する必要があります（プロジェクトID、ref、tokenを変更してください）：

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

トリガー変数の利用

トリガーAPIコールで任意の変数をいくつでも渡すことができ、それらはGitLab CI/CDで利用可能なので、.gitlab-ci.ymlファイルで使用することができます。パラメータは以下の形式です：

variables[key]=value

この情報はUIでも公開されます。_値は_オーナーとメンテナーのみが閲覧可能であることに注意してください。

トリガー変数の使用は、様々な理由で有用であることが証明されています：

識別可能なジョブ変数がUIで公開されているため、目的を説明する変数を渡せば、再構築がトリガーされた理由を知ることができます。
条件付きジョブ処理：特定の変数が存在するときに実行される条件付きジョブを持つことができます。

次の.gitlab-ci.yml 。3つのステージを設定し、upload_package 。テストステージとビルドステージのジョブがすべてパスしたときのみ、。変数UPLOAD_TO_S3がゼロでないとき、make upload が実行されます。

stages:
  - test
  - build
  - package

run_tests:
  stage: test
  script:
    - make test

build_package:
  stage: build
  script:
    - make build

upload_package:
  stage: package
  script:
    - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi

UPLOAD_TO_S3 変数を渡すと、upload_package ジョブのスクリプトが実行されます：

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

トリガー変数は、すべての変数の中で最も優先順位が高い変数です。

cronを使った夜間パイプラインのトリガー

Note:GitLabのUIでパイプラインスケジュールを使うことで、次のような動作も実現できます。

スクリプトを作成する場合でも、cURL を直接実行する場合でも、cron と連携してジョブをトリガーすることができます。以下の例では、9 という ID のプロジェクトのmasterブランチに対して、毎晩00:30にジョブをトリガーしています：

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

レガシートリガー

GitLab 9.0 より前に作成された古いトリガーはレガシーとしてマークされます。

レガシーラベルのトリガーは関連ユーザーを持たず、現在のプロジェクトにのみアクセスできます。これらは非推奨とみなされ、GitLabの将来のバージョンで削除される予定です。

クリエーションラインについて

私たちクリエーションラインは、日本で最も古く2017年にGitLabサービスの提供を開始し、2022年には「Asia-Pacific Partner of the Year」も獲得。GitLabのサブスクリプション販売やテクニカルサポートだけでなく、GitLab Enterpriseの導入支援やGitLabトレーニングなど多様なサービスを提供し、エンタープライズを中心に豊富な実績を誇ります。GitLabに関するお悩みがありましたら、ぜひお気軽にお問い合わせください。日本で唯一、3度にわたるMVPを獲得したGitLabエバンジェリストをはじめとしたエキスパートチームが、あなたの課題解決をご支援します。