TeamCity 7 Continuous Integration Essentials

By Volodymyr Melymuka
  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies

About this book

Nowadays, Agile application development is usually done at a fast pace when many developers are working on the same piece of code. Every so often, this becomes a real challenge if there’s no permanent control over consistency of the project source. It is often impossible to force lazy and/or busy programmers to execute tests before and after each of their commits. Continuous Integration is a well-known life saver for distributed development environments with TeamCity being one of the best and easy-to-use instruments utilizing it.

"TeamCity 7 Continuous Integration Essentials" is the first book of its kind showing in a sequential approach — how to start implementing Continuous Integration — over generic projects and enclosing rich features of the TeamCity as a project gradually evolves.

Learn how to do a quick-start with TeamCity and suite most of the common needs right out of the box. As the project grows and more sophisticated requirements to the build process arise, the examples from this guide will assist you showing how to unleash TeamCity hidden powers and adjust advanced features to bring stability into the distributed development process.

You will learn how to start a new Java project from scratch generating a working “skeleton” of web application using Apache Maven and later adding some business logic and writing certain tests. After that, you will know how to perform a swift attach of TeamCity facilities to your project and eventually change it into rich featured information source describing the current state of your venture. If you want to benefit from Continuous Integration and are considering using TeamCity then this book is for you.

You will be acquainted with everything you need to know in order to apply Continuous Integration with TeamCity by installing it first, then turning on automatic supervision over project’s reliability, and finally tuning up advanced settings in order to match your needs.

Publication date:
December 2012


Chapter 1. Getting Started with TeamCity

The total number of software programs and applications being developed at the present time has never been greater and their scope has never been wider. Moreover, it still grows both in terms of increasing demand of getting every kind of business you need to have today or would need to be having tomorrow. All related new features should be introduced rapidly enough to leave competitors behind.

But speed comes at a well-known cost—you either make it quickly or of high quality. There are several possible ways to try to achieve both together, and TeamCity provides one of the best options to do that via Continuous Integration.

TeamCity is a very light instrument, easy to install, integrate, and maintain. It's a tool which helps you ensure that your software project not only compiles properly but can be assembled and (ideally) allowed to be delivered to operational destination production servers merely by glancing at the TeamCity welcome page. For distributed teams, it could give a priceless experience of having reliable codebase free from some forgotten to be committed source files and resources.

In this chapter we shall cover the following topics:

  • Features

  • Terms and concepts

  • Architecture

  • Build lifecycle


Continuous Integration

Continuous Integration is defined by Martin Fowler as follows:

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. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly.

Kent Beck and Martin Fowler are credited as the first users of the term Continuous Integration since 1999. Now, more than 10 years later, this term has become a well-known and well-used practice (though many interested parties might wish it would turn into an established standard) used for software design and engineering across the entire industry.

The main essence of it lies in the simple practice of each delivering person in the team to meet on a very frequent, several-times-per-day basis to a source control repository.

In the long run, this could save us from lots of headaches and last-minute integrations made in a rush. The more frequent this integration is, the less chance you have to get an incompatible bunch of modules instead of a rock solid application.

Okay, so now you are delivering to a repository every so often but what next? Repository integration will keep the code consistent, but will it check the code for correctness or run some tests? The answer here is no. What we need at this time is some build automation, and here TeamCity steps in.



Let's sum up some outstanding TeamCity features.

Automatic and manual build triggering

Do you want every change in the Version Control System (VCS) to be verified? It's never been easier. Just set up automatic build triggering on every commit and you are done. Also dependent builds could be instantly triggered after the completion of some other build and may even use their generated artifacts. At any time, we can schedule a manual build by simply clicking on the Run button.

Pre-tested commit

This concept also has another name—remote run. It is really a life saver when we wish to check the consistency of our patch with the whole project. Instead of performing a commit, we select Remote run on the commit screen and can decide whether to do an actual commit depending on build results. It is usually not a good idea to proceed with a commit if the build is either failed or did not introduce new failures itself, but kept previous ones in place.

Instant notifications

There are plenty of different ways to stay in touch with the TeamCity Server. On the other hand, it could be as simple as sending an e-mail to all interested parties and as exquisite as the Windows tray notifier. Many other options such as RSS feeds, Jabber, and plugins for major IDEs are supported.

Code coverage and inspections

Upon producing build results we may be interested in checking our code coverage. Further on, it is possible to apply over 600 IntelliJ IDEA's inspections in order to find actual and potential problems. Inspections result in thorough reports for probable bugs, performance issues, and obsolete code, if present.

Easy to verify code changes

No longer does the developer need to remember what the code looked like before a change had been introduced. TeamCity provides a very useful and effective comparison engine to easily see what actually has been modified with which changes.

Configurable test reports

You need not to wait for a long build run just to figure out that the very first test has failed. TeamCity will notify you at once when it notices a failing build. You will get a complete report showing which tests have failed, whether this problem has happened for the first time, and so on, with the full statistics the developer needs.

Comprehensive build infrastructure

TeamCity supports multiple multi-platform build agents which can be run in parallel independently of each other. It is possible to get workload information and history. Every bit of statistics related to builds is also accessible over time. It is possible to track build progress, run build chains, and apply enhanced build dependencies.

Enhanced VCS integration

TeamCity permits utilizing sophisticated VCS configuration. It can use a smart scheduling mechanism called quiet period , if there is a need not to run builds at once, but to wait until partial commits or ones from different roots are conducted. Agent-side checkout allows maintaining source code consistency over your builds spread between different build agents.

Advanced features

TeamCity provides flexible user management with the possibility of configuring per-project user roles and accesses along with user action audits. TeamCity supports adaptable user authentication with LDAP and NT authentication support, detection of hanging builds that take longer time than expected, discovery of JVM out-of-memory crashes, and on the fly thread dumps for running builds.


Terms and concepts

Let's look at some useful concepts that will help you understand TeamCity better.

Build agent

A build agent is an isolated software unit where actual builds are executed and run. A build agent can coexist with the TeamCity server on one physical box, however that is not required. It is possible to install two or more build agents on one machine though it is not the preferred way to go because of the performance impact those agents would have on each other:

Sometimes separate build agents are needed per platform. For instance, it is often a situation that the server and the default agent are running on a Linux machine. Let's say there's a need to run some very specific kind of test such as GWT or flexunit tests on a build agent but this is impossible on a default one because these tests cannot be run in headless mode (it means display-less mode in which Linux servers usually work). A possible solution here is to install another build agent on the Windows machine. A build agent is a stateful machine. In order to make it work, the developer needs to install and run it first. At that point, the agent becomes disconnected. Then, during the configuration stage, we provide a connection link to the TeamCity server and the agent gets connected. It is still not yet ready because we need to make it authorized first. This is done manually on the Agents page. The default agent on the same machine as the server gets authorized automatically. At any point, you may disable or enable a particular build agent.

Build artifact

Every build may be configured to produce one or more build artifacts. They could be described as simple files that are possible to download or use in other (dependent) builds. For instance, the coverage data generated by a build is a build artifact. Also it could be some generated JAR, WAR, or other file that is configured.

There are also so-called hidden build artifacts that enlist raw coverage data and maven build data. These could be accessed through a special link.

Build configuration

In a nutshell, this is a set of actions to be applied to the source code. You define the actions and rules to be applied to the build, and click on Run; the configured builds would be handled by TeamCity and could be run from this point continuously and automatically. Creation of a build configuration is pretty straightforward and consists of several steps. On the first one, the name should be provided along with the rules describing how to understand if a build was successful or not. The later steps allow configuring version control settings, setting up build steps (Maven, Ant, and many other options are available). Then you can build triggering rules, dependencies, and other additional settings.

Upon creation of one build configuration, it could be replicated to avoid entering the configuration data many times in a row. Even a simple setting such as a user or group notification rule can be reused.

If you feel you are going to need the same build configuration several times, you may create a build configuration template. After that, you can generate new configurations with a single click—only the name of the template needs to be provided and the rest of the data would be served by the template.

Each build configuration has its state—active or paused. Also, it has a completion status that can be either successful, failed, or under investigation, indicated by the corresponding icon. Before the build has been run for the first time, there'll be no icon, as the status is still unknown.

Every build configuration has a unique ID, which you may refer to when performing some advanced manual configuration of TeamCity.

Code coverage

Code coverage is a very useful measure to describe the degree or level of how well and thoroughly the source code is covered by unit tests. This term really deserves a separate book to be written about it, though none are written yet. However, there are plenty of articles available on the Internet describing best practices. A nice start would be from the following example:

There are many metrics that could be collected with powerful code coverage engines, TeamCity being one of them. Combined with the Sonar code inspection server ( code coverage steps up to the next level where possible performance issues can be detected early on, probable bugs can be caught, or direct misuse of some language functions can be spotted.

TeamCity supports coverage engines for both Java and .NET. Major build runners that support code coverage collection include Maven, Ant, NAnt, NUnit, and several more.

At the time of writing, TeamCity did not support full coverage for integration tests. For example, having several Maven modules and calling one module from another will collect coverage for only the initiator module. In order to obtain this kind of coverage, the Sonar server with the Cobertura analysis tool would be needed.

My Changes

My changes is a special page where personal historical build information concerning a specific user is collected. Here, a user may observe his own changes and figure out how they affected builds presented by a timeline. You may go as far as viewing atomic change details presented by each build. Also the developer may navigate from here to the issue tracker directly, if issue tracker integration is turned on and properly configured.


TeamCity can utilize several notifiers. There can be either separate or common notification rules created for each of the supported notifiers. The total list includes:

  • Email notifier undoubtedly being the most commonly used one

  • IDE notifier shows status in your favorite IDE

  • Jabber notifier sends events through Jabber server, that is Google Talk

  • System Tray notifier displays updates in the Windows system tray

  • Atom/RSS feed notifier informs you via Atom/RSS feed

Settings are configured on the My Settings & Tools page in the Watched Builds and Notifications section.

Pre-tested commit (remote run)

This delayed commit is a very powerful feature which previously allowed TeamCity to stand out in the crowd. By now, it has been adopted by major competitors as it became very useful, and therefore, popular. In short, it allows a developer to make sure that his changes will compile without problems and pass all tests, not only on his box but on at least one isolated machine.


A project is the largest separate TeamCity's concept used here. It is merely a group of build configurations. It should have its own name, some meaningful description and may be used to define some generic security settings for all included build configurations. You can assign separate permissions for users on a per-project basis.

Version Control System

A Version Control System (VCS) is a facility to store a project's source code files and all changes made to them over time. It is expected that the VCS will represent corresponding versions of code for any given time. These slices are called revisions and are usually identified by incrementing numbers. TeamCity supports plenty of version control systems such as ClearCase, CVS, Git , Mercurial, Perforce , StarTeam , Subversion , Team Foundation Server , SourceGear Vault , and Visual SourceSafe .



TeamCity is represented by a very simple and scalable distributed build grid architecture. There is one server, which is the central unit to which a bunch of build agents are connected. One default build agent comes with TeamCity itself and is usually installed on the same box containing the server. Other build agents can be installed elsewhere on UNIX/Linux/Windows platforms.

The server's duty is to coordinate cooperation of a build agent grid. Those are the facilities which actually run all the builds and tests—not the server. It runs nothing but a database where historical records are being stored, and a modest web application where they are shown. The server keeps a mediator role between agents, collecting and publishing all information data in one place.


Build lifecycle

The build lifecycle is depicted in the following diagram:

Scheduling to a build agent

The build process is always initiated by the TeamCity server. It could have a manual cause, that is after you've clicked on the Run button for a specific build. But more important for us is automatic triggering which could be originated from several independent origins. If you've set up VCS triggers, TeamCity can detect that a commit has been made to the version control system. Otherwise, it can discover that some build which we are depending on has finished successfully and then schedule our dependent build at once.

If there are no particular preferences for selecting a build agent that have been specified, TeamCity chooses the fastest idle one from its pool. But the build is not started yet—first it is being scheduled and put into the Build Queue, and when its turn comes later, it gets assigned to a particular agent and only then gets executed.

You need to pay attention to platform-specific builds and instruct your build agents to support only certain build configuration. Various agents could have different build paths or some environment settings, and so on, which could prevent your build from being successfully executed if it's picked up by the wrong agent.

VCS specifics

A build should be run on some source code and here's the place where powerful VCS integration steps in. The two feasible options for the build agent to be provided with needed sources to start the build are as follows:

  • Server-side checkout

  • Agent-side checkout

Server-side checkout

This is the default and most commonly used option. This way only the server cares about VCS configurations and support, thus freeing agents from any knowledge about how the VCS is used and how it is arranged. Among the pros, there are fewer and easier configurations on build agents, reduced interaction with the VCS altogether because the server manages all version control related operations. TeamCity sends only relevant incremental patches of the source files that it stores in its internal cache.

Agent-side checkout

Here the pros are that you are able to apply some version-specific actions, such as accessing the .svn directory for Subversion or retrieving the related revision numbers from the underlying VCS. Keep in mind that this option requires more effort to set up the configuration, and is not supported by every VCS available in TeamCity.

Running the build

When the source code is in place, the agent can start the build. Exact actions are described in so-called build-steps that were set up on the Build Configuration page. Each step can define its own specific goal, which is accomplished by the related build runner. A build runner could be thought of as a plugin for TeamCity supporting a particular build tool such as Ant, Maven, MSBuild, NAnt, test frameworks such as NUnit, or even the bare command line, and many others.

So you need to construct your build with several build steps. Running this build will execute all arranged steps in a defined sequence.

In real time, the build agent updates the server with the latest changes. All test reports and logged messages are being sent to TeamCity on the fly, so you are able to monitor the progress of the build in real time.

When the build is finished, its outcome will be sent to TeamCity, including coverage reports, built JAR and WAR files, together called build artifacts . Upon completion, you may download them from the server and investigate them if you wish.



TeamCity is a contemporary, rich-featured, distributed build management and Continuous Integration server. It has been designed for developers and by developers, thus being very intuitive, easy to use, easy to learn, and user friendly. There's absolutely nothing hard to understand neither in lifecycle, organization, or total workflow of TeamCity.

TeamCity contains an extensive set of utilities which moves your development effectiveness and comfort to a totally new level. It is a light and very easy to install facility which provides you with a decent degree of certainty that the code in your version control system not only compiles, but even adheres to written tests. And all this magic happens automatically on a continuous basis without requiring any user intervention. Every change in your source code would be detected, monitored and inspected, and you shall get full report about every modification introduced.

About the Author

  • Volodymyr Melymuka

    Volodymyr Melymuka is an agile and experienced Lead Software Engineer and a qualified team leader, who applies Continuous Integration with TeamCity for more than 4 years as of now. He took up key roles and led several projects in which he applied various agile/XP practices such as TDD, BDD, and continuous delivery, among others. During his work he used and administered many CI servers, namely TeamCity, Jenkins, and Bamboo. He currently works as a scrum master and team leader in TomTom's offshore development team. His former working experience involved large enterprises such as UBS Investment Bank and BAWAG P.S.K., and a great unbelievable project for SecondMarket Inc. He has a number of professional certifications such as Certified ScrumMaster from Scrum Alliance and ICAgile Associate by ICAgile consortium. Besides being interested in the latest web technologies and many others things, he is also a former musician and he is fond of portrait photography, especially the ones involving children.

    Browse publications by this author
Book Title
Unlock this full book FREE 10 day trial
Start Free Trial