TeamCity での Perforce ワークスペースの処理

Perforce ワークスペースのお名前

作成されたワークスペースの名前は、 TC_p4_ 接頭辞で始まります。 機能ブランチをサポートするために、Perforce サーバー側で作成されたワークスペースには、 TC_p4_server_ 接頭辞が付きます。

ビルド構成で エージェント側のチェックアウトを使用する場合は、次のようにワークスペース名を変更できます。

• teamcity.perforce.workspace.prefix 構成パラメーターを使用して、ワークスペース名の接頭辞を追加します。

• ワークフローで特定のワークスペース名パターンが必要な場合に備えて、カスタムワークスペース名を設定します。 これを行うには、 vcsroot.<VCSRootExternalID>.p4client パラメーターを設定します。 カスタムワークスペースのお名前が指定されている場合、TeamCity はチェックアウト前に、対応する VCS ルート設定に従ってワークスペースを更新します (たとえば、VCS ルートでストリームサポートが有効化されている場合は、関連するストリームパラメーターを適用します)。 クラウドエージェントでチェックアウト済みソースを再利用 も参照してください。

ワークスペース名には、ビルドエージェント名と、チェックアウトディレクトリおよび（オプションで）チェックアウトルールからビルドされたハッシュ値も含まれます。

Perforce ワークスペースパラメーター

エージェント側チェックアウトを使用すると、TeamCity はチェックアウトプロセス中に作成された Perforce ワークスペースを表す環境変数を提供します。

チェックアウトに複数の Perforce VCS ルートが使用される場合、ビルドの VCS ルートのリストにある 最初 の VCS ルートに対して変数が作成されます。

• P4USER — vcsroot.<VCS_root_ID>.user パラメーターと同じです。

• P4PORT — vcsroot.<VCS_root_ID>.port パラメーターと同じです。

• P4CLIENT — vcsroot.<VCS_root_ID>.p4client パラメーターと同じで、エージェント上に生成された P4 ワークスペースの名前。

これらの変数は、チェックアウト後にカスタム Perforce コマンドを実行するために使用できます。 例: PerforceTest VCS ルートのポートにアクセスできるようにするには、プロジェクトまたはビルド構成設定で env.P4PORT=%vcsRoot.PerforceTest.port% 環境変数を定義します。

ワークスペースの削除

Perforce ワークスペース(英語)は、ディポ内のファイルのサブセットをミラーリングした、ユーザーマシン上のファイルセットです。 TeamCity はエージェントマシンと Perforce サーバー上にワークスペースを自動的に作成します。 時間の経過とともに、これらのワークスペースはサーバー / エージェントマシン上でかなりのリソースを消費する可能性があるため、定期的にクリアすることをお勧めします。

デフォルトの削除メカニズム

デフォルトでは、TeamCity は次の場合に エージェント Perforce ワークスペースを削除します:

• バージョン管理された設定がコミットされた直後（コミットごとにワークスペースが作成されます）。

• エージェント側チェックアウトの場合 - クリーンチェックアウトが実行されたとき (この場合、TeamCity は p4 sync -f も実行します。詳細は 以下を参照してください)。

• エージェントプロセスのバックグラウンド（ビルド間）で、現在のエージェントに関連付けられたワークスペースに存在しないワークスペースディレクトリが検出された場合。 TeamCity エージェントは、未使用の チェックアウトディレクトリのクリーンアップを実行します (デフォルトのタイムアウトは 8 日で、 system.teamcity.ビルド.チェックアウトディレクトリ.有効期限時間 システムプロパティで変更できます)。 チェックアウトディレクトリが削除され、このディレクトリが Perforce ワークスペースに関連付けられている場合、このワークスペースも削除されます。 Perforce ワークスペースのクリーンアップは、 ビルドエージェント.プロパティ ファイル内の teamcity.perforce.workspace.cleanup=false 設定、またはルートプロジェクト 構成パラメーターとしてサーバーレベルでグローバルに無効にすることができます。

Perforce 接続設定

7 日以上非アクティブな TeamCity で生成されたワークスペースを自動的にクリーンアップするには、 Perforce 管理者アクセスの接続設定で Perforce ワークスペースを自動的に除去 オプションを有効にします。 ワークスペースは定期的に データのクリーンアップで削除されます。

• この接続を所有するプロジェクトとそのサブプロジェクト内のすべてのビルド構成に影響します。

• Perforce ワークスペースを自動的に除去 オプションの状態に関係なく、サーバーワークスペースは自動的に削除されます。

• TeamCity クラウドエージェントによって作成されたエージェントワークスペース（名前が TC_p4 プレフィックスで始まるもの）は、対応する設定が有効になっている場合に削除されます。 ベアメタルエージェントによって作成されたワークスペースには影響しません。

• 接続設定に資格情報を入力したユーザーは、 「管理者」権限(英語)を持っている必要があります。

• クラウドエージェントのプロパティに teamcity.perforce.keepWorkspaces=true プロパティを 追加して 、このエージェントの自動ワークスペースを維持し、定期的なクリーンアップから除外することができます。

VCS ルート設定

ビルドの完了後に TeamCity で生成されたワークスペースを自動的にクリーンアップするには、 Perforce VCS ルート設定で Perforce ワークスペースを自動的に除去 オプションを有効にします。

• この VCS ルートが接続されているビルド構成にのみ影響します。

• ベアメタルとクラウドの両方の TeamCity エージェントで、エージェントワークスペースを削除します。

• ビルドが完了するとワークスペースは削除され、新しいビルドごとにクリーンチェックアウトが強制されます。

• この VCS ルートオプションが有効になっている場合、 teamcity.perforce.keepWorkspaces=true プロパティはエージェントワークスペースの削除を妨げません。

ワークスペースを手動で削除する

構成 アクション メニューの Perforce ワークスペースを削除… 項目をクリックして、1 回限りのクリーンアップを実行します。

• このアクションにより、エージェントとサーバーの両方のワークスペースをクリアできます。

• サーバーワークスペースをクリアするには、Perforce ストリームへのパスを入力する必要があります。

• エージェントワークスペースをクリアすると、非アクティブ期間のしきい値（日数）を設定できます。 この制限を超えたワークスペースは削除されます。

Perforce Sync -f とワークスペースの再利用

エージェント側チェックアウトを使用すると、TeamCity はエージェントのチェックアウトディレクトリに紐付けられたワークスペースを作成します。 チェックアウトは、増分 p4 sync コマンド（個人用ビルドと非個人用ビルドの両方）を使用して実行されます。

VCS ルートが p4 sync -p を使用するように構成されている場合、TeamCity は常にこのコマンドを実行してソースをチェックアウトします。

通常、各 クリーンチェックアウトビルドでは、ソースのクリーンアップを伴う p4 sync -f コマンドが実行されます。 Perforce エージェントのチェックアウトについては、以下に説明する例外があります。

クラウドエージェントでチェックアウト済みソースを再利用

新しい TeamCity クラウドエージェントごとにクリーンチェックアウトを回避するには、コードソースを含む永続ストレージをエージェントのチェックアウトディレクトリにコピーまたはマウントできます。 ただし、Perforce はワークスペース、エージェントの IP アドレスと名前、エージェントに保存されているリビジョン、その他のデータを追跡するため、新しいクラウドエージェントでビルドを実行すると、 p4 sync 操作によって既存のソースファイルが無視され、クリーンチェックアウトが行われます。

これを防止し、永続ストレージからソースを再利用するには、次の手順を実行します。

1. クリーンチェックアウトを明示的に無効にするには、ビルド構成に teamcity.agent.failBuildOnCleanCheckout=ignoreAndContinue パラメーターを追加します。

2. チェックアウトの開始前にワークスペースを調整するには、 Bootstrap の歩数(英語)を有効にします。

3. 1 つまたは複数のコマンドラインまたはスクリプトステップを構成に追加し、 ブートストラップ中に実行 オプションを確認します。 これらのブートステップでは次のことを行う必要があります。

   • ビルドチェックアウトディレクトリが永続ストレージを指しており、このストレージに必要なすべてのソースが正しいリビジョンでチェックアウトされていることを確認します。

   • p4 -c <p4_ワークスペース名> flush <チェンジリスト_リビジョン> コマンドを実行して、ワークスペースに必要なソースがすべてすでに存在していることを Perforce サーバーに伝えます。

   • カスタムワークスペース名を必要な値に設定します。 これを行うには、 vcsroot.<VCSRootExternalID>.p4client プロパティに新しい値を割り当てる setParameter サービスメッセージを送信します。

     echo "##teamcity[setParameter name='vcsroot.P4_ExternalVCSRootID.p4client' value='customP4ClientName']"

これらのブートストラップステップを用意すると、TeamCity は P4 クライアント仕様を更新し、 p4 sync コマンドを実行して、フラッシュされた <チェンジリスト_リビジョン> と現在のビルドに関連付けられたリビジョンの間の変更のみを取得するチェックアウトを実行します。