VCS Worker

Interaction with version control (VCS) servers is one of the resource-heavy parts of TeamCity. Until TeamCity 8.0, VCS operations could only be performed by TeamCity server itself. In version 8.0, we introduced an option to execute VCS operations in a separate VCS Worker service, which can run on a separate machine; moreover, you can use several VCS Workers running on multiple machines to offload the server.

For example, you can route all Git VCS traffic through one VCS Worker and all Subversion traffic through another. Furthermore, you can run the TeamCity server on Linux and still be able to use TFS by running a VCS Worker on a Windows machine. With large installations, VCS Worker(s) installed on separate machines should noticeably decrease the TeamCity server load.

By default, VCS Workers are disabled and TeamCity behaves as usual, i.e. performs all VCS operations from the main server process.

A VCS Worker supports Team Foundation Server, Perforce, Subversion, Git, and Mercurial.

Installing VCS Worker

• Stop the TeamCity Server
• Download the VCS Worker archive and save it to your <TeamCity Data Directory>/plugins folder.
• Start the TeamCity Server
• In the TeamCity Web UI, go to the Administration page, select VCS Worker in the Integrations section and download vcs-worker.zip.
• Unpack the vcs-worker.zip on the target machine (The BUILD_<XXX> is the VCS Worker version. Make sure it is the same as the TeamCity server version you are running)
• Open port 9888 in the firewall
• Set the JAVA_HOME environment variable to point at the installed Java JVM 1.6+
• Start the VCS Worker using{{<vcs-worker>/bin/vcs-server.bat start}} or <vcs-worker>/bin/vcs-server.sh start
• Make sure you can open the VCS Worker URL from the TeamCity server using ping or a web browser (e.g. http://vcs-worker-host:9888)
• Copy <TeamCity data directory>/config/vcs-worker.properties.dist to vcs-worker.properties
• Open <TeamCity data directory>/config/vcs-worker.properties
• Uncomment worker.1.url line: (remove #) and specify the worker URL, e.g. http://vcs-worker-host:9888
• The TeamCity server restart is not required. You should be able to see the information about a connected worker via http://your-teamcity-server/admin/admin.html?item=vcsWorkerTab.

Configuring Worker

You can modify a number of settings for your VCS Worker: check <vcs-worker>/conf/vcs-worker.properties.dist for all available options.

• Open <TeamCity data directory>/config/vcs-worker.properties
• Uncomment required lines (remove #) and configure the settings
• Restart the VCS Worker to apply the changes.

Running Several VCS Workers

• Install another VCS Worker on a different machine
• Edit <TeamCity data directory>/config/vcs-worker.properties by adding more workers, e.g. add the worker.2.url=http://second-worker:9888 line
• If needed, use the worker.1.vcsTypes and worker.2.vcsTypes settings to assign different VCS types to different workers
• If needed, you can split the VCS roots of the same type among several workers: e.g. worker.1.vcsRootName=.TeamCity. will route all requests for VCS roots with "TeamCity" in the name to the specified worker
• Save the file, no restart is required. All connected workers will be listed under the VCS Worker tab in the "Administration" section (http://your-teamcity-server/admin/admin.html?item=vcsWorkerTab).

TeamCity uses round-robin selection of VCS Workers if there are several VCS Workers available to serve an operation. Additional filters can be configured: see the <vcs-worker>/conf/vcs-worker.properties.dist file for all available options.