Git

サーバーでの VCS 関連の操作用のネイティブ Git

TeamCity は、サーバーでの Git 操作のデフォルトオプションとしてネイティブ Git を使用できるようになりました。ネイティブ Git に切り替えると、以前に使用された JGit 実装と比較して、サーバーでの変更操作のチェックのパフォーマンスが向上します。また、大規模な Git リポジトリに関連する多くの問題も修正されています。

切り替える前に、ネイティブ Git クライアント(英語)バージョン 2.29 以降がサーバーマシンにインストールされ、その実行可能ファイルへのパスが PATH 環境変数に指定されていることを確認してください。または、teamcity.server.git.executable.path 内部プロパティを使用して実行可能ファイルへのフルパスを設定することもできます (サーバーの再起動は不要です)。Windows では、パスに二重のバックスラッシュを使用することを忘れないでください。

TeamCity サーバーをネイティブ Git に切り替えるには、管理 | 診断に移動し、Git タブを開きます。ここでは、サーバー上の任意の VCS ルートでネイティブ Git を介した接続をテストできます。すべての VCS ルートをテストすることを選択した場合、TeamCity は、JGit を介して正常に接続されているかどうかを確認してから、ネイティブ Git を介して接続をテストします。この対策は、ネイティブ Git に切り替えた後にパイプラインが破損しないようにできます。接続テストが成功した場合は、サーバーでネイティブ Git サポートを有効にできます。

一般設定

• URL を取得 — リポジトリからデータを取得するために使用されるリモート Git リポジトリの URL。

  個々のエージェントのフェッチ URL をオーバーライドして、元の VCS ホスティングではなく、より近いプロキシを使用できるようにすることができます。これを行うには、必要なエージェントの conf/buildAgent.properties ファイルを開き、次のようにリダイレクトルールを追加します: teamcity.git.fetchUrlMapping.<name> = <source URL> => <target URL> 例:

  teamcity.git.fetchUrlMapping.firstrule = https://example.com/org/test.git => http://proxy.com/test.git

  部分的なアドレスとアスタリスク (*) ワイルドカードを使用して、パターンに一致するすべてのフェッチ URL のプロキシを設定できます。例: 次のルールにより、エージェントは元の https://example.com/org/test/test.git の代わりに http://proxy.com/test/test.git URL を使用できます。

  teamcity.git.fetchUrlMapping.secondrule = https://example.com/org/* => http://proxy.com/

  フェッチ URL とともに、VCS ルートにはリポジトリへのアクセスに必要な認証設定も保存されることに注意してください。そのため、フェッチ URL の置き換えは、匿名または秘密鍵認証モードを使用する VCS ルートに対してのみ有効です。他のモードでは、エージェントがリポジトリにアクセスできることが保証されません (たとえば、ソース VCS 用に発行されたリフレッシュ可能なトークンは、プロキシホスティングでは受け入れられません)。

• プッシュ URL — VCS ラベリングビルド機能によって作成されたアノテーション付きタグをリモートリポジトリにプッシュするために使用されるターゲットリモート Git リポジトリの URL。空白の場合は、フェッチ URL が使用されます。

• デフォルトブランチ - デフォルトはブランチです。ここではパラメーター参照がサポートされています。デフォルト値は refs/heads/master です。

• ブランチ仕様 — 機能ブランチのサポートに必要なブランチ名のパターンをリストします。デフォルトのブランチに加えて、一致したブランチの変更も監視されます。構文はチェックアウトルール +|-:branch_name に似ています。ここで、branch_name は VCS に固有です。つまり、Git の refs/heads/ です (オプションの * プレースホルダーを使用)。

• ブランチとしてタグを使用 — ブランチとして git タグを監視 / チェックアウトできるようにし、ブランチ仕様をブランチと同様にタグ名と一致させます (たとえば、+|-:refs/tags/<tag_name>)。デフォルトでは、タグは無視されます。

• ユーザー名スタイル — TeamCity が VCS 変更のユーザー名を報告する方法を定義します。ユーザー名のスタイルを変更すると、新しく収集された変更にのみ影響します。古い変更は、変更を収集した時点でアクティブだったスタイルで引き続き保存されます。

• サブモジュール — サブモジュールリポジトリをチェックアウトするかどうかを指定します。複数レベルのサブモジュールを設定する場合は、「チェックアウト」(リポジトリツリー全体を再帰的に取得) モードと「非再帰チェックアウト」(メインリポジトリによって直接参照されるサブモジュールのみを取得) モードを選択できます。下のダイアグラムでは、サブモジュール A と B は両方のモードで使用できますが、サブモジュール C と D には再帰的な「チェックアウト」モードが必要です。

  Main_Repo | |_________ Tier 1 Submodule A | | | |_________ Tier 2 Submodule C | |_________ Tier 1 Submodule B | |_________ Tier 2 Submodule D

  サブモジュールリポジトリは、認証を必要としないか、同じプロトコルを使用して、VCS ルートで設定されているのと同じ認証を受け入れる必要があります。それ以外の場合は、LFS とサブモジュールのサポートセクションに従って、これらのリポジトリにアクセスするための追加の資格情報を設定する必要があります。

• タグ / マージのユーザー名 — ラベル付けに使用されるカスタムユーザー名。

認証設定

• 匿名 - 匿名の読み取りアクセスでリポジトリを複製するには、このオプションを選択します。

• パスワード / 個人アクセストークン — 有効なユーザー名 (クローン URL にユーザー名がない場合、このフィールドで指定されたユーザー名が URL のユーザー名を上書きします) と、リポジトリのクローン作成に使用するパスワードを指定します。
  エージェント側のチェックアウトの場合、エージェントに Git 1.7.3\+ クライアントの場合のみがインストールされていればサポートされます。TW-18711(英語) を参照してください。
  Team Foundation Server 2013 からホストされる Git の場合は、ここで NTLM 資格情報を指定します。

  GitHub、Azure DevOps Services、GitLab、JetBrains Space、および Bitbucket での認証には、パスワードの代わりに個人アクセストークンを使用できます。Azure DevOps に接続するときは、TeamCity からアクセスするリポジトリで、コードアクセススコープをバージョン管理設定のコード（読み取り）/ コード（読み取りと書き込み）に設定することを忘れないでください。

  既存の Bitbucket クラウド、Bitbucket サーバー、GitLab または Azure DevOps Services 接続を使用して VCS ルートを作成する場合、TeamCity はパスワードの代わりにリフレッシュ可能なトークンを使用します。

• リフレッシュ可能なトークン — GitHub、GitHub App、Bitbucket サーバー、Bitbucket Cloud、Azure DevOps、GitLab、JetBrains Space からデータを取得する VCS ルートが TeamCity 接続を使用して設定されている場合、リフレッシュ可能なトークンはデフォルトで有効になります。

  リフレッシュ可能なアクセストークンは、既存の OAuth 接続を介して必要な VCS プロバイダーから TeamCity によって取得される短命のトークンです (VCS ホスティング側のユーザーが手動で発行する静的 PAT トークンとは対照的です)。リフレッシュ可能なトークンの生成と使用の詳細については、次の記事を参照してください: リフレッシュ可能なアクセストークンの管理。

  クローン (フェッチ) URL にユーザー名がない場合、ユーザー名を指定できます。ここで指定したユーザー名は、URL のユーザー名よりも優先されます。

• 秘密鍵 — SSH プロトコルにのみ有効です。秘密鍵は OpenSSH フォーマットに存在する必要があります。

  秘密鍵リストからオプションの 1 つを選択し、有効なユーザー名を指定します (クローン URL にユーザー名がない場合、ここで指定したユーザー名が URL のユーザー名よりも優先されます)。
  利用可能な秘密鍵オプション:

  • アップロードされたキー — プロジェクトにアップロードされたキーを利用するには、このオプションを選択します。

  • デフォルトの秘密鍵 — このオプションを選択すると、一般的な ssh ツールで使用されるデフォルトの場所にあるファイルシステムで使用可能なキーが使用されます。ファイルが存在する場合は <USER_HOME>/.ssh/config で指定されたマッピング、または秘密鍵ファイル <USER_HOME>/.ssh/id_rsa (ファイルはサーバー上に存在する必要があり、またエージェント側のチェックアウトが使用されている場合はエージェントで)。

  • カスタム秘密鍵 — サポートされているサーバー側チェックアウトのみ。秘密鍵パスフィールドに、サーバーマシン上の秘密鍵ファイルへの絶対パスを入力します。キーが暗号化されている場合は、対応するフィールドにパスフレーズを指定します。

GitHub に接続するために利用可能なすべてのオプションについては、コメント(英語)を参照してください。

サーバー設定

これらは、サーバー側チェックアウトの場合に使用される設定です。

エージェント設定

これらはエージェント側チェックアウトの場合に使用される設定です。
エージェント側のチェックアウトでは SSH のサポートが制限されていることに注意してください。サポートされている認証方法は、「デフォルトの秘密鍵」と「アップロードされた秘密鍵」のみです。
エージェント側のチェックアウトを使用する場合は、エージェントに Git 1.6.4+ をインストールする必要があります。

サーバーでの Git ガベージコレクションの設定

TeamCity サーバーは、サーバー上で構成された VCS ルートで使用されるすべての Git リポジトリのローカルクローンを維持します。サーバーは 1 日に何度もこれらのクローンのフェッチを実行するため、予測可能なパフォーマンスを維持するにはクローンを定期的に最適化する必要があります。クローンの Git ガベージコレクションが長期間実行されなかった場合、変更を収集するプロセスが遅くなったり、メモリ関連のエラーが報告され始めたりすることがあります。
TeamCity は、ネイティブ Git クライアントがサーバー上で見つかると、定期的に git gc を自動的に実行できます。Git GC を実行できない場合は、関連するヘルスレポートが生成されます。

警告を修正する / 自動 git gc 要件を満たすには、次を実行します。

1. ネイティブ Git クライアントを TeamCity サーバーに手動でインストールします。

2. Git 実行可能ファイルへのパスを指定します。

   • 実行可能ファイルのあるディレクトリを PATH 環境変数に追加してサーバーを再起動するか

   • サーバーを再起動せずに、teamcity.server.git.executable.path 内部プロパティで実行可能ファイルへのフルパスを設定します。Windows では、パスに二重の円記号を使用することを忘れないでください。

TeamCity が Git ガベージコレクションを実行すると、詳細が teamcity-cleanup.log に記録されます。git ガベージコレクションが失敗した場合、対応する警告が表示されます。

TeamCity は、合計時間が 5 時間のクォータを超えなくなるまで Git ガベージコレクションを実行します。クォータは、teamcity.server.git.gc.quota.minutes 内部プロパティを使用して変更できます。
Git ガベージコレクションは毎晩午前 2 時に実行されます。これは、次のような cron 式で内部プロパティを指定することで変更できます。teamcity.git.cleanupCron=0 0 2 * * ?git gc プロセスの動作が遅く、割り当てられた時間内に完了できない場合は、デフォルトの Git 構成ファイル内の git-repack 構成を確認します (たとえば、--window-memory を増やすと、git gc のパフォーマンスが向上します)。

ローカル Git クローンに何らかの手動メンテナンスが必要な場合は、<TeamCity Data Directory>/system/caches/git ディレクトリにあります。ディレクトリ内の map ファイルには、リポジトリ URL とリポジトリのベアクローンを格納するサブディレクトリ間のマッピングが含まれています。

LFS とサブモジュールのサポート

内部プロパティ

Git VCS では、次の内部プロパティを設定できます。

teamcity.git.idle.timeout.seconds

デフォルト値 : 1800

リモートリポジトリと通信するためのアイドルタイムアウト。このタイムアウトの間にデータが送受信されなかった場合、プラグインはタイムアウトエラーをスローして、プロセスが永久にハングするのを防ぎます。

teamcity.git.fetch.timeout

デフォルト値 : 1800

このプロパティは非推奨です。git fetch 操作のための teamcity.git.idle.timeout.seconds のオーバーライド

teamcity.git.fetch.separate.process

デフォルト値 : true

TeamCity が git fetch を別のプロセスで実行するかどうかを指定します

teamcity.git.fetch.process.max.memory

デフォルト値 : なし

このプロパティは明示的な -Xmx を提供し、自動 -Xmx セットアップを無効にします。

メインサーバープロセスに加えて、構成されたメモリが使用されるため、サーバーマシンに十分なメモリがあることを確認します。git fetch および git patch を実行する複数の子プロセスが存在し、それぞれが構成されたメモリ量を使用します。Git フェッチのために -Xmx1024m よりも大きなヒープメモリを必要とする大きなリポジトリの場合、64 ビット Java に切り替えるが必要になる場合があります。

teamcity.git.fetch.process.max.memory.limit

デフォルト値 : なし

デフォルトでは、TeamCity は git fetch および git patch のネストされた Java プロセスを開始し、これらのプロセスの -Xmx を自動的に選択します。

このプロパティは、TeamCity が自動的に設定できる git fetch または git patch の可能な最大 -Xmx 値を指定します。

teamcity.git.monitoring.expiration.timeout.hours

デフォルト値 : 24

fetch が別のプロセスで使用される場合、自身のスレッドダンプを作成し、TEAMCITY_DATA_DIR/system/caches/git/<git-XXX>/monitoring に保存します（ディレクトリマッピングは TEAMCITY_DATA_DIR/system/caches/git/map で確認できます）。スレッドダンプは、リモートリポジトリからのクローン作成に関する問題の調査に役立ちます。このパラメーターは、スレッドダンプを保存する期間（時間単位）を指定します。

teamcity.server.git.gc.enabled

デフォルト値 : false

サーバーのクリーンアップ中に TeamCity が git gc を実行するかどうかを指定します (ネイティブ git が使用されます)。

teamcity.server.git.executable.path

デフォルト値 : git

サーバー上のネイティブ git 実行可能ファイルへのパス。

teamcity.server.git.gc.quota.minutes

デフォルト値 : 60

git gc を実行する最大時間（分単位）。

teamcity.git.cleanupCron

デフォルト値 : 0 0 2 \* \* ? \*

git-plugin のクリーンアップ時刻を表すクーロン表現(英語)。デフォルトの式では、毎日午前 2 時にクリーンアップが開始されます。

teamcity.git.stream.file.threshold.mb

デフォルト値 : 128

JGit がストリームを使用してオブジェクトをインフレートするしきい値（メガバイト単位）。リポジトリに大きなバイナリファイルがあり、TW-14947(英語) に記載されている症状が見られる場合は、この値を増やしてください。

teamcity.git.buildPatchInSeparateProcess

デフォルト値 : true

Git プラグインは、別のプロセスでパッチをビルドし、false に設定してサーバープロセスでパッチをビルドします。パッチをビルドするには、git-plugin がリポジトリファイルをメモリに読み込む必要があります。メモリ不足にならないように、git-plugin は、しきい値よりも小さいサイズのオブジェクトのみを読み取ります。大きなオブジェクトの場合、ストリームが使用され、遅くなる可能性があります（TW-14947(英語)）。別のプロセスでパッチを構築すると、すべてのオブジェクトがメモリに読み込まれます。パッチプロセスは、個別のフェッチプロセスのメモリ設定を使用します。

teamcity.git.mirror.expiration.timeout.days

デフォルト値 : 7

未使用のリポジトリのクローンがサーバーマシンから削除されるまでの日数。変更の確認や現在のバージョンの取得など、このリポジトリに対して TeamCity 操作がない場合、リポジトリは未使用と見なされます。これらの操作はかなり頻繁に行われるため、7 日間というのはかなり高い値です。

teamcity.git.commit.debug.info

デフォルト値 : false

見つかったコミットごとに追加のデバッグ情報を記録するかどうかを指定します。

teamcity.git.repackIdleTimeoutSeconds

デフォルト値 : 1800

git-repack 操作のアイドルタイムアウトを秒単位で定義します。大規模なリポジトリでは、オブジェクトの再パックに時間がかかるため、このタイムアウトを増やす必要がある場合があります。

teamcity.git.sshProxyType

デフォルト値 : なし

SSH プロキシの種類。サポートされている値: http、socks4、socks5socks4 プロキシはリモートホスト名を解決できないことに注意してください。そのため、UnknownHostException が発生した場合は、socks5 に切り替えるか、TeamCity サーバーマシンの hosts ファイルに git サーバーのエントリを追加してください。

teamcity.git.sshProxyHost

デフォルト値 : なし

SSH プロキシホスト。

teamcity.git.sshProxyPort

デフォルト値 : なし

SSH プロキシポート

teamcity.git.native.sshProxyCmd

デフォルト値 : なし

netcat-openbsd のない Linux マシン上で動作する TeamCity サーバーには、このプロパティを指定してください。この場合、SSH 認証を行う Git VCS ルートで exit code: 128 stderr: nc: invalid option -- 'X' エラーが発生する可能性があります。詳細については、発信 TeamCity サーバー接続にプロキシを使用するセクションの末尾にある注記を参照してください。

teamcity.git.native.sshProxyCmd=ncat --proxy %host:%port --proxy-type http

teamcity.git.connectionRetryAttempts

デフォルト値 : 3

失敗を認める前に、接続をテストし、現在のリポジトリの状態を取得するために、リモートホストへの接続を確立しようとする試行回数。

teamcity.git.connectionRetryIntervalSeconds

デフォルト値 : 4

連続した接続試行間の遅延 (秒単位)。

Git のビルドパラメーター :

teamcity.git.use.native.ssh

デフォルト値 : false

TeamCity がネイティブ SSH 実装を使用するかどうかを指定します。このプロパティは「エージェントによるチェックアウト」モードでのみ有効です。

teamcity.git.idle.timeout.seconds

デフォルト値 : 3600

エージェント側のチェックアウトが使用されている場合の git fetch 操作のアイドルタイムアウト。この間にフェッチプロセスからの出力がない場合、フェッチは終了します。

エージェント側のチェックアウトルールの制限事項

Git プラグインは、 git sparse-checkout (英語) を使用してエージェント上の Git ファイルをチェックアウトします。プラグインは、Git でサポートされる VCS チェックアウトルールのセットを制限する単純なファイルマッピング操作のみを実行できます。

次のルールがサポートされています。

ルールはファイルを再マップしてはならないことに注意してください。つまり、次のルールはサポートされていません : +:dirA/dirA1 => dirA/dirA2

1 つのルートに複数のチェックアウトルールを指定する場合は、それらのチェックアウトディレクトリ (ルールの右側の部分) に共通の親ディレクトリ ([prefix/]) があることを確認してください。エージェント側のチェックアウトではルール +:dirA => [prefix/]dirA のみがサポートされており、[prefix/] はすべてのルールで同じである必要があります。

例:

次のルールはサポートされていないことに注意してください: +:dirA=>[prefix/]dirA/postfix チェックアウトディレクトリパスに [/postfix] を追加し、構成の VCS チェックアウトモードが「エージェント上のファイルを常にチェックアウトする」に設定されている場合、新しいビルドを開始できません。

既知の問題

• teamcity.git.fetch.process.max.memory プロパティが指定されている場合のリポジトリからのフェッチ中の java.lang.OutOfMemoryErrorTeamCity 2019.2 以降、推奨されるアプローチは、このプロパティを無効にして、自動メモリ管理を TeamCity に委譲することです。

• Windows サービスとして実行されている TeamCity はネットワークにマップされたドライブにアクセスできないため、そのようなドライブにある git リポジトリを操作することはできません。これを機能させるには、teamcity-server.bat を使用して TeamCity を実行します。

• JGit でストリームを使用してインフレーションすると、OutOfMemoryError が防止されますが、時間がかかる場合があります（問題に関連する TW-14947(英語) の問題を参照してください）。同様の動作に気付いた場合は、teamcity.git.stream.file.threshold.mb を増やしてみてください。さらに、OutOfMemoryError を防ぐために、TeamCity 専用のメモリの総量を増やすことをお勧めします。