Skip to end of metadata
Go to start of metadata
You are viewing documentation of TeamCity 6.5.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.

Table of Contents

Under construction

In this section:

Introduction to Continuous Integration

According to Martin Fowler, "Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible." To learn more about continuous integration basics, please refer to Martin Fowler’s article.

TeamCity and Continuous Integration

TeamCity is a user-friendly continuous integration (CI) server for developers and build engineers that is easy to set up and free of charge for small and medium teams. With TeamCity you can:

  • Run parallel builds simultaneously on different platforms and environment
  • Optimize the code integration cycle and be sure you never get broken code in the repository
  • Detect hanging builds
  • Review on-the-fly test results reporting with intelligent tests re-ordering
  • Use over 600+ automated server-side inspections for Java, JSP, JavaScript and CSS
  • Run code coverage and duplicates finder for Java and .NET
  • Customize statistics on build duration, success rate, code quality and custom metrics
  • and much more.

Refer to the page to learn more about major TeamCity features.
The complete list of supported platforms and environment can be found here.

TeamCity Architecture

Unlike some build servers, TeamCity has distributed build grid architecture, which means that TeamCity build system comprises of the server and a "farm" of Build Agents which run builds and altogether make up the so-called Build Grid.

Basically a Build Agent is a piece of software that actually executes a build process. It is installed and configured separately from the TeamCity server. Although you can install an agent on the same computer as the server, we recommend to install it on a different machine for a number of reasons, first of all, for the sake of server performance.

TeamCity's Build Agents can have different platforms, operating systems and pre-configured environments that you may want to test your software on. Different types of tests can be run under different platforms simultaneously so the developers get faster feedback and more reliable testing results.

While build agents are responsible for actually running builds, TeamCity server's job is to monitor all the connected build agents, distribute queued builds to the agents based on compatibility requirements and report the results. The server itself runs neither builds nor tests.

Since there is more than one participant involved into build process, it may not be clear how the data flows between server and agent, what is passed to agents, how and when TeamCity gets the results, and so on. Let's sort this out by considering a simple case of build lifecycle in TeamCity.

Build Lifecycle in TeamCity

To demonstrate build lifecycle in TeamCity we need to introduce another important term – Version Control System:


A Version Control System (VCS) is a system for tracking the revisions of the project source files. It is also known as SCM (source code management) or a revision control system.

Naturally, VCS, TeamCity server and build agent are three essential components required to create a build. Now, let's take a look at the data flow between them during a simple build lifecycle.

First of all, a build process is initiated by TeamCity server when certain condition is met, for example TeamCity has detected new changes in your VCS. In general, there is a number of such "conditions" which can trigger a build, but right now they are of no interest to us. To launch a build TeamCity server tries to select the fastest agent based on the history of similar builds, and of course it selects an agent with appropriate environment. If there's no idle build agents among the compatible agents, the build is placed to the build queue, where it waits to be assigned to a particular agent. Once the build is assigned to a build agent, the build agent has to get the sources to run on.

At this point, TeamCity provides two possible ways how the build agent can get sources needed for the build:

  • Server-side Checkout
  • Agent-side Checkout

Server-side checkout
If server-side checkout is used, TeamCity server exports the required sources and passes them to the build agent. Since the build agent itself doesn't interact with your version control system, you don't need to install VCS client on agents. However, since sources are exported rather than checked out, no administrative data is stored in the file system and build agent cannot perform version control operations (like check in or label or update). TeamCity optimizes communications with the VCS servers by caching the sources and retrieving from the VCS server only the necessary changes: TeamCity server sends to the agent incremental patches to update on the agent only the files changed since the last build.

Agent-side checkout
If agent-side checkout is used, the build agent itself checks out the sources before the build. Agent-side checkout frees more server resources and provides the ability to access version control-specific directories (.svn, CVS); that is, the build script can perform VCS operations (like check-ins into the version control). Note, that agent-side checkout is supported not for all VCSs.

When build agent has all the required sources, it starts to execute so called build steps which are parts of the build process itself. Each step is represented by particular Build Runner, which in its turn is a part of TeamCity that provides integration with a specific build tool (like Ant, Gradle, MSBuild, etc), testing framework (e.g. NUnit), or code analysis engine. Thus in a single build you can sequentially invoke test tools, code coverage, and, for instance, compile your project.

While the build steps are being executed, build agent sends all the log messages, test reports, code coverage results and so on to the TeamCity server on the fly, so you can monitor the build process in real time.

After finishing the build, build agent sends to the server so-called build artifacts, these are the files produced by a build, for example, installers, WAR files, reports, log files, etc, when they become available for download.

 Related Documentation Pages

Configuring Your First Build in TeamCity

To configure your first build in TeamCity, perform following simple steps:

 1. Create a project (click to expand)

Start working with TeamCity by creating a project: a project is a collection of your build configurations. It allows you to organize your own projects and adjust security settings: you can assign users different permissions for each project.

Just click the Create Project link, then specify project's name and add some optional description.

 2. Create a build configuration (click to expand)

When you have created a project, TeamCity suggests to populate it with a build configuration:

Build Configuration in TeamCity is a number of settings that describe a class of builds of a particular type, or a procedure used to create builds. To configure a build you need to create build configuration, so click the add a build configuration link. Specify general settings for your build configuration, like:

  • Build configuration name
  • Build number format: each build in TeamCity has a build number, which is a string identifier composed according to the pattern specified here. Learn more. You can leave the default value here, in which case build number format will be maintained by TeamCity and will be resolved into a next integer value on each new build start. The counter you can specify in the Build counter field.
  • Atrifact paths: if your build produces installers, WAR files, reports, log files, etc. and you want them to be published on the TeamCity server after finishing build, specify here paths to such artifacts. Learn more.

If needed, specify when build should be considered as failed and click the VCS Settings button to proceed.

 3. Specify sources to be build (click to expand)

To be able to create a build TeamCity has to know where the source code resides, thus setting up VCS parameters is one of the mandatory steps during creating a build configuration in TeamCity.
At the Version Control Settings page, TeamCity suggests to create and attach new VCS Root.


VCS root is a collection of VCS settings (paths to sources, login, password, and other settings) that defines how TeamCity communicates with a version control (SCM) system to monitor changes and get sources for a build.

Each build configuration has to have at least one VCS root attached to it, however if your project resides in several version control systems you can create as many VCS Roots to it as you need. For example, if you store part of your project in Perforce, and the rest in Git, you need to create and attach 2 VCS roots - one for Perforce, another for Git. Learn more about configuring different VCS roots.

After you have created a VCS root, you can instruct TeamCity to exclude some directories from checkout, or map some paths (copy directories and all their contents) to a location on build agent different from the default. This can be done by means of checkout rules:

Refer to the VCS Checkout Rules for details.

Also, specify whether you want TeamCity to checkout the sources on agent or server (see above). Note, agent-side checkout is supported not for all VCSs, and in case you want to use it, you need to have version control client installed at least on one agent.

 4. Configure build steps (click to expand)

When creating a build configuration it is important to configure the sequence of build steps to be executed. Each build step is represented by a build runner and provides integration with a specific build or test tool. You can add as many build steps to your build configuration as needed. For example, call a NAnt script before compiling VS solutions.
Learn more

Basically, these are essential steps required to configure your first build. Now you can launch it by clicking Run in the upper right corner of the TeamCity web UI.
However, these steps cover only a small part of TeamCity features. Refer to Creating and Editing Build Configurations sections to learn more about triggering a build, adjusting agent requirements, making your builds dependant on each other, using properties and so on.

Happy building!