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

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.build.checkoutDir.expireHours システムプロパティで変更できます）。チェックアウトディレクトリが削除され、このディレクトリが Perforce ワークスペースに関連付けられている場合、このワークスペースも削除されます。Perforce ワークスペースのクリーンアップは、 buildAgent.properties ファイル内の teamcity.perforce.workspace.cleanup=false 設定、またはルートプロジェクト構成パラメーターとしてサーバーレベルでグローバルに無効にすることができます。

Perforce 接続設定

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

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

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

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

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

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

VCS ルート設定

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

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

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

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

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

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

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

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

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

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

Perforce 同期 -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_workspace_name> flush <changelist_revision> コマンドを実行して、ワークスペースに必要なソースがすべてすでに存在していることを Perforce サーバーに伝えます。

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

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

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