Skip to main content
The TeamCity VCS plugin is community-built. Diversion maintains a fork with fixes that are not in the original, so use the build linked below.

​
Prerequisites

  • Administrator access to your TeamCity server.
  • The Diversion CLI (dv) installed on the TeamCity server. See the quickstart for installation, or CI/CD for the unattended installer.

​
1) Get the plugin

Download teamcity-diversion-vcs.zip from the latest release.

​
2) Install the plugin in TeamCity

Administration → Plugins → Upload plugin zip, then restart the TeamCity server.

​
3) Install and sign in to the Diversion CLI

The plugin runs on the TeamCity server, so dv must be installed and signed in there. If your build steps also call dv, install and sign in on each build agent as well. Note the full path to dv.exe (for example C:\Users\<user>\.diversion\bin\dv.exe) — you need it when configuring the VCS root. How you sign in depends on the account the TeamCity service runs as. Check in services.msc → the TeamCity service → Log On tab:
  • A named user account — open a terminal as that user and run dv login. The browser auth flow completes normally.
  • Local System — open a shell running as the System account (for example psexec -i -s cmd.exe), then run dv login there.
If the server runs as a service account with no interactive session, skip the browser flow and authenticate with an Integration token instead: dv authenticate <token>. See CI/CD for generating one. API access requires the Pro plan or above.
After signing in, confirm it worked: run dv status and read the output, not the exit code. If you see no credentials found for the account. User is logged out, sign in again.

​
4) Give the VCS root its own Diversion workspace

Three directories are in play, and no two of them may be the same path:
  • your own workspace, where you and your team work
  • the VCS root’s Working Directory, which the plugin drives on the TeamCity server
  • the build’s checkout directory, which TeamCity owns on the agent
The VCS root’s Working Directory is a normal Diversion clone that the plugin drives on your behalf. It runs dv commands there to see which commits have landed, and for server-side checkout it reads file contents from it to build the patches TeamCity sends to the agents. This is not where your build runs, and it is not TeamCity’s checkout directory — you create it once, and from then on it belongs to the plugin. Clone your repository to a path nothing else uses, then set that path as the VCS root’s Working Directory in step 5.
Never point the Working Directory at a developer’s workspace. Whenever new commits land on the tracked branch, the plugin runs dv checkout --discard-changes there, so any uncommitted work in that directory is discarded.Never point it at a build’s checkout directory either. TeamCity can wipe and re-fetch that directory, which Diversion then stages as thousands of deleted files on the branch — see Troubleshooting if it happens.

​
5) Configure the Diversion VCS root

In your build configuration, add a new VCS root and select Diversion. Fill in:
  • Repository ID — your Diversion repository ID (dv.repo.…), from dv repo
  • Branch Name — the branch this root monitors, for example main or Development
  • Diversion Executable — the full path noted in step 3, or just dv if it is on the system PATH
  • Working Directory — the dedicated clone from step 4. Required for server-side checkout; leave empty for agent-side checkout.
Each VCS root tracks exactly one branch. To build several branches, create one VCS root per branch, each with its own working directory.

​
6) Turn off automatic checkout if your build steps use dv

If your build steps do their own dv update or dv checkout, TeamCity’s server-side patching is redundant and will fight with them. In the build configuration’s Version Control Settings → Checkout settings, set the checkout mode to Do not checkout files automatically. The VCS root then serves only change detection and triggering, and your build steps own the working directory.

​
7) Add a VCS trigger

Build Configuration → Edit → Triggers → Add new trigger → VCS Trigger TeamCity now queues a build whenever a commit lands on the branch configured in the VCS root.

​
8) Add your build steps

Add a Command Line (or other) build step with your build command. For Unreal Engine this is typically RunUAT.bat BuildCookRun pointing at your .uproject.

​
Troubleshooting

A build fails with Failed to remove checkout directory ... Something still holds files in it open. A clean checkout could not empty the checkout directory because another program holds something in it — commonly an open shell or editor sitting in that folder, or antivirus scanning it. Close whatever is using the directory and run the build again. You installed the plugin from the original repository and something is broken. Builds may not trigger for non-default branches, and agent-side checkout may re-clone on every build or fail with exit code 3. Replace it with the build from step 1 and restart the server. If a build configuration is already stuck, run dv unregister in its checkout directory and delete the directory before building again. The VCS root’s workspace shows thousands of pending deletions. The working directory is also being used as a TeamCity checkout directory — see step 4. The branch is safe as long as the deletions are not committed. Recover with dv checkout <branch> --discard-changes or dv reset -f -all in that directory, then separate the two directories.
Never run dv commit -a in a VCS root working directory. If a build step commits, pass an explicit file list so a pending mass deletion cannot be committed by accident.
Commits are picked up half an hour late. TeamCity slows down a VCS root that keeps failing, so it looks like polling stopped. Most likely the CLI is signed out on the server, or signed in as an account that cannot see the repository — see step 3. Polling recovers on the first successful check. The plugin reports no branches. The CLI is signed out on the server. Re-run dv login as the correct service account (step 3).