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 in distributed version control systems (DVCS) like Git and Mercurial allow you to work on a feature independently from the repository and commit all the changes for the feature onto the branch, merging the changes back when your feature is complete. This approach brings a number of advantages to software development teams, however in continuous integration servers that do not have dedicated support for it, it also causes a number of problems, like constant build configurations duplication, poor visibility and in the end loss of control of the process.

In TeamCity 7.0 feature branches are partially supported by means of the Branch Remote Run Trigger, that automatically starts a new personal build each time TeamCity detects changes in particular branches of the VCS roots of the build configuration. However, TeamCity 7.1 brings feature branches support on a whole new level, allowing to automate the process, and ensuring visibility of branches all over the interface.

Configuring branches

To start working with branches, you need to tell TeamCity which ones of them you want to be monitored. This is done in a build configurations right in the VCS root.
The syntax of branch names specification is similar to checkout rules:

For further details on branches specification, please refer to Git and Mercurial VCS roots description.
Everything that is matched by the wildcard will be shown as a branch name in TeamCity interface. For example, +:refs/heads/* will match refs/heads/feature1 branch but in TeamCity interface you'll see feature1 only as a branch name.
If you want shortened branch labels in builds, you can use extended syntax of branch specification like this:

In this case, TeamCity will use label 7.0 for builds from the refs/heads/release-7.0 branch and 7.1 for builds from refs/heads/release-7.1.

Specification supports comments – lines started with #.
In order to use brackets in the branch name you need to escape them. To specify escaping symbol put the following as a first line in the specification:

Once you've done branch specification, TeamCity will start to monitor these branches for changes. If your build configuration has VCS trigger and a change is found in some branch, TeamCity will trigger a build in this branch.
From build configuration home page you'll also be able to filter history, change log, pending changes and issue log by branch name. Also branch names will appear in custom build dialog, so you'll be able to manually trigger a custom build on a branch too.

Branch specification & default branch

When configuring Git or Mercurial VCS root, you need to specify "Branch name", which will define so-called "default branch". It is used in situations when branch name was not specified. For example, if someone clicks on a Run button TeamCity will create build in the default branch.

Note that you can also use parameter in branch specification.


Builds from branches are easily recognizable in TeamCity UI, because they are marked with a special label:

You can also filter history by a branch name if you're interested in a particular branch.
TeamCity assigns a branch label to the builds from the default branch too.


For each build TeamCity shows changes included in it. For builds from branches changes calculation process takes branch into account and presents you with changes relevant to the build branch. Changelog with it's graph of commits will help you understand what is going on in the monitored branches.

If the "Show builds" and "Show graph" options are enabled in the change log, TeamCity will display build markers on the graph.

Active branches

In a build configuration with configured branches an Overview page shows active branches.

A branch considered active if:

  • it is present in VCS repository and has recent commits (i.e. commits with the age less than the value of teamcity.activeVcsBranch.age.days parameter, 7 days by default).
  • or it has recent builds (i.e. builds with the age less than the value of teamcity.activeBuildBranch.age.hours parameter, 24 hours by default).

Since TeamCity 7.1.1 you can change the parameters. This can be done either in a build configuration (this will affect one build configuration only), project, or in internal properties (this defines defaults for the entire server.) Parameter in configuration overrides parameter in internal properties.


TeamCity tries to detect new failing tests in a build, and for those tests which are not new, you can see in which build the test started to fail. 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 test details page. So you can see a history of test passes or failures in a single branch.


VCS trigger is fully aware of branches and will trigger build once a check-in is detected in a branch. All VCS trigger options like, per-checkin triggering, quiet period, triggering rules are directly available for builds from branches.


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

It is currently not possible to configure artifact dependencies to retrieve artifacts from a build from a specific branch, artifact dependencies always use builds from default branch. The same applies to finish build trigger. It will only watch for finished builds from default branch.


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

Build configuration status

Build configuration status is calculated based on builds from default branch only. Consequently per-configuration investigation works for builds from default branch. For example, successful build from non-default branch won't remove per-configuration investigation. But successful build from default branch will.

Multiple VCS roots

If your build configuration uses more than one VCS root and in both VCS roots you have specified branches to monitor, the way how builds are triggered is more complicated.

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









Build parameters

Refer to Predefined Build Parameters#BranchProperties for description of branch specific parameters.

See also:

Administrator's Guide: Git (JetBrains) | Mercurial


  1. If I do not want default branch at all? How can I exclude commits to default branch from VCS Trigger?

      1. Nice, thx. Other question is there special .log for actions related to listening "feature branches"? I have seen one for remote-run... but not for "f. branches"

        1. We use teamcity-vcs.log for them also errors should be clear from UI. If they are not, please create an issue in the tracker.

          1. I'm experimenting with "Branch Specification" filters and want to understand what happens in realtime when I set new filters. I'm tring to exclude builds with "default branch" when using build configurations with feature branches with VCS Trigger. I tried provide not fake branch like "mastermaster" but then all "active" feature branches are disappear.

      2. One more question: There is such setting: "Limit the number of simultaneously running builds (0 — unlimited)", so when using "features branches" I want to set limit per branch. How should I do this?

  2. Is there any %property% which has current branch name? I tried to use but it couses errors even in not default branch (

    1. It's in format "refs/heads/YOUR_BRANCH_NAME_HERE"

  3. How can I control "There are 8 active branches in this configuration. 171 inactive branches are not displayed."? I mean how to force branch to inactive state?

    1. I've added a description of active branches, hope it helps.

      1. Can I redefine teamcity.activeVcsBranch.age.days in Build Parameters tab in Build Configuration or it's allowed to do only in config files?

        1. You can use both: parameters in config files affect all the server, parameters in build configuration or project affect only them and override parameters from config files.

            1. Alexander,

              This is a documentation page and it is not meant for asking questions (as there is a forum).

              I am going to delete all unrelated comments within several days. Please back them up if you find them valuable.

  4. Is there a way to change how "special label"s are shown? When it's long it's shorten like "BUG-1...erty" and it's not very useful, I need to show at least full issue prefix like "BUG-1234_...".

    1. Hi, there is no way to do that. Feel free to create a feature request in youtrack.