- 認証トークン
- 新しいトリガーの追加
- トリガーの取り消し
- パイプラインのトリガー
- webhook からのパイプラインのトリガー
- トリガー変数の利用
- cronを使った夜間パイプラインのトリガー
- レガシートリガー
APIによるパイプラインのトリガー
注意事項
- GitLab 7.14 で導入されました。
- GitLab 8.12では、ジョブの権限システムが完全に再設計されました。新しいモデルとその意味についてすべてお読みください。
トリガーを使用すると、APIコールで特定のref
(ブランチまたはタグ)のパイプラインを強制的に再実行できます。
認証トークン
以下の認証方法がサポートされています:
どのジョブがパイプラインで実行されるかを制限するために$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 を指定する webhook
ref
本体よりも優先されるように、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の将来のバージョンで削除される予定です。