pipeline trigger tokenとは? API経由でrunを開始する

pipeline trigger tokenは、外部システムがUIログインなしにAPI呼び出しでpipeline runを開始できるようにする秘密の認証情報です。

pipelineは、通常のpushやPRのフローの外から開始する必要がある場合があります。別のシステムが作業を終えた、schedulerが発火した、あるいはデプロイツールがbuildを起動したいときなどです。pipeline trigger tokenがそれを認可します。これは、API リクエストとともに提示されると、CIシステムに「この呼び出し元はこのpipelineを開始する権限がある」と伝える秘密情報です。

trigger tokenの用途

プログラムによるpipeline開始を認証します。人がrunをクリックする代わりに、外部サービスがtokenを載せたAPI呼び出しを送り、tokenが呼び出し元の認可を証明するためCIシステムがrunを開始します。

どう使われるか

プロジェクトまたはpipelineにスコープを絞ったtokenを生成する。
呼び出し側のシステムにsecretとして保存する。
呼び出し元がそれをtrigger APIリクエストに含める。
CIシステムがそれを検証してrunを開始する。

簡単な例

デプロイツールがプロビジョニングを終え、token=${TRIGGER_TOKEN} とbranchのrefを付けてCIのtriggerエンドポイントを呼び出します。CIシステムはtokenを検証し、そのbranchのpipeline runをキューに入れます。

trigger tokenを安全に保つ

trigger tokenはpipelineを開始できるため、あらゆるsecretと同様に扱いましょう。スコープを狭く絞り、暗号化して保存し、決してcommitせず、露出したらローテートします。漏洩したtokenは、誰でもあなたのpipelineをtriggerできてしまいます。

trigger tokenと連鎖

trigger tokenは、downstreamやプロジェクト間のpipelineが接続する手段です。upstreamのpipelineがtokenを提示してdownstreamのものを開始します。これらは、プロジェクトの境界を越えた多くのpipelineオーケストレーションを支える認証情報です。

重要なポイント

trigger tokenは、API呼び出しによるpipelineの開始を認可します。
外部システムはUIログインなしにrunを起動するためにこれを提示します。
secretとして扱いましょう。スコープを絞り、安全に保存し、漏洩したらローテートします。