> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Diversion で TeamCity をセットアップする
> TeamCity 用の Diversion VCS プラグインをインストール・設定して、コミットが自動的にビルドをトリガーするようにします。
TeamCity VCS プラグインはコミュニティ製です。Diversion はオリジナルには含まれていない修正を加えた[フォーク](https://github.com/bedmonds13/teamcity-diversion)を保守しているため、以下でリンクされているビルドを使用してください。
## 前提条件
* **TeamCity サーバー** への管理者アクセス。
* TeamCity サーバーにインストール済みの **Diversion CLI**（`dv`）。インストール方法は[クイックスタート](/ja/quickstart)を参照するか、非対話型インストーラーについては [CI/CD](/ja/ci-cd#install-the-diversion-client-authenticate-it-and-clone-your-repo) を参照してください。
***
## 1) プラグインを入手する
[最新リリース](https://github.com/bedmonds13/teamcity-diversion/releases/latest)から `teamcity-diversion-vcs.zip` をダウンロードします。
さらに **Java 17+**（[Adoptium](https://adoptium.net)）と **Maven**（[ダウンロード](https://maven.apache.org/download.cgi)。`bin/` フォルダーをシステムの `PATH` に含めて展開してください）が必要です。
```bash theme={null}
git clone https://github.com/bedmonds13/teamcity-diversion
cd teamcity-diversion
mvn clean package
```
ビルドされたプラグインは `build/target/teamcity-diversion-vcs.zip` にあります。
***
## 2) TeamCity にプラグインをインストールする
**Administration → Plugins → Upload plugin zip** を開いてアップロードし、TeamCity サーバーを再起動します。
***
## 3) Diversion CLI をインストールしてサインインする
プラグインは **TeamCity サーバー** 上で動作するため、そこに `dv` がインストールされ、サインインされている必要があります。ビルドステップ内でも `dv` を呼び出す場合は、各ビルドエージェントにもインストールしてサインインしてください。
`dv.exe` のフルパス（例: `C:\Users\\.diversion\bin\dv.exe`）を控えておきます。VCS ルートを設定する際に必要になります。
サインインの方法は、TeamCity サービスを実行しているアカウントによって異なります。`services.msc` で TeamCity サービスの **Log On** タブを確認してください。
* **名前付きユーザーアカウント** — そのユーザーとしてターミナルを開き、`dv login` を実行します。ブラウザの認証フローが通常どおり完了します。
* **Local System** — System アカウントとして動作するシェル（例: `psexec -i -s cmd.exe`）を開き、そこで `dv login` を実行します。
サーバーが対話セッションを持たないサービスアカウントとして動作している場合は、ブラウザフローをスキップし、代わりに Integration トークンで認証します: `dv authenticate `。トークンの生成方法は [CI/CD](/ja/ci-cd#generate-an-api-token) を参照してください。API アクセスには [Pro 以上のプラン](https://www.diversion.dev/pricing) が必要です。
サインイン後は正常に完了したことを確認してください。`dv status` を実行し、終了コードではなく出力を読みます。`no credentials found for the account. User is logged out` と表示された場合は、もう一度サインインしてください。
***
## 4) VCS ルート専用の Diversion ワークスペースを用意する
関係するディレクトリは 3 つあり、どの 2 つも同じパスであってはいけません。
* **あなた自身のワークスペース**。あなたとチームが作業する場所です。
* **VCS ルートの Working Directory**。TeamCity サーバー上でプラグインが操作します。
* **ビルドの checkout directory**。エージェント上で TeamCity が管理します。
VCS ルートの **Working Directory** は、プラグインがあなたに代わって操作する通常の Diversion クローンです。そこで `dv` コマンドを実行して、どのコミットが到着したかを確認します。サーバーサイドチェックアウトでは、そこからファイル内容を読み取り、TeamCity がエージェントに送るパッチを組み立てます。ここはビルドが実行される場所でも、TeamCity のチェックアウトディレクトリでもありません。一度作成すれば、以降はプラグインが所有します。
他の何にも使われていないパスにリポジトリをクローンし、そのパスを手順 5 で VCS ルートの **Working Directory** に設定します。
**Working Directory を開発者のワークスペースに向けないでください。** 追跡対象ブランチに新しいコミットが到着すると、プラグインはそこで `dv checkout --discard-changes` を実行するため、そのディレクトリ内の未コミットの作業はすべて破棄されます。
**ビルドの checkout directory にも向けないでください。** TeamCity はそのディレクトリをワイプして再フェッチすることがあり、その結果 Diversion はブランチ上で何千もの削除済みファイルとしてステージします。発生した場合は [トラブルシューティング](#troubleshooting) を参照してください。
***
## 5) Diversion の VCS ルートを設定する
ビルド構成で新しい VCS ルートを追加し、**Diversion** を選択します。次を入力します。
* **Repository ID** — Diversion のリポジトリ ID（`dv.repo.…`）。`dv repo` から取得できます。
* **Branch Name** — この VCS ルートが監視するブランチ。例: `main` や `Development`。
* **Diversion Executable** — 手順 3 で控えたフルパス。システムの `PATH` に通っている場合は単に `dv` でも構いません。
* **Working Directory** — 手順 4 で用意した専用クローン。サーバーサイドチェックアウトでは必須です。エージェントサイドチェックアウトでは空のままにします。
各 VCS ルートは 1 つのブランチのみを追跡します。複数のブランチをビルドするには、それぞれ独自の Working Directory を持つ VCS ルートをブランチごとに 1 つ作成します。
***
## 6) ビルドステップで `dv` を使う場合は自動チェックアウトを無効にする
ビルドステップが独自に `dv update` や `dv checkout` を実行する場合、TeamCity のサーバーサイドパッチ適用は重複しており、それらと競合します。
ビルド構成の **Version Control Settings → Checkout settings** で、チェックアウトモードを **Do not checkout files automatically** に設定します。VCS ルートは変更検出とトリガーのみを担当し、Working Directory はビルドステップが所有します。
***
## 7) VCS トリガーを追加する
**Build Configuration → Edit → Triggers → Add new trigger → VCS Trigger**
これで、VCS ルートで設定したブランチにコミットが到着するたびに、TeamCity がビルドをキューに追加します。
***
## 8) ビルドステップを追加する
Command Line（またはその他）のビルドステップを追加し、ビルドコマンドを設定します。Unreal Engine の場合、通常は `.uproject` を指定した `RunUAT.bat BuildCookRun` になります。
***
## トラブルシューティング
**ビルドが `Failed to remove checkout directory ... Something still holds files in it open` で失敗する。**
別のプログラムがそのフォルダー内の何かを保持しているため、クリーンチェックアウトが checkout directory を空にできませんでした。よくある原因は、そのフォルダーで開かれているシェルやエディター、またはそこをスキャンしているアンチウイルスです。そのディレクトリを使っているものをすべて閉じてから、ビルドを再実行してください。
**元のリポジトリからプラグインをインストールしたところ、何かが壊れている。**
デフォルト以外のブランチでビルドがトリガーされない場合や、エージェントサイドチェックアウトがビルドごとに再クローンしたり `exit code 3` で失敗したりする場合があります。[手順 1](#1-プラグインを入手する) のビルドで置き換え、サーバーを再起動してください。すでにビルド構成が動かなくなっている場合は、その checkout directory で `dv unregister` を実行し、ディレクトリを削除してからビルドし直してください。
**VCS ルートのワークスペースに数千件の削除保留が表示される。**
Working Directory が TeamCity の checkout directory としても使われています。手順 4 を参照してください。削除がコミットされない限りブランチは安全です。そのディレクトリで `dv checkout --discard-changes` または `dv reset -f -all` を実行して復旧させ、その後 2 つのディレクトリを分離してください。
VCS ルートの Working Directory では絶対に `dv commit -a` を実行しないでください。ビルドステップがコミットする場合は、明示的なファイルリストを渡して、保留中の大量削除が誤ってコミットされないようにしてください。
**コミットが 30 分ほど遅れて拾われる。**
TeamCity は失敗が続く VCS ルートの速度を落とすため、ポーリングが停止したように見えます。多くの場合、サーバー上で CLI がサインアウトしているか、リポジトリを参照できないアカウントでサインインしています。手順 3 を参照してください。ポーリングは最初に成功したチェックで回復します。
**プラグインがブランチを 1 つも表示しない。**
サーバー上で CLI がサインアウトしています。正しいサービスアカウントとして `dv login` を再実行してください（手順 3）。