TeamCity ウェブフック

ウェブフックを有効化

1. 管理 | <ルートプロジェクト> | パラメーター に移動します。

2. 「新しいパラメーターを追加 」をクリックして 2 つの 構成パラメーターを作成します。

   

   • teamcity.internal.webhooks.enable — Webhook を有効にするかどうかを指定します。 このパラメーターを 真 に設定します。

   • teamcity.internal.webhooks.url — TeamCity がペイロードを送信する先の URL (HTTP POST リクエスト経由) を格納します。 テストの目的で、 Webhook.site(英語) や ビーセプター(英語)などのリアルタイム Webhook テストサービスによって提供される URL を指定できます。

3. POST リクエストの送信をトリガーするイベントのリストを指定します。 これを行うには、イベントを追跡する必要がある TeamCity プロジェクト用に teamcity.internal.webhooks.events 構成パラメーターを作成します。

   以下のリストは、最も頻繁に使用される teamcity.internal.webhooks.events パラメーター値を列挙したものです。 使用可能なイベントの完全なリストについては、 Open API Javadoc(英語) を参照してください。 複数の値の区切りとしてセミコロン (;) を使用します。

   エージェント登録済み

   追跡対象イベント: 新しいビルドエージェントが TeamCity サーバーに接続し、 認証トークンを取得しました。
   親プロジェクト: <ルートプロジェクト> のみ
   REST API ペイロードスキーマ: #/definitions/agent

   エージェント登録解除済み

   追跡対象イベント: ビルドエージェントが停止し、サーバーから切断されました。 エージェントソフトウェアのアップグレードが必要な場合や、エージェントサービスを手動で停止した場合に発生することがあります。
   親プロジェクト: <ルートプロジェクト> のみ
   REST API ペイロードスキーマ: #/definitions/agent

   エージェント除去済み

   追跡対象イベント: ビルドエージェントが除去されました。
   親プロジェクト: <ルートプロジェクト> のみ
   REST API ペイロードスキーマ: #/definitions/agent

   BUILD_STARTED

   追跡対象イベント: ビルドが開始されました。 BUILD_TYPE_ADDED_TO_QUEUE イベントの後に続きます。
   親プロジェクト: 任意のプロジェクト。
   REST API ペイロードスキーマ: #/definitions/build

   ビルド完了。

   追跡対象イベント: ビルドは、失敗したか成功したかにかかわらず終了します。
   親プロジェクト: 任意のプロジェクト。
   REST API ペイロードスキーマ: #/definitions/build

   ビルド中断済み

   追跡対象イベント: 実行中のビルドがキャンセルされました。 キャンセルされたビルドは ビルド完了。 イベントをトリガーしません。
   親プロジェクト: 任意のプロジェクト。
   REST API ペイロードスキーマ: #/definitions/build

   CHANGES_LOADED

   追跡対象イベント: TeamCity はリモートリポジトリから変更を正常に収集し (または新しい変更が存在しないことを確認し)、ビルドステップを実行する準備ができています。 ビルドによっては、 BUILD_STARTED イベントの前または後に発生することがあります。
   親プロジェクト: 任意のプロジェクト。
   REST API ペイロードスキーマ: #/definitions/build

   BUILD_TYPE_ADDED_TO_QUEUE

   追跡対象イベント: ビルドが開始され、ビルドキューに配置されました。
   親プロジェクト: 任意のプロジェクト。
   REST API ペイロードスキーマ: #/definitions/build

   ビルドの問題が変更されました

   追跡対象イベント: ビルドの問題のリストが変更されました (同じビルド構成の前回の実行と比較)。
   親プロジェクト: 任意のプロジェクト。
   REST API ペイロードスキーマ: #/definitions/build

4. 追跡対象イベントをトリガーするアクションを実行し (たとえば、新しいビルドを実行して BUILD_TYPE_ADDED_TO_QUEUE > CHANGES_LOADED > BUILD_STARTED > ビルド完了。 チェーンをトリガーするなど)、ターゲット URL が対応する POST リクエストを受信することを確認します。

リクエストペイロードのカスタマイズ

デフォルトでは、Webhook は完全な エージェントまたは ビルドペイロードを含むリクエストを送信します。 リクエストペイロードに存在する必要があるフィールドを手動で指定できます。 これを行うには、値として fields=field1,field2,object(field3) を指定して teamcity.internal.webhooks.{event_name}.fields 構成パラメーターを追加します。

例: teamcity.internal.webhooks.BUILD_INTERRUPTED.fields = fields=buildTypeId,number,canceledInfo(user(username)) パラメーターには、キャンセルされたビルドの番号、対応するビルド構成の ID、およびこのビルドをキャンセルした人のユーザー名のみが表示されます。

認証設定

受信者 API が POST リクエストの匿名送信を許可しておらず、承認が必要な場合は、次の追加パラメーターを指定します。

• teamcity.internal.webhooks.username — 「php-auth-user」ヘッダーに書き込まれるユーザー名。

• teamcity.internal.webhooks.password — 「php-auth-pw」ヘッダーに書き込まれるパスワード。 この値を安全に保存し、TeamCity UI および REST リクエストから非表示にするには、パラメーター設定ダイアログで 編集… をクリックし、"パスワード" タイプを選択します。

  

失敗したリクエストを再送信

リクエストが配信されなかった場合 (リクエストの送信中に例外がスローされた、または受信者のレスポンスコードが「2**」以外だった場合)、TeamCity はこのメッセージの再送信を試行できます。 これを行うには、 teamcity.internal.webhooks.retry_count パラメーターを作成し、その値として再試行回数を設定します。 デフォルト値は 0 です。

パラメーターの継承

TeamCity プロジェクトは、親プロジェクトから構成パラメーターを継承します。 たとえば、 <ルートプロジェクト> に teamcity.internal.webhooks.events=BUILD_STARTED;BUILD_FINISHED パラメーターがある場合、すべての TeamCity プロジェクトはビルドの開始時と終了時にウェブフックメッセージを送信します。

親プロジェクトと子プロジェクトの両方に同じ名前のパラメーターがある場合、子プロジェクトは継承された値をオーバーライドします。 例:

• <ルートプロジェクト> には teamcity.internal.webhooks.events=BUILD_STARTED;BUILD_FINISHED パラメーターがあります；

• プロジェクト A には teamcity.internal.webhooks.events=BUILD_INTERRUPTED パラメーターがあります。

この場合、すべての TeamCity プロジェクトはビルドの開始時と終了時に報告しますが、 プロジェクト A はキャンセルされたビルドのみを報告します。 プロジェクト A で 3 つのイベントすべてを報告する必要がある場合は、そのパラメーター値を BUILD_STARTED;BUILD_FINISHED;BUILD_INTERRUPTED に変更します。