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

Table of Contents

Feature branches for Git & Mercurial

Distributed version control systems like Git & Mercurial provide a convenient way to develop in feature branches. Previous versions of TeamCity already supported development in feature branches to some extent.
Prior to TeamCity 7.1 you could:

  • Create a copy of a build configuration for each feature branch with a new copy of a VCS root.
  • Use Branch Remote Run Trigger.

Both ways have disadvantages. Creating a new build configuration for each branch is tedious and requires permissions, and it does not provide the same feeling as creating a branch in Git.
On the other hand Branch Remote Run Trigger can trigger personal builds only (by default, such builds are only visible to the build owner), so this approach does not work well if more than one developer works in a feature branch. Branch Remote Run Trigger also lacks some configuration parameters often needed in real-world scenarios, like an ability to wait some time before a build is triggered, or ignore some of the commits, etc.

These ways look like workarounds, so we felt a new approach was required to make TeamCity fully compatible with this development model.

Our main idea was to make development and building in branches as simple as possible. Ideally, all you have to do is to push your branch to a Git or Mercurial repository and TeamCity would detect it and start a build on your changes. And this is how it actually works in TeamCity 7.1! But to enable this you need to make some tiny changes in your build configuration.

Branch specification & default branch

Your repository may have a lot of branches and naturally not all of them are feature branches. In TeamCity you can tell the server which branches to watch for changes using branch specification. It has the following syntax:

Where <branch rule> is a branch name in a VCS repository, +: and -: instruct TeamCity to include or exclude changes from branches with specified names (as you can see, the syntax is similar to checkout rules). There is no need to specify exact branch names, you can also use *. For example:

Branch specification can be set right on the VCS root page, and as with almost any VCS root setting you can use parameter references here too. Refer to our documentation to learn more about branch specification syntax.

Git & Mercurial VCS roots also have a dedicated field for branch name. This field specifies the default branch to be used when a branch is not defined. For example, if a build is added to the queue and no branch is provided, TeamCity will start a build in the default branch. There is a number of places where default branch is required, we'll cover them later.

VCS trigger

Once you've configured branch specification in a VCS root, TeamCity starts monitoring branches for new changes. To enable automated build triggering on a commit to a VCS repository you need to add a VCS trigger to your build configuration.
Once a change is detected in a branch, TeamCity will trigger a build on this branch. All VCS trigger parameters like quiet period, per-checkin triggering and so on also work with branches. You can even configure TeamCity to trigger on a change in a branch in snapshot dependency!

Branch label on a build

When the VCS trigger triggers a build on a branch, a label with a branch name is assigned to the build:

Labels for builds from default branches are shown differently, see builds with default label on screenshot.

It is important to understand that branch label may not be the same as the actual branch name in the repository. For example, Git branch names typically look like this:

It would be tedious to repeat refs/heads/ in each build. Most likely, you would prefer to see master, bugfix or release-1.0 instead. There are two solutions to this problem. First of all you can use * in branch specification. In this case, TeamCity will only take a part of branch name matched by * and use it as branch label in builds. So in our example, branch specification +:refs/heads/* would solve this problem. You can also use parentheses in branch specification to specify exactly which part of actual branch name should be used as branch label in build:

In this case, builds triggered on a refs/heads/release-1.0 branch will be labeled 1.0.

Branches filtering

Builds can be filtered by branch label in various places of the TeamCity web interface.

On the overview page you can filter all build configurations of a single project by selected branch name:

On the build configuration home page you can filter history, change log, issue log and pending changes by branch label:

There is also a Branches tab in the build configuration which will give you a bird's-eye view on the status of active branches in a build configuration (i.e. branches with builds or changes within 1 week):

On this tab you can also easily trigger builds in a specific branch.

Run custom build dialog

If your build configuration has branches (on its own or via snapshot dependencies), custom build dialog will let you choose a branch to be used for a build:

Multiple VCS roots

If your build configuration uses multiple VCS roots and branches are set up in several of them, the way builds are triggered is more complicated.

VCS Trigger groups branches from several VCS roots by branch label (the part matched by * in branch specification). When some root doesn't have a branch from the other root, its default branch is used. Say, you have two VCS roots and both have a default branch refs/heads/master, first root has branch specification refs/heads/7.1/* and has changes in branches refs/heads/7.1/feature1 and refs/heads/7.1/feature2, second root has specification refs/heads/develop/* and has changes in branch refs/heads/develop/feature1. In this case, VCS trigger runs 3 builds with revisions from the following combinations of branches:









VCS branch parameter

For Git and Mercurial, TeamCity provides additional build parameters with names of VCS branches known at the moment of build starting. If a build took a revision from the refs/heads/bugfix branch, TeamCity will add a configuration parameter with the following name:<simplified VCS root name>=refs/heads/bugfix

Where <simplified VCS root name> is the name of the VCS root where all non-alpha numeric characters are replaced with _.

In addition to this parameter, VCS branch is now shown on build changes page:

Other TeamCity features and their relationship to branches

A number of existing features in TeamCity were affected by branches support.

Build changes

For each build TeamCity shows the changes included in it. For builds from branches, changes calculation process takes the branch into account and presents you with changes relevant to the build branch.

First failed in / fixed in

TeamCity tries to detect new failing tests in a build - you can see in which build the test started to fail for those tests that are not newly created. Now this functionality is aware of branches too, i.e. when the first build is calculated, TeamCity traverses builds from the same branch.

Additionally, branch filter is available on the test details page, so you can see how the test passed / failed in a specific branch.


If a build configuration with branches has snapshot dependencies on other build configurations, all builds from the chain will be marked with this branch when the first build is triggered.

Artifact dependencies work mostly with builds from the default branch. Currently there is no way to have an artifact dependency to last finished build from a non-default branch. The same applies to finish build trigger - it will only watch for finished builds in the default branch.


All notification rules except "My changes" will only notify about builds from the default branch. At the same time "My changes" rule will work for builds from all available branches.

VCS labeling

If you configured VCS labeling for your VCS roots, TeamCity will only label builds from the default branch.


REST is fully aware of branches. The following requests are supported:
All available branches of a build configuration: GET http://teamcity:8111/app/rest/buildTypes/<buildType_locator>/branches
Build locator now supports the "branch" dimension. Use "<any>" for <branch_name> to return builds from all branches. If branch is not specified, only builds from the default branch are returned.
e.g. all builds for the specified branch: GET{{http://teamcity:8111/app/rest/builds/?locator=branch:<branch_name>}}
get build's branch: GET http://teamcity:8111/app/rest/build/branch - returns a text/plain response with the branch name (empty string for the default branch)

Branch Remote Run Trigger

Branch Remote Run Trigger works as usual, but with one important exception. If branch specification is provided in build configuration VCS roots, this trigger will not trigger builds on branches specified in branch specification. It will continue to trigger builds on all other branches matched by its own pattern.

Change Log and Changes pages

Build and Pending Changes pages

Build Changes tab and Pending Changes tab have got a new look, very similar to Change Log. Apart from unified look and feel these pages also inherited some change log goodies, like graph of commits (especially useful for Git or Mercurial), ability to filter changes by user name and file path, and paging.

Artifact dependency changes

If TeamCity detects a change in the build artifact dependency (i.e. artifacts were downloaded from a different build compared to the previous build), this fact will be presented as a new change and will be shown on changes pages:

and in changes popup:

Builds on the change log graph

If the "Show builds" and "Show graph" options are enabled in the change log, TeamCity will display build markers on the graph. We find that this enhancement makes it much more clear which commit ends up in which build:

Current problems & investigations

Current problems are shown for collapsed configurations

In order to make the overview page more usable for those who have to monitor problems in many build configurations we started showing current problems for build configurations right on the overview page. To avoid clutter, problems are only shown if the build configuration is collapsed:

Note that if your browser does not have enough horizontal space TeamCity will tune the problems presentation accordingly:

Also note that similarly to queued builds, information about currently running builds can be seen in the popup too - there is no need to expand the build configuration.

Sticky investigation & my investigations highlighting

Usually if an investigation is assigned for a build configuration or a test, it is automatically removed once the build configuration becomes green or the test passes.
Sometimes it is not convenient though. For example, if a test fails from time to time (so-called flickering test), investigation will be removed - however, such test can't be considered fixed.
To allow better management of such problems we introduced the manual mode for investigation resolving. When you assign an investigation you can select how you want it to be resolved: automatically or manually:

The same way highlighting of user changes works across the TeamCity web interface, when an investigation is assigned to you and is shown somewhere in the web UI, such investigation will be highlighted:

Investigations highlighting is controlled by the same user profile setting that is used for changes' highlighting - the setting is now called "Highlight my changes and investigations".

Version Control Repository browser

In several places in build step settings where a path to a build script can be specified you may now notice a small new icon: . By clicking on it you'll be presented with a VCS repository browser which allows you to choose a file in the repository.

This functionality is available for build configurations with Git, Mercurial, Subversion, Perforce, TFS and ClearCase VCS roots.

Support for NTLM HTTP authentication

The long-standing and popular feature request to add support for transparent/single-sign-on NTLM HTTP authentication has now been implemented: TW-6885.

The feature only works if the TeamCity server is installed on Windows and uses Windows domain authentication and only in the web browser.

Read more in our documentation

Manually mark build as successful or failed

Sometimes you need to mark a failed build as successful - for example, if a failure happened because of a minor problem, and you want other builds to take artifacts of this build, or you want to promote this build further through the pipeline.
On the other hand, there are cases when TeamCity is not able to determine build failure. For example, a build finished successfully but because of an error in the build script it did not produce any artifacts. So the build clearly cannot be treated as successful.

To handle both of these cases we added the ability to mark build as successful or failed. In both cases you need to provide some description of the reason of this operation. Also to be able to change build status one must have Project administrator role. These operations are logged into audit log and can be examined later.

Read more in our documentation.

New Windows service implementation for TeamCity server

Service which is used to start TeamCity on Windows was re-implemented in order to fix several annoying issues.

Starting from this release, all TeamCity server JVM options are stored in the exact same way as for command line execution mode - in environment variables.

Issues covered: TW-6450, TW-7467 (for server only), TW-12704, TW-14725, TW-15071, TW-15426, TW-17130, TW-18734, TW-20421.

Build steps execution

In previous TeamCity versions, if your build consisted of several steps, TeamCity made a decision whether to continue build steps execution basing only on an exit code returned by the previous step. If a previous build step returned a non-zero exit code, TeamCity would not execute the subsequent steps at all. As it turned out, this simple logic was too simple for many of our customers: TW-13682.

In TeamCity 7.1 we improved it and now you have a choice of the following options:
Execute step if:

  • Only if all previous steps were successful (default choice, this is how previous versions of TeamCity behaved).
  • Even if some previous steps are failed.
  • Always, even if build stop command was issued.

The last policy can be useful for some cleanup tasks. Note that as in previous TeamCity version whether the step has failed or not is mostly determined by the process exit code.

Read more in our documentation.

Checkout on label in Perforce integration

In Perforce VCS root settings you can now specify the P4 label to use for sources checkout. Changes between the builds using labels are shown simply for informational purposes and are only accurate if the label was moved from one revision to another without labelling specific files.

If a build always checks out a certain fixed revision, a note is shown in the revisions table.

Related issues in the tracker: TW-11070 and TW-5061.

Read more in our documentation.


TeamCity VS-addin and Microsoft Visual Studio 2012

TeamCity VS-addin is now fully compatible with Visual Studio 2012, including dark theme support.

Other updates:

  • "My Investigations" tool window added.

NuGet support

TeamCity 7.1 fully supports NuGet 1.8 and 2.0.

Other improvements are:

  • NuGet Commandline tab now allows to upload a custom NuGet.CommandLine package on the server instead of downloading it from the public feed.
  • NuGet Trigger supports Pre-release packages.
  • NuGet Installer runner no longer requires you to have packages/repository.config file under solution. Now NuGet Installer runner uses Visual Studio solution file (.sln) to create the full list of NuGet packages to install. It also supports Solution-Wide packages from .NuGet/packages.config file. Packages upgrade can be done for entire solution or via packages.config files.

Xcode runner

Xcode runner has been made available as a separate plugin for both TeamCity 6.5 and 7.0. Starting with TeamCity 7.1 it is bundled.

Xcode runner needs to load information from Xcode project files, so once you specify path to the project or workspace, you need to click "Check / Reparse Project" button to load project settings.

A brief list of Xcode runner features:

  • Both Xcode 3 (target-based) and Xcode 4 (scheme-based) projects are supported.
  • Structured build log based on Xcode build stages.
  • Compilation errors are detected and reported to TeamCity.
  • Tests started by xcodebuild are reported on the fly.
  • Various Xcode-related tools installed on the agent are reported via agent parameters to simplify agent requirements configuration.

Read more in our documentation.

Ruby environment configurator

Ruby environment configuration now supports .rvmrc file. So if you have .rvmrc file under version control it is easy to instruct TeamCity to configure Ruby environment from this file.

Read more in our documentation.

Amazon EC2

It is now possible to specify the Amazon Instance ID instead of Image ID in TeamCity cloud profile settings:

  • If image ID is specified, it is run as a usual image and is terminated at the end.
  • If instance ID of a not running EBS-based instance is specified, it is resumed when there is a need for an agent and stopped at the end.

A number of usability improvements has been done, for example, TeamCity now shows cloud agents with starting instances in agent compatibility lists.

Other integrations

  • Eclipse plugin: Eclipse 4.2 is supported
  • Databases: Microsoft SQL Server 2012 is supported
  • Version control: TFS 2012 is supported
  • NAnt 0.92 support added

Other improvements

  • Several cosmetic changes applied all over the web interface
  • Filter to show unused VCS roots added on global VCS roots page in Administration area
  • Number of retry attempts can now be specified in Retry build trigger
  • AssemblyFileVersion field added to AssemblyInfo patcher build feature
  • Ability to navigate to corresponding place in the build log from the failed test popup
  • Agent requirements imposed by parameter references now provide details where in configuration the reference is defined
  • Server usage statistics show statistics about the browsers being used to access TeamCity
  • Counters are shown for a number of configured build parameters, triggers, dependencies and requirements in the right sidebar on build configuration editing pages
  • Server startup logic behind startup screens has been reworked to be more robust
  • Windows user name and password are no longer exposed when you install the build agent service from Windows installer (TW-6425)
  • CORS requests are supported in REST API
  • You can embed TeamCity build status as a simple image into any HTML page via Build Status Icon
  • Tests can now be easily muted and unmuted right from IntelliJ IDEA plugin
  • Diff viewer is now able to highlight many more languages
  • fixed issues

Previous Releases

What's New in TeamCity 7.0