TeamCity 用 VCS ポストコミットフックの構成

コミットフックの共通情報

コミットフックは TeamCity REST API を利用して、TeamCity サーバーにコマンドを発行します。 コミット後のフックで推奨されるアプローチは、リモートリポジトリにプッシュされた新しいコミットを確認するコマンドを発行することです。 これを行うには、Webhook は POST リクエストを /app/rest/vcs-root-instances エンドポイントに送信する必要があります。

• TeamCity サーバー URL は TeamCity サーバーの URL です。

• VCS ルートインスタンスロケーター は、このビルド構成で使用される特定の VCS ルートインスタンスを指す ロケーターです。

/アプリ/rest/vcs-ルート-インスタンス/コミットフック通知?ロケーター エンドポイントに送信されたリクエストはビルドを自動的にトリガーせず、TeamCity に新しい変更の確認を強制するだけです。 これらの変更が検出されたときにビルドを開始するように、 VCS トリガー を設定できます。

変更を確認して TeamCity トリガーにビルドを初期化させるのではなく、新しいビルドを明示的にキューに入れたい場合は、代わりに /アプリ/rest/ビルドキュー エンドポイントにリクエストを直接送信します。 リクエストの例については、ドキュメント記事 ビルドの開始とキャンセルを参照してください。

インスタンスロケーター

VCS ルートインスタンスロケーター は、ビルド構成でリポジトリの変更を確認する必要があるすべての VCS ルートインスタンスを検索するフィルター式です。 この式は、必要なルートインスタンスを見つけて他のすべてをフィルタリングするための一連の特定の基準を定義する必要があります。 それ以外の場合、ロケーターが無関係な多数のインスタンスを返すと、TeamCity は変更確認を過剰に実行し、サーバー負荷が増加します (場合によっては初期ポーリング負荷を超えます)。

必要な VCS ルートインスタンスは、その名前、一意の ID、親 VCS ルートの名前、プロジェクト、ビルド構成、その他のフィールドによって検索できます。 このロケーター VcsRootInstanceLocator で指定できるディメンションの完全なリストについては、この記事を参照してください。

最も信頼できるロケーターは、リポジトリ URL を使用するロケーターです (通常、リポジトリ URL は決して変更されないため)。 VCS ルートインスタンスロケーターには、使用可能なディメンションとして URL が含まれません。 代わりに、ネストされたロケーターを利用してインスタンスのプロパティを確認する必要があります。 URL のコロンとスラッシュはエスケープする必要があることに注意してください。

すべての VCS ルートインスタンスのプロパティとその値を表示するには、パスロケーター (エンドポイント?ロケーター=値 ではなく エンドポイント/値) とデフォルトの「ID」ディメンションを使用してインスタンスをリクエストします。

このリクエストは、次のようなペイロードを返します。

内部インスタンス ID を取得するには:

1. ビルド構成に移動し、 設定 タブを開きます。

2. 識別子 プロパティ値をコピーします。

   

3. Postman などの REST API テストツールを使用して、次のリクエストを送信します。

   /app/rest/vcs-root-instances?locator=buildType:<copied_value>

4. 次のような応答が返されるはずです。

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <vcs-root-instances count="1" href="/app/rest/vcs-root-instances?locator=buildType:GitLabMavenApp_Build"> <vcs-root-instance id="87" vcs-root-id="GitLabMavenApp_HttpsGitlabComUsernameReponameGitRefsHeadsMain" name="https://gitlab.com/username/reponame.git#refs/heads/main" href="/app/rest/vcs-root-instances/id:87"/> </vcs-root-instances>

   { "count": 1, "href": "/app/rest/vcs-root-instances?locator=buildType:GitLabMavenApp_Build", "vcs-root-instance": [ { "id": "87", "vcs-root-id": "GitLabMavenApp_HttpsGitlabComUsernameReponameGitRefsHeadsMain", "name": "https://gitlab.com/username/reponame.git#refs/heads/main", "href": "/app/rest/vcs-root-instances/id:87" } ] }

   上記のサンプル応答では、ビルド構成で使用される VCS ルートインスタンスの一意の ID は「87」です。

ロケーターには複数のディメンションを含めることができ、これにより複数のフィルター条件を指定できます。 例:

このロケーターは、特定の VCS ルートのすべてのインスタンスを検索します。 カウント ディメンションは、返されるインスタンスの最大数を指定された値まで増やします (デフォルトの制限は 100 エントリです)。

*-参照 パラメーターのない VCS ルートの場合、次のオプションを使用するとパフォーマンスが向上します。

認証

セキュリティ上の理由から、TeamCity ではすべての REST API 呼び出しに認証が必要です。 一部の VCS プロバイダーは、必要な認証方法 (基本認証、ベアラートークンなど) を指定する高度な Webhook 設定を提供せず、リクエストの宛先 URL のみを入力できます。 この場合、次のいずれかの形式でユーザー資格情報を URL に追加します。

• ユーザー名:パスワード - TeamCity へのログインに使用する通常の資格情報の組み合わせ。 管理 | 認証 で有効な 「基本 HTTP」モジュールが必要です。

• ユーザー名:PAT — 通常のユーザー名と 個人アクセストークンの組み合わせ。 管理 | 認証 で有効な 「トークンベースの認証」モジュールが必要です。

リクエストでは、VCS ルートが定義されているすべてのプロジェクトに対して、「プロジェクトとすべての親プロジェクトの表示」および「ビルド構成設定の表示」権限を持つユーザーの資格情報を使用する必要があります。

認証の問題が発生した場合は、 管理 | 診断 に移動し、 トラブルシューティング セクションで「debug-auth」プリセットを選択します。 その後、 TeamCity_フォルダー/ログ/teamcity-認証.log ファイルを調べて、詳細な問題情報を表示できます。

設定済みフックによるリポジトリポーリング

コミットフックが構成されているプロジェクトでは、フックが機能しなくなった場合に備えて、バックアップメカニズムとしてリモートリポジトリをポーリングし続けます。 ただし、フック通信が成功するたびに、ポーリング間隔は自動的に 2 倍になります。 TeamCity がこの間隔を延長する最大値は 4 時間で、最小間隔は 15 分です。 スケジュールされたポーリングでコミットフックをトリガーしなかった変更が見つかった場合、TeamCity はポーリング間隔をデフォルト値にリセットします。

現在のポーリング間隔とコミットフックのステータスを確認するには、 管理 | <自分のプロジェクト> | <自分のビルド構成> | バージョン管理設定 に移動します。

最小ポーリング間隔のカスタム値を設定するには、VCS ルート設定に移動し、 変更の確認 セクションまで下にスクロールします。

GitHub および GitHub Enterprise

GitHub または GitHub Enterprise への接続が GitHub アプリ経由で構成されている場合は、接続プロパティでコミット後のフックを直接設定できます。

1. GitHub App 接続を設定するときは、TeamCity の指示に従って、指定された URL を使用する GitHub App ウェブフック を作成します。

2. GitHub App 構成ページでウェブフックシークレットを設定し、同じ値を TeamCity 接続設定ダイアログに貼り付けます。

3. GitHub リポジトリにテストコミットをプッシュして、TeamCity が更新通知を受信することを確認します。 送信された更新通知と TeamCity の応答は、"GitHub App | 設定 | 詳細" ページで確認できます。

   

代替アプローチは、 GitHub チェック実行 API を活用してコミットごとに新しい TeamCity ビルドをトリガーする GitHub Checks ウェブフックトリガーを利用することです。 このトリガーは、コミットステータスパブリッシャービルド機能の代わりとしても機能します。

GitLab

GitLab の Webhook を設定する最も迅速かつ簡単な方法は、対応する GitLab CE/EE 接続設定を使用することです。 接続ヒントに従って GitLab 側でウェブフックを作成し、TeamCity で同じ シークレットトークン を使用してください。 なお、この方法は、自己管理型（オンプレミス）の GitLab インスタンスへの接続にのみ適用可能です。

Web フックを手動で設定するには、以下の手順を実行してください。

1. GitLab サーバー上の必要なリモートリポジトリに移動します。

2. GitLab サイドバーで 設定 | ウェブフック をクリックします。

   

3. 新しいウェブフックを追加 をクリックします。

4. Webhook が POST リクエストを送信する先の URL を指定します。 認証 セクションに従って、ユーザー名とパスワード /PAT を含めます。 例:

   http://valravn:querty@myteamcityfarm.build.gg/app/rest/vcs-root-instances/commitHookNotification?locator=87

5. 「トリガー」セクションで「プッシュイベント 」にチェックを入れます。

6. 「ウェブフックを追加 」をクリックして、新しい Webhook を保存します。

7. 新しいコミットをプッシュしてフックをテストします。 TeamCity ビルド構成の 保留中の変更 タブにコミットが表示されるはずです。

GitLab では、 リポジトリ設定 | 統合 ページで JetBrains TeamCity との統合を設定することもできます。 この統合は /アプリ/rest/ビルドキュー エンドポイントにリクエストを送信するため、"変更の確認" リクエストを発行する代わりに、新しいコミットがプッシュされたとき、または新しいマージリクエストが作成されたときに、新しい TeamCity ビルドを明示的にキューに入れます。

この統合を設定するには、TeamCity URL (/アプリ/rest/… 接尾辞なし)、ビルド構成 ID、TeamCity ユーザー資格情報を指定します。

Bitbucket

このアプローチは、Bitbucket クラウド、Bitbucket サーバー、および Bitbucket データセンターで利用できます。

1. 更新通知を送信する必要があるリモートリポジトリに移動します。

2. ウェブフック ページに移動します。

   サイドバーメニューで、 リポジトリ設定 | ウェブフック をクリックします。

   

   サイドバーメニューで歯車アイコンをクリックし、 ウェブフック を選択します。

   

3. ウェブフックを作成/追加 をクリックします。

4. Webhook 名を指定し、「トリガー」または「イベント」セクションで プッシュ にチェックを入れます。

5. Bitbucket が TeamCity 更新チェックをトリガーする POST リクエストを送信する先の URL を指定します。 認証 セクションに従って、URL にユーザー資格情報を含めます。 例:

   https://valravn:querty@mybuildfarm.gg/app/rest/vcs-root-instances/commitHookNotification?locator=id:34

6. 保存 または 作成 をクリックして、新しい Webhook を保存します。

7. サンプルコミットをプッシュして、Webhook がリクエストを正常に配信することを確認します。

Azure DevOps サーバー

最新の Azure DevOps Server（旧 Team Foundation Server）および Azure DevOps Services は、コードコミットイベント用のサービスフックを提供しています。 フックを作成するには、以下の手順を実行してください。

1. Azure DevOps プロジェクトのサービスフックにある サブスクリプションを作成します。

2. 統合する「Web フック」サービスを選択します。

3. コードチェックインイベントを選択し、フィルターを指定します。

4. TeamCity のユーザー名、パスワード、サーバー URL を次の形式で入力します:

   "$SERVER/app/rest/vcs-root-instances/commitHookNotification?locator=$LOCATOR"

   $ロケーター 値は、TFS リポジトリの種類によって異なります。

   vcsRoot:(type:tfs,count:99999),property:(name:tfs-url,value:<TFS server url>,matchType:equals,ignoreCase:true),property:(name:tfs-root,value:<TFS project>,matchType:contains,ignoreCase:true),count:99999

   ここで、 <TFS サーバー URL> は、Azure DevOps VCS ルート URL およびパスプロパティで指定された値に置き換える必要があります。 例:

   http://teamcity/app/rest/vcs-root-instances/commitHookNotification?locator=vcsRoot:(type:tfs,count:99999),property:(name:tfs-url,value:http%3A%2F%2Ftfs%3Aport%2Ftfs%2Fcollection,matchType:equals,ignoreCase:true),property:(name:tfs-root,value:Project,matchType:contains,ignoreCase:true),count:99999

   vcsRoot:(type:jetbrains.git,count:99999),property:(name:url,value:<VCS root repository URL>,matchType:equals,ignoreCase:true),count:99999

   ここで、 <VCS ルートリポジトリ URL> は対応する TeamCity VCS ルートで指定されたリポジトリ URL に置き換える必要があり、値は URL エスケープする必要があります。 例:

   http://teamcity/app/rest/vcs-root-instances/commitHookNotification?locator=vcsRoot:(type:jetbrains.git,count:99999),property:(name:url,value:https%3A%2F%2Faccount.visualstudio.com%2FDefaultCollection%2FProject%2F_git%2FRepository,matchType:equals,ignoreCase:true),count:99999

5. 完了 をクリックして、サービスフックを作成します。

汎用ポストコミットフック

以下のスクリプトを VCS サーバーに TeamCity トリガー.sh として保存します（個人用 アクセストークンが必要です）。

Perforce の場合、この 専用スクリプトを使用できます。

TeamCity サーバーに合わせて変数を設定します。 ユーザーは、VCS ルートが定義されているプロジェクトに対して「ビルド構成設定の表示」権限を持っている必要があります。 この権限は、デフォルトでプロジェクト開発者ロールに含まれています。

Git サーバー

1. ターゲット VCS サーバーで Git リポジトリのルートを見つけます。 .git/フック ディレクトリといくつかのテンプレートが含まれている必要があります。

2. 次の行を使用して .git/フック/ポスト受信 ファイルを作成します。

   /path/to/teamcity-trigger.sh 'vcsRoot:(type:jetbrains.git,count:99999),property:(name:url,value:<VCS root repository URL>,matchType:equals,ignoreCase:true),count:99999'

   ここで、 <VCS ルートリポジトリ URL> は対応する TeamCity VCS ルートで指定されたリポジトリ URL に置き換える必要があり、値は URL エスケープする必要があります。

3. Git ユーザーが TeamCity トリガー.sh および フック/ポスト受信 スクリプトの両方を読み取り、実行できることを確認してください。 次のコマンドを実行する必要がある場合があります。

   chmod 755 /path/to/teamcity-trigger.sh /path/to/git_root/.git/hooks/post-receive

Mercurial サーバー

1. ターゲット VCS サーバーで Mercurial リポジトリルートを見つけます。

2. .hg/hgrc 設定 を作成または編集し、次のスニペットを追加します。

   [hooks] changegroup = /path/to/teamcity-trigger.sh 'vcsRoot:(type:mercurial,count:99999),property:(name:repositoryPath,value:<VCS root repository url>,matchType:equals,ignoreCase:true),count:99999'

   ここで、 <VCS ルートリポジトリ URL> は対応する TeamCity VCS ルートで指定されたリポジトリ URL に置き換える必要があり、値は URL エスケープする必要があります。

3. TeamCity トリガー.sh が実行可能であることを確認してください。 次のコマンドを実行する必要がある場合があります。

   chmod 755 /path/to/teamcity-trigger.sh

Subversion サーバー

1. データベース、 フック、 ロック を含む Subversion リポジトリのルート、およびその他のディレクトリを見つけます。 フック ディレクトリが必要です。

2. 次の行を使用して フック/ポストコミット ファイルを作成します。

   /path/to/teamcity-trigger.sh 'vcsRoot:(type:svn,count:99999),property:(name:url,value:<VCS root repository url>,matchType:equals,ignoreCase:true),count:99999'

   ここで、 <VCS ルートリポジトリ URL> は対応する TeamCity VCS ルートで指定されたリポジトリ URL に置き換える必要があり、値は URL エスケープする必要があります。

3. Subversion サーバーのプロセスが TeamCity トリガー.sh と フック/ポストコミット の両方のスクリプトを読み取り、実行できることを確認してください。 次のコマンドを実行する必要がある場合があります。

   chmod 755 /path/to/teamcity-trigger.sh /path/to/svn_repository_root/hooks/post-commit

Perforce サーバー

ここでは、専用の Perforce スクリプトの設定方法について説明します。 汎用スクリプトを利用することも可能ですが、これは古いアプローチであり、現在は推奨されていないことに注意してください。

Perforce サーバーにインストールされている専用のポストコミットスクリプトは、TeamCity の Perforce VCS ルートを自動的に検出し、対応するビルドをトリガーします。 スクリプトを使用するには、まず アクセストークンを生成する必要があります。 このトークンに割り当てられた TeamCity ユーザーには、Perforce VCS ルートが定義されているプロジェクトに対する"ビルドの実行"権限が必要です。 この権限は、デフォルトでプロジェクト開発者ロールに含まれています。

プロジェクト設定で Perforce 管理者アクセス接続を構成することもお勧めします。 TeamCity はこれを使用して、Perforce 変更リスト内のすべての変更済みファイルが収集されるようにします。 このような接続が明示的に設定されていない場合、TeamCity はプロジェクトの VCS ルートの 1 つの設定を使用して Perforce への接続を試みます。

1. このスクリプトを Perforce サーバーに TeamCity フック.sh として保存します。

   #!/bin/sh # How to use this script: # 1. Save the script on the Perforce server under the name /path/teamcity-hook.sh. # 2. Run chmod +x /path/teamcity-hook.sh. # 3. Set up a change-commit trigger by adding the following line when editing the specification with the `p4 triggers` command: # check-for-changes-teamcity change-commit //depot/... "/path/teamcity-hook.sh %change%" # 4. Update the variables below. # # Update the following variables: # TeamCity server root URL: TEAMCITY_SERVER=http://localhost:8111/bs # Access token of a user on TeamCity server which can run builds in all relevant configurations (Developer role) TC_ACCESS_TOKEN="<token_value>" # This P4PORT value will be used to find relevant VCS roots, it should be equal to the P4Port setting in the VCS root: P4PORT="localhost:1666" CHANGE=$1 # The following is one line: (sleep 10; curl -H "Authorization: Bearer $TC_ACCESS_TOKEN" -d "p4port=$P4PORT&changelistId=$CHANGE" "$TEAMCITY_SERVER/app/perforce/commitHook" -o /dev/null) >/dev/null 2>&1 <&1 & exit 0

2. chmod +x /パス/TeamCity フック.sh を実行します。

3. p4 トリガー コマンドを使用して Perforce 仕様を編集する(英語)を実行し、次の行を追加して変更コミットトリガーを設定します。

   check-for-changes-teamcity change-commit //depot/... "/path/teamcity-hook.sh %change%"

   ここで、 //デポ/… は TeamCity ビルドで使用されるディポです。 複数のディポがある場合は、このパスを //… に置き換えることができます。

4. スクリプトの変数を TeamCity 設定に合わせて更新します。