You are viewing the documentation of TeamCity 8.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 9.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

Error rendering macro 'toc' : [com.ctc.wstx.exc.WstxLazyException] com.ctc.wstx.exc.WstxUnexpectedCharException: Unexpected character ':' (code 58) (missing namespace prefix?) at [row,col {unknown-source}]: [15,18040]


Starting with TeamCity 8.0 each Build Agent license adds 10 more build configurations to Professional edition (as well as one agent)

Projects Hierarchy

TeamCity 8.0 allows creating subprojects inside other projects. Now all projects form a tree (each project can have one parent project only) with the <Root project> at the top of the hierarchy. The <Root project> is created by default and cannot be removed.

Project hierarchy affects the server behavior in many places:

  • VCS roots created in a project are available in this project and in all subprojects down the hierarchy. As such, the concept of shared VCS root has been eliminated, and all shared roots are moved to the <Root project> during upgrade.
  • Similarly to VCS roots, build configuration templates created in a project are available in this project and in all subprojects. TeamCity no longer allows attaching a build configuration to a template if the template does not belong to the current project or one of its parents.
  • A project parameter defined for a project will be available in build configurations of this project and all subprojects. A parameter defined in the <Root project> effectively becomes global, i.e. appears in all build configurations.
  • Roles assigned to a user or group in a project propagate to its subprojects. For example, if a user is assigned the Project administrator role in a project, this user will have the Project administrator role in all subprojects of this project. On the other hand, if the View project permission is assigned to someone in a project, this user will have the View project permission for all the parent projects too.
  • A notification rule assigned to a project applies to all its subprojects too.
  • If an investigation is assigned to a test or problem in some project, it propagates to its subprojects too. The same applies to mutes.
  • When a project is archived, all its subprojects are archived too.

Different pages in the user interface now include results from subprojects:

  • The project Change Log page now shows changes from the current project and all subprojects.
  • The project Current problems/ Investigations/ Muted Problems tabs show data from the current project and all its subprojects.
  • Test History shows results from the project and its subprojects.
  • If project is selected in Administration -> Audit, the information on all its subprojects will be displayed too.

Subprojects are also shown in breadcrumbs, all projects popup, choosers with projects and build configurations and in many other places.

Human Friendly Identifiers

Each configurable entity in TeamCity, be it a project or build configuration, always has an identifier |(ID) assigned. These IDs become important if some automated actions are to be performed with this entity. For example, one may want to add a build to the queue right from a build script. Another common task is to fetch artifacts in a build script from the latest build of some build configuration. REST API is often used to create or modify build configurations, VCS roots or even projects. IDs are used for all the above-mentioned cases. Until TeamCity Version 8.0, these IDs were not editable and as such were not human friendly (e.g. bt125).

Now, in version 8.0, you can assign your own IDs to projects, build configurations, templates and VCS roots. All these entities now have the ID field in their settings. ID is a mandatory field, but TeamCity fills it out automatically based on the current object name and the ID of the parent object. Once the ID is provided, it can be used in build scripts and in REST API.

IDs are also used in several other places, like URLs in web interface, file and directory names under <TeamCity data directory>. They are also used in dep. and vcsRoot. parameter references.

Since ID is a mandatory field, it appears in some other places in the administration interface, like the Copy dialog for projects and build configurations. During upgrade, TeamCity will generate IDs for projects and VCS roots based on the project and VCS root names. It will not generate IDs for build configurations and templates though. If you want human friendly IDs for all build configurations in your project, you can use the Bulk edit IDs button in the sidebar of the edit project page.

And last but not least, human friendly IDs are also used across all project configuration files stored on the disk under <TeamCity data directory>/config. This makes it possible to move configuration files from one server to another, provided that IDs used for objects are unique across these servers.

It is also worth noting that <TeamCity Data Directory>\system\artifacts used to hold directories named by project names prior to 8.0. Since this update, the directories are named by project ids (nested build configuration directories still use build configuration names).

Related topic in our documentation: Identifier

Project Directory Structure

TeamCity does not store project configuration files in a database, instead it stores them on the disk under the <TeamCity data directory>/config folder. Configuration files are stored in the xml format. Before version 8.0, TeamCity stored all VCS roots in a single vcs-roots.xml file. All build configurations and templates of a project were stored in a single project-config.xml file. In version 8.0 the project-config.xml file has been divided into several parts, and VCS root definitions were moved under the project directory. So now the project directory containing all project configuration files looks as follows:

  • buildNumbers directory contains current build numbers of all build configurations of the project with file names like: <build configuration ID>.properties
  • buildTypes directory contains definitions of build configurations and templates, one file per definition, with file names like: <build configuration/template ID>.xml
  • vcsRoots directory contains definitions of VCS roots, one file per definition, with file names like: <vcs root ID>.xml
  • pluginData directory contains plugin specific configuration files.

Mixed Mode Authentication

TeamCity server supports the following authentication mechanisms: built-in authentication (enabled by default), Windows Domain (with optional NTLM HTTP authentication), and LDAP. However, before version 8.0, these authentication modules were mutually exclusive, i.e. it was not possible to have the built-in and domain authentication at the same time, although such setup could be convenient during migration from one authentication mode to another.

In version 8.0 we implemented a more sophisticated authentication mechanism, which we call "mixed mode". Starting from this build, you can configure several authentication modules, so when a user attempts to log in, TeamCity will try all the modules one by one. If one of them authenticates the user, the login will be successful; if all of them fail, the user will not be able to log into TeamCity. We also implemented a user interface to simplify editing of the authentication configuration (in the previous versions you had to manually edit the main-config.xml file). Finally, presets were created for the most common use cases:

  • Default (built-in authentication only)
  • LDAP
  • LDAP with NTLM
  • NTLM

Some modules have the settings which can now be edited from the user interface too. For advanced users there is an advanced mode allowing them to add / remove authentication modules. These options should be handled with great care. On changing authentication modules, all the existing users with their settings are preserved if their usernames in the old and new authentication modules remain the same. If this is not the case, the username for specific authentication module can be specified in the user profile (see Authentication Settings).

Additionally, there is a special super user account with system administrator role. This account is not editable and it does not have a profile. When the server starts, it generates a password for this account and writes it in teamcity-server.log. This account can be used for password recovery; all maintenance tasks are performed on behalf of the super user.

Related topics in our documentation:

Faster Build History Clean-up

TeamCity is critical software for many organizations. Many of our users have distributed teams, working with the server all the time. At the same time, TeamCity must perform some clean-up tasks to remove obsolete builds and their artifacts, clean-up obsolete data from database and caches. These clean-up activities are also important to keep the server performance at the desired level. Before version 8.0, the clean-up task could take a significant amount of time, and the clean-up duration was unpredictable. This affected projects with distributed teams as the server was not accessible for many team members during the clean-up process.

In version 8.0 we made a lot of performance improvements in the clean-up process. Several time consuming activities were moved to the background. Moreover, it is now possible to set the clean-up execution time for the server.

Besides the general speedup, there are other improvements in the clean-up process:

  • Clean-up rules can be defined for a project, in this case they act as default for all configurations and subprojects.
  • Orphaned build artifacts and build logs (i.e. files not attached to any build in history) are now cleaned out as well. Thus, the server can be safely stopped during the clean-up process, and the data not yet removed will be cleaned out next time.
  • The clean-up progress is now displayed.
  • The clean-up process can be stopped by system administrator.

Disk Usage Report

Each build occupies some disk space under <TeamCity data directory> folder. The space is used by build artifacts and build logs. One useful addition in version 8.0 which nicely complements our clean-up improvements is the Disk Usage report. With the help of this report you can easily find the projects consuming most of disk space and configure the clean-up rules accordingly. Besides this, the report provides summary for the total free disk space, number of pinned builds, etc. Disk usage is shown on the build history clean-up page as well.

The Disk Usage report allows going deeper in the build history of a specific build configuration and showing some additional statistics for the builds of this configuration:

Server Health Report

The Server Health report is another significant addition made in TeamCity version 8.0. This report shows different configuration problems, so called server health items. These items can be global, or project related. There are several reports providing such items, and, as the report is pluggable, it is possible to write a plugin which will report on some specific items. Currently the following reports are available:

  • Agents not used for 3 days or more
  • Configuration with large build logs
  • Possible frequent clean checkout
  • Possible frequent clean checkout (Swabra case)
  • Similar VCS root usages
  • Similar VCS roots
  • Unused VCS roots

We are planning to significantly extend the number of reports in the subsequent versions of TeamCity.


Meta-Runner allows you to extract build steps, requirements and parameters from a build configuration and create a build runner out of them. This build runner can then be used as any other build runner in a build step of any other build configuration or template.

Let's consider an example of a meta-runner. In this case we'll create a runner to publish some artifacts to TeamCity with the help of corresponding service message. Usually artifacts configured in a build configuration are published when the build finishes. However, sometimes for long builds with multiple build steps we need artifacts faster. So let's create a runner which can be inserted between any build steps and can be configured to publish artifacts produced by previous steps.

Preparing Build Configuration

The first thing we need to do is to prepare a build configuration which will work the same way as the meta-runner we'd like to produce. We'll use the configuration with a single Ant build step. We've chosen Ant because it can be executed on any platform where the TeamCity agent runs; besides, Ant runner in TeamCity supports build.xml specified right in the runner settings. This is important because our build configuration must be self-contained, it cannot take build.xml from the version control repository. So in our case the Ant step settings will look like this:

where artifact.paths is a system property. We need to add it on the Build Parameters tab of the build configuration settings:

Note that each parameter can have a specification where we can provide the label, description, type of control and specify validation conditions. Before version 8.0 this specification was used by the custom build dialog only. Now this specification is used by a meta-runner too.

Verifying How Build Configuration Works

Once we defined build steps and parameters, we can check how our build configuration works by running a couple of builds through the custom build dialog:

Extracting and Using Meta-Runner

If the build configuration works properly, we can create a meta-runner using the Extract Meta-Runner button in the build configuration settings sidebar:

The Extract Meta-Runner dialog requires specifying the project where the meta-runner will be created. As with VCS roots and templates, if a meta-runner is created in a project, it will be available in this project and all subprojects down the hierarchy. In our case the <Root project> is selected, so the meta-runner will be available in all projects. We also need to provide the name, description and an ID for the meta-runner (by default, the ID will be generated from the meta-runner name).

Once the meta-runner is extracted, it becomes available in the build runners selector and can be used in any build step just like any other build runner:

The current meta-runner usages can be seen at the project Meta-Runners tab:

Besides build steps and parameters, a meta-runner can also have requirements. If requirements are defined in the build configuration, they will be extracted to the meta-runner automatically. Requirements can be useful if the tools used by meta-runner are available on specific platforms only.

Since the meta-runner looks and works like any other runner, it is also possible to create another meta-runner on the basis of an existing meta-runner.

Shared Resources

Builds can use different resources (databases, web services, etc.). Some of these resources can be accessed concurrently but allow only a limited number of connections, others require exclusive access. To address these cases, we introduce the Shared Resources build feature. Now you can define a resource on the project level, configure its parameters (e.g. type and quota) and then use this resource in specific build configurations by adding the Shared Resources build feature to them.

Build Problems

In this version TeamCity is even more efficient in detecting build problems. A build problem is something that causes a build to fail. For example, all build failure conditions, once detected in a specific build, actually result in a build problem being added to the build. Once the problem is reported, the build fails. All problems reported for the build are now shown on the build results page and in the build summary popup. TeamCity also tracks the new/not new status for build problems, and allows muting them or assigning investigations for them. Reported problems are shown on the Current problems, Investigations and Muted problems pages. So now you can work with problems the same way you work with tests.

Additionally, there is a new service message that allows reporting on a custom problem for the current build.

Queued Build Page

In TeamCity a build goes through several states:

  • upon some event the build trigger adds the build to the queue where the build stays waiting for a free agent
  • the build starts on the agent and performs all configured build steps
  • the build finishes and becomes a part of the build history of this build configuration

The build results page shows different details for a running or finished build. However some of these details, like Changes, Build parameters and Dependencies are also applicable to the build while it is waiting in the queue. In version 8.0, a queued build has its own page where all these details are displayed. Additionally, the queued build page is a convenient place for builds with snapshot dependencies, because there you can see the progress for all dependencies of the build chain, estimated duration, included changes, status, and so on:

Feature Branches Improvements

Since version 7.1 we have received a lot of feature requests for further improvements in feature branches support. In this release we tried to address the most important of them:

  • the build branch name can be specified in the artifact dependency
  • the VCS, Schedule and Finish build triggers now support the branch filter setting
  • the VCS labeling also supports the branch filter
  • Mercurial bookmarks can now be used in the branch specification, so, if you prefer to use bookmarks instead of standard Mercurial branches, you can now fully use TeamCity feature branches with them
  • Git tags can be used in the branch specification. Some teams use Git tags the same way as branches, i.e. once a new tag is set, a build should be started in TeamCity in a branch designated by the tag name. This is now supported too.

Related topics in our documentation:

Changes from Sub-repositories in Mercurial

TeamCity has supported Mercurial sub-repositories from the beginning. However, if you use sub-repositories, you're aware that TeamCity did not detect changes in them. When .hgsubstate was modified to include recent changes from sub-repository all you could see in TeamCity user interface is commit modifying this .hgsubstate file. Starting from version 8.0, you can configure TeamCity to also show changes from a sub-repository brought by the .hgsubstate file modification. See how it works in action:

IntelliJ IDEA Project Runner

IntelliJ IDEA Based Make

If you use IntelliJ IDEA, you probably know that since version 12.0 it uses a new external make, i.e. the make which works out of main IntelliJ IDEA process. We worked together with IntelliJ IDEA team to integrate this make with the IntelliJ IDEA Project runner in TeamCity. Starting from TeamCity version 8.0, IntelliJ IDEA Project runner builds your project using the same make tool which is used by IntelliJ IDEA itself. Basically it means that all of the goodies available in the IntelliJ IDEA make are now available in TeamCity too. To name a few:

  • support for different languages like Groovy, Scala, Closure, Kotlin, etc.
  • ability to compile Android projects and build .apk artifacts.
  • ability to build many other artifact types supported by IDEA itself (war, ear, etc.).
  • faster rebuild, thanks to the highly optimized IDEA external make build process, and even faster incremental building (can be enabled on the IntelliJ IDEA project runner page).
  • since the tool is basically the same, there are no any incompatibilities between TeamCity and IntelliJ IDEA anymore.

One additional feature for those who develop for Android in IntelliJ IDEA: the Inspections (IntelliJ IDEA) runner now supports Android SDK as well.

Remote Debug from IDE

Sometimes there are cases when, to fix a test, you have to debug it right on the agent. Usually this happens when the agent environment is unique in some aspect, which causes some test to fail, which is not easy or impossible to reproduce locally. If you happen to use the IDEA Project runner, and if you're using TeamCity plugin for IntelliJ IDEA, then now you have a good tool at hand to help you in such cases.

To start remote debugging of a test, you need to select the test and choose an appropriate option from the context menu (the remote debug action is also available in the TeamCity plugin menu):

Once you do this, the TeamCity plugin will ask you to select a build configuration where you want to start the debug session. Actually, the process is similar to starting a personal build. For example, if there are personal changes, a personal patch will be created and sent to an agent. Also since the process is basically the same, when you select a build configuration, you can specify an agent, customize properties, etc.

If the selected configuration has more than one build step, the plugin will ask to choose one or more build steps where the debug session must be started:

Note that only build steps with the IntelliJ IDEA Project runner are supported.

After that a build starts on the agent and the standard IntelliJ IDEA debug tool window appears:

The debug tool window works in the listening mode, i.e. it waits for the agent to connect to it. Once the agent connects, the Java process on the agent is paused and the following popup appears in the IDE:

Now we can set some breakpoints, and actually start the debug session by clicking start either in the notification popup or in the debug tool window.

Once JVM process exits, another notification popup appears in the IDE:

Our debug session is not finished yet, now we can either repeat or finish it. If you ever tried to debug a tricky case (although it's always tricky, otherwise we wouldn't have started the debug session), you should understand how important the Repeat action can be. It will repeat the same build step again and it works much faster than starting a new debug session.

Since the remote debug session works with IntelliJ IDEA run configurations, it is important to mention that at the moment not all types of run configurations are supported by TeamCity. The currently supported types are:

  • Java application run configuration
  • JUnit run configuration
  • TestNG run configuration

Test Status in IntelliJ IDEA

You can configure TeamCity IntelliJ IDEA plugin to show the test status obtained from the server right in the editor, near the test name. This indication can save developers time for the cases when a test is muted on the server or is being investigated by some other developer.

Test status indication can be enabled throughthe menu of the TeamCity plugin for IntelliJ IDEA.

.NET Inspections Improvements

Full MSBuild Model Support

We worked together with our colleagues from the ReSharper team to fix a large set of bugs in the server-side .NET code analysis. Generally, all those bugs could be described as "There are no errors (warnings) in Visual Studio, but TeamCity shows a number of problems in my code."
The reason was that the project model which is an input for code analysis was incorrectly constructed outside of Visual Studio. In order to fix this, we now support all of MSBuild-related features usually used by developers.
Some of them are:

Analysis Results Caches

We have also received reports about poor performance of code analysis on the server (compared to ReSharper). To mitigate this, all data produced by code analysis which could be reused in future builds on the same build agent is stored outside of the checkout directory (by default) and is cleaned out together with other agent caches.

Other Noteworthy Changes

Updated Look and Feel

As usual, we've made numerous improvements to the overall look and feel. All the icons have been redesigned and now support the new high-resolution displays.

Change Log Page

  • commit graphs can be collapsed
  • changes can be filtered by comment
  • build tags and pin status are shown for build rows


We've changed the way how statistics charts are generated, now we use JavaScript based library and charts are rendered on the browser. This makes it possible to make charts more interactive. For example, now you can easily zoom any region of a chart.

Besides this, some additional features were added:

  • Y-axis settings can be changed.
  • Chart data can be downloaded in the CSV format.
  • Auto-generation of colors for series has been improved.
  • A custom color can be set for a custom chart series in the chart configuration file.

Builds Schedule Tab

If you use Schedule triggers a lot, then you probably tried to find a window on your system where you could squeeze yet another build configuration. In version 8.0 this task is much easier thanks to the new Builds Schedule tab available on the project level. This tab shows all schedule triggers configured in the project and its subprojects in a single timeline, so you can easily observe what happens and at what time on your system.

Conveniently, the schedule trigger itself now has a timezone setting, which should help if your server and teams working with it are in different timezones.

Remove Build Action

A single build or the whole build chain which the given build participates in can now be removed from the database with the help of the Remove action available from the Build actions menu.

Plugin Development

TeamCity server and agent API is published in JetBrains Maven repository, so now it should be easy to create plugins with help of Maven. We also provided Maven archetype for TeamCity plugin generation. Read more on this here.


  • Build artifacts can be listed via REST API
  • Build configuration labeling settings can be retrieved or modified by REST

Fixed Issues

There are lots of fixed issues including security-related ones. See the full list.

Previous Releases

What's New in TeamCity 7.1

  • No labels