TeamCity 2020.1ヘルプ

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

概要

デフォルトでは、TeamCityはポーリングアプローチを使用してVCSリポジトリの変更を検出します。つまり、VCSルートごとに、定期的にバージョン管理リポジトリサーバーに要求を送信して、新しいリビジョンがあるかどうかを確認します。数百のVCSルートを持つ大規模なインストールの場合、これにより、VCSサーバーおよびTeamCity自体に顕著な負荷が生じる可能性があります。

バックグラウンドポーリングを回避するために、VCSサーバーにコミット後フックを設定することができます。これにより、変更手順の確認を開始するようTeamCityに通知されます。このようにして、TeamCityは、変更が利用可能な場合にのみ、変更検出のバックグラウンド要求を行います。

コミットフックが構成され、適切に動作している場合でも、TeamCityは、サーバーの起動時および各ビルドキュー(または起動時)で変更の要求を行い、コミットフックが機能しなくなっても最新の変更が使用されるようにします。

When a commit hook call comes in, TeamCity starts checking for changes in VCS Roots which match the request. If a change is found during the check, TeamCity automatically increases the VCSポーリング間隔 (the minimum after the increase is 15 minutes, maximum is 4 hours, increased by 2 times on each successful check). If the commit hook stops working (for example, TeamCity finds a change in a VCS root which it did not receive a commit hook call for), the VCSポーリング間隔 value is reset to default.

コミットフックは、通常、コミット後リポジトリトリガーで構成する必要があるTeamCity REST API リクエストを介して受信されます。

POST .../app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstancesLocator>

要求は、実行された操作に関するテキストの詳細またはエラーメッセージを返します。

It is important to find the <vcsRootInstancesLocator> for the request to match only the affected VCS roots from those configured in the TeamCity instance. If too many VCS roots are matched by the request configured in the commit hook, it will lead to more requests and more overload on the VCS repository and TeamCity than using default polling approach. Some examples of the "locator" are provided below.
The request should be performed by a user who has "View project and all parent projects" permission for all the projects where VCS root is defined.
Note that by default only the first 100 matched "VCS root instances" will be matched by the request. To match more, "count:9999" can be added as below.

<vcsRootInstancesLocator> の最も一般的な形式は次のとおりです。

vcsRoot:(type:<TYPE>,count:99999),property:(name:<URL_PROPERTY_NAME>,value:<VCS_REPOSITORY_URL_PART>,matchType:contains,ignoreCase:true),count:99999

ただし、パラメータ %-referencesのないVCSルートの場合、よりパフォーマンスの高い分散を使用できます。

vcsRoot:(type:<TYPE>,property:(name:<URL_PROPERTY_NAME>,value:<VCS_REPOSITORY_URL_PART>,matchType:contains,ignoreCase:true),count:99999),count:99999

UNIXベースのVCSサーバーのコミットフックの例を以下に説明します。

コミット後の汎用スクリプト

以下のスクリプトをVCSサーバーに teamcity-trigger.sh として保存します(個人アクセストークンを生成する必要があります)。

SERVER=https://buildserver-url ACCESS_TOKEN="<access-token>" LOCATOR=$1 # The following is one-line: (sleep 10; curl --header "Authorization: Bearer $ACCESS_TOKEN" -X POST "$SERVER/app/rest/vcs-root-instances/commitHookNotification?locator=$LOCATOR" -o /dev/null) >/dev/null 2>&1 <&1 & exit 0

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:contains,ignoreCase:true),count:99999'

<VCS root repository URL> は、対応するTeamCity VCSルートで指定されたリポジトリURLに置き換える必要があり、値はURLエスケープする必要があります。ロケーターには matchType:contains が含まれていることに注意してください。つまり、URL too.fileの一部を指定できます。

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:contains,ignoreCase:true),count:99999'

<VCS root repository URL> は、対応するTeamCity VCSルートで指定されたリポジトリURLに置き換える必要があり、値はURLエスケープする必要があります。ロケーターには matchType:contains があるため、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:contains,ignoreCase:true),count:99999'

<VCS root repository URL> は、対応するTeamCity VCSルートで指定されたリポジトリURLに置き換える必要があり、値はURLエスケープする必要があります。ロケーターには matchType:contains があるため、URLの一部も指定できることに注意してください。

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

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

Perforceサーバーでのコミット後トリガーのセットアップ

Set up a change-commit trigger by adding one or several lines when editing specification(英語) (the text below must be placed in one line, one line per trigger):

check-for-changes-teamcity change-commit //depot/project1/... "/path/teamcity-trigger.sh '<VCS Root locator>'"

<VCS Root locator> は次のいずれかになります。

  • ストリームベースのVCSルートの場合:

vcsRoot:(type:perforce,count:99999),property:(name:stream,value://streamdepot/streamname,matchType:contains,ignoreCase:true),count:99999
  • クライアントベースのVCSルートの場合:

vcsRoot:(type:perforce,count:99999),property:(name:client,value:<client name>,matchType:contains,ignoreCase:true),count:99999
  • クライアントマッピングVCSルートの場合:

vcsRoot:(type:perforce,count:99999),property:(name:client-mapping,value:<some unique part of client mapping>,matchType:contains,ignoreCase:true),count:99999

Where <some unique part of client mapping> should match the Perforce depot path in TeamCity VCS Root after all parameter resolution. For the rule check-for-changes-teamcity change-commit //depot/project1/... it should probably be //depot/project1/ .

Each such check-for-changes-teamcity rule line describes an association between path with commit ( //depot/project1 ) and a set of VCS Roots in TeamCity which should be checked for changes.

TFVCおよびGit用のTeam Foundationサーバーでのサービスフックのセットアップ

最新のAzure DevOps Server(以前のTeam Foundation Server)およびAzure DevOps Servicesは、コードコミットイベントのサービスフックを提供します。フックを作成するには、次の手順を実行します。

1. Webアクセスでチームプロジェクトの管理ページを開きます。

2. ウィザードを実行してサブスクリプションを作成します。

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

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

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

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

以下のセクションで説明するように、$LOCATOR 値はTFSリポジトリタイプに依存します。

TFVCリポジトリ

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

<TFS server url> は、TFS 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:contains,ignoreCase:true),property:(name:tfs-root,value:Project,matchType:contains,ignoreCase:true),count:99999

Git リポジトリ

vcsRoot:(type:jetbrains.git,count:99999),property:(name:url,value:<VCS root repository URL>,matchType:contains,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:contains,ignoreCase:true),count:99999

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

トラブルシューティング

実際のフックを設定する前に、コマンドラインから次のコマンドを実行することをお勧めします。

curl --header "Authorization: Bearer $ACCESS_TOKEN" -X POST "$SERVER/app/rest/vcs-root-instances/commitHookNotification?locator=$LOCATOR"

コミットフックがサーバー上のVCSルートと正しく一致する場合、次のような出力が表示されます。

Scheduled checking for changes for 1 VCS roots. (Server time: 20160719T192540.787+0300)

コミットフックでVCSルートが見つからなかった場合、エラーが報告されます。

No VCS roots are found ...

この出力の考えられる理由:

  • 指定されたロケーターが正しくない、サーバー上のどのVCSルートとも一致しない

  • 指定されたユーザーには、一致するVCSルートの少なくとも1つに対する十分な権限がありません。

実際に一致するルートを確認するには、リクエストを使用します(詳細も参照)。

curl --header "Authorization: Bearer $ACCESS_TOKEN" -X POST "$SERVER/app/rest/vcs-root-instances?locator=$LOCATOR"