APIでパイプラインをトリガーする

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

特定のブランチまたはタグのパイプラインをトリガーするには、パイプライントリガー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コマンドを使用します:

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>を123456などのプロジェクトIDに置き換えます。プロジェクト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>を123456などのプロジェクトIDに置き換えます。プロジェクト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変数は各ジョブのページに表示されますが、オーナーおよびメンテナーロールを持つユーザーのみがその値を参照できます。

パイプラインの動作を制御する場合にインプットを使用すると、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/CD変数$CI_PIPELINE_SOURCEを組み合わせて使用する。
only/exceptキーワードを使用する。ただし、推奨されるキーワードはrulesです。

`$CI_PIPELINE_SOURCE`値	`only`/`except`キーワード	トリガー方式
`trigger`	`triggers`	トリガートークンを使用して、パイプライントリガーAPIによってトリガーされるパイプラインで適用されます。
`pipeline`	`pipelines`	`$CI_JOB_TOKEN`を使用するか、CI/CD設定ファイルで`trigger`キーワードを使用して、パイプライントリガーAPIによってトリガーされるマルチプロジェクトパイプラインで適用されます。

さらに、パイプライントリガートークンでトリガーされたパイプラインでは、定義済みCI/CD変数$CI_PIPELINE_TRIGGEREDがtrueに設定されます。

どのパイプライントリガートークンが使用されたかを確認する

単一のジョブページにアクセスすると、どのパイプライントリガートークンによってジョブが実行されたかを確認できます。トリガートークンの一部が、右側のサイドバーのJob details（ジョブの詳細）に表示されます。

トリガートークンでトリガーされたパイプラインでは、ビルド > ジョブにおいて、ジョブにtriggeredというラベルが付きます。

トラブルシューティング

Webhookでパイプラインをトリガーしたときの`403 Forbidden`

Webhookでパイプラインをトリガーすると、APIが{"message":"403 Forbidden"}応答を返す場合があります。トリガーループを回避するため、パイプラインイベントを使用してパイプラインをトリガーしないでください。

パイプラインをトリガーしたときの`404 Not Found`

パイプラインをトリガーした際に{"message":"404 Not Found"}応答が返される場合、原因として、パイプライントリガートークンではなくパーソナルアクセストークンを使用していることが考えられます。新しいトリガートークンを作成し、パーソナルアクセストークンの代わりに使用してください。

パイプラインをトリガーした際に{"message":"404 Not Found"}応答が返される原因として、GETリクエストを使用している可能性も考えられます。パイプラインは、POSTリクエストでのみトリガーできます。

パイプラインをトリガーしたときの`The requested URL returned error: 400`

refに存在しないブランチ名を指定してパイプラインをトリガーしようとすると、GitLabはThe requested URL returned error: 400を返します。

たとえば、別のブランチ名をデフォルトブランチとして使用しているプロジェクトで、誤ってブランチ名にmainを指定してしまうといったケースが考えられます。

このエラーのもう1つの原因として、CI_PIPELINE_SOURCE値がtriggerの場合にパイプラインの作成を禁止するルールが設定されていることが考えられます。次に例を示します:

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

workflow:rulesを参照して、CI_PIPELINE_SOURCEの値がtriggerの場合にもパイプラインが作成できることを確認してください。