APIを使用したパイプラインのトリガー

特定のブランチやタグに対してパイプラインをトリガーするには、パイプライントリガー API エンドポイントへの API コールを使用します。

API で認証する場合は、次のようにします：

パイプライントリガートークンの作成

パイプライン・トリガー・トークンを作成し、APIコールの認証に使用することで、ブランチやタグのパイプラインをトリガーできます。トークンはユーザーのプロジェクトアクセストークンと権限を偽装します。

前提条件

  • 少なくともプロジェクトのメンテナーのロールを持っている必要があります。

トリガートークンを作成するには

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. パイプライントリガートークンを展開します。
  4. 新しいトークンを追加]を選択します。
  5. 説明を入力し、パイプライン・トリガー・トークンの作成を選択します。
    • 作成した全てのトリガーの完全なトークンを表示し、コピーすることができます。
    • 他のプロジェクトメンバーが作成したトークンは最初の 4 文字しか見ることができません。
caution
公開プロジェクトでトークンをプレーンテキストで保存することはセキュリティリスクです。潜在的な攻撃者は、.gitlab-ci.yml ファイルで公開されているトリガートークンを使って、トークンを作成したユーザーになりすますことができます。トリガートークンのセキュリティを向上させるために、マスクされた 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 "https://gitlab.example.com/api/v4/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 からパイプラインをトリガーするには、push イベントと tag イベントに次のような Webhook URL を使用します：

https://gitlab.example.com/api/v4/projects/<project_id>/ref/<ref_name>/trigger/pipeline?token=<token>

Replace：

  • URL をhttps://gitlab.com またはインスタンスの URL に置き換えてください。
  • <project_id> 123456 のようにプロジェクトIDを指定します。プロジェクトIDはプロジェクトのランディングページの上部に表示されます。
  • <ref_name> main のようにブランチ名やタグ名を指定します。この値は Webhook ペイロードのref_name よりも優先されます。ペイロードのref は、ソースリポジトリでトリガーを発生させたブランチです。ref_name にスラッシュが含まれている場合は、URL エンコードする必要があります。
  • <token> をパイプライントリガートークンで URL エンコードする必要があります。

Webhook ペイロードにアクセスします。

Webhook を使ってパイプラインをトリガーする場合、TRIGGER_PAYLOAD 定義済み CI/CD 変数を使って Webhook ペイロードにアクセスできます。ペイロードはファイル型変数として公開されるので、cat $TRIGGER_PAYLOAD や同様のコマンドでデータにアクセスできます。

API 呼び出しで CI/CD 変数を渡します。

トリガーAPIコールでは、任意の数の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 変数は各ジョブのページに表示されますが、オーナーとメンテナーのロールを持つユーザーだけが値を見ることができます。

Job variables in UI

パイプライントリガートークンの取り消し

パイプライン・トリガー・トークンを取り消します：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. パイプライントリガーを展開します。
  4. 取り消したいトリガートークンの左側にあるRevoke({remove}) を選択します。

失効したトリガートークンを元に戻すことはできません。

トリガーパイプラインで実行する CI/CD ジョブの設定

トリガーパイプラインでジョブを実行するタイミングを設定するには、次のようにします：

$CI_PIPELINE_SOURCE 値 only/except キーワードトリガー方式
triggertriggers トリガートークンを使用してパイプライントリガAPIでトリガされたパイプラインで。
pipelinepipelines $CI_JOB_TOKENまたは、CI/CD 設定ファイルでtrigger キーワードを使用します。

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

どのパイプライントリガートークンが使われたかを見る

どのパイプライントリガントークンがジョブの実行を引き起こしたかは、単独のジョブページで確認できます。ページの右側、ジョブの詳細の下にトリガートークンの一部が表示されます：

Marked as triggered on a single job page

トリガートークンでトリガされたパイプラインでは、ジョブはBuild > Jobs でtriggered と表示されます。

トラブルシューティング

403 Forbidden Webhookでパイプラインをトリガーした場合

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 を使ってしまった場合などです。

このエラーのもう1つの原因として考えられるのは、CI_PIPELINE_SOURCE の値がtrigger の場合にパイプラインを作成しないようにするルールです：

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

CI_PIPELINE_SOURCE の値がtrigger のときにパイプラインを作成できるように、workflow:rules をレビューしてください。