TeamCity と Perforce の統合

前提条件

• TeamCity は P4 2017.1 以降の Perforce P4 サーバー / クライアントをサポートします

• TeamCity サーバーマシンに Perforce P4 クライアントをインストールする必要があります。

• Perforce クライアントへのパスを パス 環境変数に追加する必要があります。
  または、 p4 へのフルパスを 内部プロパティteamcity.perforce.customP4Path で設定できます。 プロパティ値には p4 ファイル名を含める必要があります。

Perforce P4 ソースでのビルドの実行

Perforce P4 に保存されているプロジェクトソースでビルドを実行し、この記事で説明されているすべての機能を使用するには、次の 2 つの手順を実行する必要があります。

1. TeamCity で専用プロジェクトを作成します：

   1. 管理 | プロジェクト に移動し、 プロジェクトを作成 をクリックします。
      これにより、プロジェクトが ルートプロジェクト の直下に追加されることに注意してください。 または、他の既存のプロジェクトの下に追加することもできます。

   2. プロジェクトの 名前と ID を入力します。

   3. 作成 をクリックします。

2. Perforce VCS ルートを作成します:

   1. プロジェクト設定を開き、 VCS ルート設定タブに移動します。

   2. VCS ルートを作成 をクリックします。

   3. VCS タイプとして Perforce P4 を選択します。

   4. この記事の説明に従って、ルートの設定を構成します。

プロジェクトと Perforce ルートを構成したら、 ビルド構成の追加とビルドの実行に進むことができます。

Perforce Streams でのビルドの実行

TeamCity は Perforce の ストリーム 内のコミットを監視し、通常の 機能ブランチ と同様に扱うことができます。

Perforce ルート が Stream モードを使用するように構成されている場合、ルート設定で機能ブランチのサポートを有効化できます。 有効化されると、指定されたメインストリームを親に持つすべてのストリームが、TeamCity によって処理される 機能ブランチ のセットに含まれます。 このセットに特定のストリームのみを含めるには、ブランチ仕様を編集してこれらのストリームをフィルターします。 各フィルタールールは新しい行から開始する必要があります。 構文は +|-:stream_name です。 たとえば、 +://stream-depot/* を使用して、 stream-depot デポにあるストリームのみを監視します。ここで、 * (例: マスター) は論理ブランチ名です。 ブランチ仕様で使用するストリームは、メインストリームの子孫である必要があることに注意してください。

TeamCity はタスクストリームも処理できますが、新しいタスクストリームを検出するのは、マージ以外のコミットが行われた場合のみです。

IntelliJ IDE からのパーソナルビルドの実行

IntelliJ ベースの IDE でコードを書く場合、ローカルの変更をメインの Perforce リポジトリにコミットする前に事前テストと事前ビルドを行えます。 リモート実行、 リモートデバッグ、 事前テスト済み遅延コミット に関する共通の手順を参照してください。

リモートの実行 / デバッグ機能はすべてのタイプの VCS に共通ですが、Perforce に固有の追加の便利さがあります。

• リモートで実行されているビルドは Perforce ストリーム上にあります。

• ディポにコミットせずにシェルブされたファイルの変更をテストします。

Perforce のシェルブされたファイルでのビルドの実行

TeamCity では、Perforce の シェルブされたファイル でパーソナルビルドを実行できます。 このようにして、変更されたソースファイルを共通のディポにチェックインする前にビルドしてみることができます。

TeamCity はシェルブされたファイルを次のように処理します：

1. リモートのソースコードはチェックアウトされています（エージェント側については、下記の注記を参照してください）。

2. p4 unshelve -s <specified-changelist> コマンドが呼び出されます。

3. p4 sync を再度実行して、 unshelve ステップによって影響を受けたファイルの最新リビジョンを復元します。

4. p4 resolve -am は変更を自動的にマージし、競合を解決します。 解決されない競合が残っている場合、ビルドは失敗します。

5. 自分だけのカスタムビルドが始まる。

6. ビルドが完了すると、 p4 revert と p4 clean はワークスペースを元の状態に復元し、シェルフから追加されたファイルを削除します。

Perforce の保留ファイルに対してカスタムビルドを 手動で実行 には:

1. 実行 ボタンの横にあるコンテキストメニューをクリックして、 カスタム実行ダイアログを開きます。

2. 個人ビルドオプションとして実行を有効にします。

3. シェルブされたファイルを含む変更リストの ID を入力します。

   

   カンマ区切りで複数の ID を入力すると、単一のビルドで複数の変更リストを処理できます。 この場合、TeamCity は diff の表示時に最終的なファイル内容を表示しません。 これは想定される動作であり、設定ミスやエラーを示すものではありません: ビルドが開始されると、すべての変更がエージェント上で処理され、適用されます。

4. ターゲットの Perforce ルートを選択します。

Perforce の保留中の変更リストの 自動トリガーを設定 には:

1. 構成設定を開き、 トリガー設定タブに移動します。

2. Perforce シェルフトリガータイプの新しいトリガーを追加します。

3. この記事の説明に従って設定を構成します。

ターゲットのシェルブされた変更リストを TeamCity REST API を使用してビルドするには、次の本文を含む POST リクエストを /アプリ/rest/ビルドキュー エンドポイントに送信します：

Swarm 更新 URL

Perforce Helix Swarm テスト更新の URL。 このプロパティはオプションであり、Helix Swarm によってトリガーされるビルドでのみ使用されます。

シェルブされた変更リスト

このプロパティは、保留中の変更リスト番号と有効な VCS ルート外部 ID を指す必要があります。 値は vcsRoot.<外部_id>.シェルブされた変更リスト 形式である必要があります。

このエンドポイントに加えて、バージョン 2024.12 より前に使用可能だった専用の シェルブのビルドを実行 エンドポイントも使用できます。

ビルドタイプ ID

ビルド構成の ID。

VCS ルート ID

関連する VCS ルートの外部 ID。

シェルブされた変更リスト ID

必要な変更リストの ID。

Perforce の TeamCity ワークスペース

Perforce 関連の操作を実行するために、TeamCity サーバーは通常、ワークスペースコンテキストなしで Perforce コマンドを実行します。 たとえば、ワークスペースは、変更の追跡やほとんどのサーバー側の操作には必要ありません。 ただし、特定のケースでは専用のワークスペースを作成する必要があります。

• デフォルトでは、TeamCity はビルドのソースをチェックアウトするために エージェント側チェックアウトモード を使用します。 この場合、専用の Perforce ワークスペースを作成し、対応する p4 sync コマンドを実行してソースを取得します。

• Perforce VCS ルートを使用して バージョン管理されたプロジェクト設定を保存します。

• 機能ブランチとしての Perforce ストリームを使用します。 この場合、TeamCity はタスクストリームを正しく処理するために、Perforce サーバー上にワークスペースを作成します。

TeamCity が Perforce でワークスペースを作成し、それらを操作する方法については、 この記事 を参照してください。

Perforce サーバーでのポストコミットフックの構成

デフォルトでは、TeamCity は VCS リポジトリ内の変更を検出するためにポーリング方式を使用します。 Perforce サーバーに定期的に要求を送信して、新しいリビジョンを検出します。 数百の VCS ルートがある大規模なインストールでは、Perforce サーバーと TeamCity の両方に顕著な負荷がかかる可能性があります。 バックグラウンドポーリングを回避するために、Perforce サーバーにコミット後フックを設定できます。 このフックは、変更が利用可能な場合にのみ変更のチェックを開始するよう TeamCity に通知します。

TeamCity は、Perforce サーバーに保存する必要がある専用のフックスクリプトを提供します。 詳細な手順については、 こちらを参照してください。

Perforce ソースにラベルを付ける

TeamCity は Perforce プロジェクトソースにカスタムラベルを割り当てることができます。 適用されたラベルとそのステータスのリストは、 ビルド結果 の 変更 タブに表示されます。

ビルド構成の自動ラベル付けを構成するには:

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

2. VCS ラベリング機能を追加します。

3. ラベルを付ける Perforce GCS ルートを選択します。

4. こちら で説明されているラベル付けパターンを指定します。

Perforce サービスメッセージ

パフォーマンスプロジェクトと連携した パーソナルビルドは、最後の「個人の変更を元に戻す」段階で失敗する可能性があります。 これは通常、この段階が始まる前にコードソースチェックアウトディレクトリが使用できなくなった場合に発生します (たとえば、 Bootstrap ビルドステップによってマウントされ、最後のビルドステップの後に自動的にアンマウントされた場合など)。

このような場合、ビルドステップ実行中に、TeamCity が通常行うよりも早く個人の変更を元に戻す必要があります。 これを行うには、最後のビルドステップ中に次の サービスメッセージを送信します。