TeamCity 用の VCS ポストコミットフックの設定

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

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

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

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

/app/rest/vcs-root-instances/commitHookNotification?locator エンドポイントに送信されたリクエストは、自動的にビルドをトリガーしません。これらは、TeamCity に新しい変更の確認を強制するだけです。これらの変更が検出されたときにビルドを開始するように VCS トリガーを構成できます。

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

インスタンスロケーター

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

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

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

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

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

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

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

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

   

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 ルートのすべてのインスタンスを検索します。count ディメンションは、返されるインスタンスの最大数を指定された値まで増やします (デフォルトの制限は 100 エントリです)。

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

認証

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

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

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

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

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

構成されたフックによるリポジトリのポーリング

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

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

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

GitHub と GitHub Enterprise

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

1. GitHub アプリ接続を構成するときは、TeamCity の指示に従って、指定された URL を使用して GitHub アプリ Webhook(英語) を作成します。

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

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

   

代替アプローチは、GitHub チェックラン API(英語) を活用してコミットごとに新しい TeamCity ビルドをトリガーする GitHub チェック Webhook トリガーを使用することです。このトリガーは、コミットステータスパブリッシャービルド機能の代わりとしても機能します。

GitLab

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

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

   

3. 新しい Web フックを追加をクリックします。

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

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

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

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

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

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

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

Bitbucket

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

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

2. Web フックページに移動します。

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

   

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

   

3. Webhook の作成 / 追加をクリックします。

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

5. TeamCity 更新チェックをトリガーするために、Bitbucket が 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"

   $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 server 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 root repository 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-trigger.sh として保存します（個人用アクセストークンが必要です）。

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

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

Git サーバー

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

2. 次の行を使用して .git/hooks/post-receive ファイルを作成します。

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

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

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

Mercurial サーバー

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

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

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

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

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

Subversion サーバー

1. db、hooks、locks を含む Subversion リポジトリのルート、およびその他のディレクトリを見つけます。hooks ディレクトリが必要です。

2. 次の行を使用して hooks/post-commit ファイルを作成します。

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

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

   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-hook.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 /path/teamcity-hook.sh を実行します。

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

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

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

4. スクリプトの変数を TeamCity 設定で更新します。