How To...

In this section:

Integrate with an issue tracker

Dedicated support for YouTrack, Jira, Bugzilla. You can also turn any issue tracker issue ID references in change comments into links. Please see Mapping External Links in Comments for configuration instructions.

Share the build number for builds in a chain build

Suppose you have build configurations A and B that you want to build in sync: use same sources and take the same build number.
Solution:
Create a build configuration C and create snapshot dependencies A on C and B on C. Then set the Build number format in A and B to:

Where <btID> is the internal ID of the build configuration C. Please refer to the Build Configuration page for description of how to determine build configuration ID.

More on dependency properties.

We plan to provide more option on build number sharing. Please watch/comment on TW-7745.

Use an external tool that my build relies on

Assume, to run a build you need to use specific external tool to be installed on a build agent. To solve the problem, you have the following options:

• Check in the tool into the version control and use relative paths.
• Create a separate build configuration with a single "fake" build which would contain required files as artifacts, then, use artifact dependencies to send files to the target build.
• Install and register the tool in TeamCity:
  1. Install the tool on all the agents that will run the build.
  2. Add env. or system. property into buildAgent.properties file (or add environment variable to the system).
  3. Add agent requirement for the property in the build configuration.
  4. Use the property in the build script.
• Add environment preparation stage into the build script to get the tool form elsewhere.

Install Multiple Agents on the Same Machine

If you want to install several TeamCity build agents on the same machine, please consider the following:

• TeamCity will work with the agents the same as if they are installed on different machines
• The agents builds running on the agents should not conflict by any resource (common disk directories, OS processes, OS temp directories)
• Depending on the hardware and the builds you may experience degraded builds performance. e.g. ensure there are no disk, memory, CPU bottlenecks when several builds are run at the same time.

For installation instructions, refer to Setting up and Running Additional Build Agents.

Change Server Port

See corresponding section in server installation instructions.

Make temporary build files erased between the build

Update your build script to use path stored in ${teamcity.build.tempDir} (Ant's style name) property as the temp directory. TeamCity agent creates the directory before the build and deletes it right after the build.

Retrieve Administrator password

On the first start TeamCity displays Administrator Setup page. TeamCity installation should always have a user with System Administrator role in the current authentication scheme.

In rare cases on user authorization scheme switch there can be no System Administrator on the system. In this case you may setup one as follows:

1. access directly the URL: http://<your_TeamCity_server>/setupAdmin.html
2. create new account (it should not match any existing user account in the system) for the System Administrator role.

If you forgot Administrator password and use internal database, you can reset the password using the instructions.

Ho do I clear build queue if it got too many builds due to a configuration error

Try pausing the build configuration that has the builds queued. On build configuration pausing all its builds are removed form the queue.

Watch Several TeamCity Servers With Windows Tray Notifier

TeamCity Tray Notifier is used normally to watch builds and receive notifications from a single TeamCity server.

In situations, when you have more than one TeamCity server, and want to monitor them with Windows Tray Notifier simultaneously, you need to start a separate instance of Tray Notifier for each of the servers from the command line with the /allowMultiple option:

• navigate to TeamCity Tray notifier installation folder (by default, it's C:\Program Files\JetBrains\TeamCity and run the command:
  Optionally, for each of the Tray Notifier instances you can specify explicitly the URL of the the server to connect to with the /server option. Otherwise, for each further tray notifier instance you will need to log out and change server's URL via UI.

See also details in the issue tracker.

Estimate hardware requirements for TeamCity

The hardware requirements differ for the server and the agents.

The agent hardware requirements are basically determined by the builds that are run. Running TeamCity agent software introduces requirement for additional CPU time (but it can usually be neglected comparing to the build process CPU requirements) and additional memory: about 150Mb.

The server hardware requirements depend on the server load. The load on the server depends significantly on the type of the builds and server usage, so here are only some general guidelines.

If you face some Performance issues, they should probably be investigated and addressed individually. e.g. if builds generate too much data, server disk system might need upgrade both by size and speed characteristics.

The load on the server depends on:

• the number of build configurations
• the number of builds in the history
• the number of the builds running daily
• the amount of data generated by the builds (size of the build log, number and output size of unit tests, number of inspections and duplicates hits etc.)
• the number of agents and their utilization percentage
• the number of users having TeamCity web pages open
• the number of users logged in from IDE plugin
• the number and type of VCS roots as well as checking for changes interval for the VCS roots. VCS checkout mode is relevant too: server checkout mode generates greater server load. Specific types of VCS also affect server load, but they can be roughly estimated based on native VCS client performance.
• the number of changes detected by TeamCity per day in all the VCS roots

Based on our experience, a modest hardware like 3.2 dual core CPU, 3.2Gb memory under Windows, 1Gb network adapter can provide acceptable performance for the setup:

• 60 projects and 300 build configurations, (with one forth being active and running regularly)
• more then 300 builds a day
• about 2Mb log per build
• 50 build agents
• 50 web users and 30 IDE users
• 100 VCS roots (mainly Perforce and Subversion using server checkout), average checking for changes interval is 120 seconds
• more then 150 changes per day
• the database (MySQL) is running on the same machine, main TeamCity process has -Xmx1100m -XX:MaxPermSize=120m JVM settings.

HDD free space requirements are mainly determined by the number of builds stored on the server and the artifacts size/build log size in each.

If the builds generate large number of data (artifacts/build log/test data), using fast hard disk for storing .BuildServer/system directory and fast network between agents and server are recommended.

The general recommendation for deploying large-scale TeamCity installation is to start with a reasonable hardware and add more projects to the server gradually, monitoring the performance characteristics and deciding on necessary hardware or software improvements. Anyway, best administration practices are recommended like keeping adequate disk defragmentation level, etc.

Setup TeamCity in Replication/Clustering Environment

TeamCity does not provide specific support for any of replication/high availability or clustering solutions.

When setting up TeamCity in a replication environment please note that TeamCity uses both database and file storage to save data. You can browse through TeamCity Data Backup and TeamCity Data Directory pages in to get more information on TeamCity data storing.

Basically, both TeamCity data directory on disk and database that TeamCity uses should remain in a consistent state and thus should be replicated together.

Only single TeamCity server instance should use database and data directory at any time.

Move TeamCity projects from one server to another.

Generally, this is not supported. For addressing simple cases manually, please see a comment.

Automatically create or change TeamCity build configuration settings

If you need a level of automation and web administration UI does not suite your needs, there are two possibilities:

• change configuration files directly on disk (see more at TeamCity Data Directory)
• write a TeamCity Java plugin that will perform the tasks using open API.

Attach Cucumber reporter to Ant build

If you use Cucumber for Java applications testing you should run cucumber with --expand and special --format options. More over you should specify RUBYLIB environment variable pointing on necessary TeamCity Rake Runner ruby scripts:

If you are launching Cucumber tests using Rake build language TC will add all necessary cmdline parameters and env. variables automatically.
P.S: This tip works in TeamCity version >= 5.0.

Get last successful build number

Use URL like this:

http://<your TeamCity server>/app/rest/buildTypes/id:<internal ID of build configuration>/builds/status:SUCCESS/number

This functionality is provided by REST API