TeamCity On-Premises 2024.03 Help

Continuous Integration with TeamCity

TeamCity is a continuous integration/continuous delivery (CI/CD) server.

Continuous Integration is a software development practice in which developers commit code changes into a shared repository several times a day. Each commit is followed by an automated build to ensure that the new changes integrate well into the existing code base and to detect problems early.

To learn about the basics of continuous integration, refer to our website.

What is TeamCity?

JetBrains TeamCity is a user-friendly continuous integration (CI) server for developers and build engineers free of charge with the Professional Server License and easy to set up!

This video gives a general overview of the main TeamCity features and explains the licensing policy:

What can you do with TeamCity?

  • Run parallel builds simultaneously on different platforms and environments

  • Optimize the code integration cycle and be sure you never get broken code in the repository

  • Review on-the-fly test results reporting with intelligent tests reordering

  • Run code coverage and duplicates finder for Java and .NET

  • Customize statistics on the build's duration, success rate, code quality, and custom metrics

  • and much more

To learn more about major TeamCity features, refer to the official JetBrains website.

TeamCity works well not only for administrators and build engineers, but also for developers. Watch this video to learn about some of its signature features:

The complete list of supported platforms and environments is available here.

Basic TeamCity concepts

This section describes the main TeamCity concepts. You can find a more comprehensive explanation in the Introduction to TeamCity terminology.

The TeamCity build system comprises a server and build agents.



Build agent

A piece of software that actually executes the build process. It is installed and configured separately from the TeamCity server. The agent can be installed on a separate machine (physical or virtual, and it can run the same operating system (OS) as the server or a different OS.
Build agents in TeamCity can have different platforms, operating systems, and preconfigured environments. Different types of tests can be run on different platforms simultaneously, so the developers get faster feedback and more reliable testing results.

TeamCity Server

The server itself does not run either builds or tests: the 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. All information on the build results (build history and all the build-associated data except for artifacts and build logs), VCS changes, agents, build queue, user accounts, user permissions, and so on, are stored in a database.


A TeamCity project corresponds to a software project or a specific version/release of a software project. A project is a collection of build configurations.

Build configuration

A combination of settings defining a build procedure. The settings include VCS roots, build steps, and build triggers described below.

VCS root

A collection of version control settings (paths to sources, username, password, checkout mode, and other settings) that defines how TeamCity communicates with a version control system (VCS) to monitor changes and get sources for a build.

Build step

A task to be executed. Each build step is represented by a build runner providing integration with a specific build tool (like Ant, Gradle, MSBuild, and so on), a testing framework (for example, NUnit), or a code analysis engine. Thus, in a single build you can have several steps and sequentially invoke test tools, code coverage, and, for instance, compile your project.

Build trigger

A rule which initiates a new build on certain events. For example, a VCS trigger will automatically start a new build each time TeamCity detects a change in the configured VCS roots.


Any modification of the source code which you introduce. If a change has been committed to the version control system, but not yet included in a build, it is considered pending for a certain build configuration.


A CI/CD job executed on an agent. It consists of one or more steps that can do any service task: compile, test, deploy, produce reports, and so on.

The term build can refer to both the actual process of building and the result of building. After a build is triggered, it is placed into the build queue and is started when a compatible agent becomes available. After the build is finished, the build agent sends build artifacts to the server.

Build queue

A list of builds that were triggered and are waiting to be started. TeamCity will distribute them to compatible build agents as soon as the agents become idle. A queued build is assigned to an agent at the moment when it is started on the agent; no pre-assignment is made while the build is waiting in the build queue.

Build artifacts

Files produced by a build, for example, installers, WAR files, reports, log files, when they become available for download.

Basic CI Workflow in TeamCity

To understand the data flow between the server and the agents, what is passed to the agents, how and when TeamCity gets the results, let us take a look at a simple build lifecycle.

Basic CI flow with TeamCity
  1. The TeamCity server detects a change in your VCS root (repository).

  2. The server stores this change in the database.

  3. The trigger, attached to the build configuration, detects the relevant change in the database and initiates a build.

  4. The triggered build appears in the build queue.

  5. The build is assigned to a free compatible build agent.

  6. The agent executes the build steps, described in the build configuration. While executing the steps, the agent reports the build progress to the TeamCity server. It sends all the log messages, test reports, code coverage results on the fly, so you can monitor the build process in real time.

  7. After finishing the build, the agent sends build artifacts to the server.

Last modified: 07 September 2023