Working with Feature Branches

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:

+:refs/heads/release-(7.0) +:refs/heads/release-(7.1)

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:

#! escape: \

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

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

Changes

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.

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 Configuring TeamCity Server Startup Properties (this defines defaults for the entire server.) Parameter in configuration overrides parameter in Configuring TeamCity Server Startup Properties.

Tests

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.

Triggers

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.

Dependencies

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.

Notifications

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 for description of branch specific parameters.