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 over the process.

TeamCity support for feature branches is continuously increasing, starting from partial support in version 7.0 by 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; moving on to TeamCity 7.1, allowing you to automate the process and ensuring visibility of branches all over the interface. In TeamCity 8.0, the feature branches support is taken to the next level What's New in TeamCity 8.0.

Configuring branches

To start working with DVCS branches, you need to tell TeamCity which of them need to be monitored. This is done via the branch specification field of the VCS root which accepts a list of names or patterns of branch names to watch. The syntax of the branch specification field is similar to VCS Checkout Rules:

The use of * wildcard matches branches and extracts the branch name to be displayed in the TeamCity interface (also known as logicalBranchName): +:refs/heads/* will match refs/heads/feature1 branch, but in the TeamCity interface you'll see feature1 only as a branch name.

To see an extended logical name in the TeamCity interface, use the part of the name to be displayed in brackets: +:refs/heads/(v8.1/*) and in the interface you'll see v8.1/feature1

If you want shortened branch labels in builds, you can use extended syntax of branch specification like this:

+: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, and so on.

Specification supports comments as lines beginning with #.

To use brackets in the branch name, you need to escape them. To do that, specify an escaping symbol as the first line in the specification. Let's say you want to track the release-(7.1) branch. The following branch specification does that:

#! escape: \ +:release-\(7.1\)

The first line in this spec defines the escape symbol to use.

Note that you can also use parameters in the branch specification.

Once you've done branch specification, TeamCity will start to monitor these branches for changes. If your build configuration has Configuring VCS Triggers, TeamCity will trigger a build in this branch.

From the build configuration home page you'll also be able to filter history, change log, pending changes and issue log by the branch name. Branch names will also appear in the custom build dialog, so you'll be able to manually trigger a custom build on a branch too.

Default branch

When configuring a Git or Mercurial VCS root, you need to specify the branch name to be used as the default one in case a branch name was not specified. For example, if someone clicks on a Run button, TeamCity will create a build in the default branch.

Logical branch name

A logical branch name is a branch name shown in the user interface for the builds and on build configuration level. It is calculated by applying a branch specification to the branch name from version control. For example, if the branch specification is defined like this:

+:refs/heads/*

then a part matched by * is a logical branch name. For the default branch <default> can be used.

Builds

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

Changes

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

Active branches

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

A number of parameters define whether a branch is active. Since TeamCity 7.1.1, the parameters can be changed either in a build configuration (this will affect one build configuration only), project, or in the Configuring TeamCity Server Startup Properties (this defines defaults for the entire server). A parameter in the configuration overrides a parameter in the Configuring TeamCity Server Startup Properties.

A branch is considered active if:

• it is present in the 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). A closed VCS branch with builds will still be displayed as active during 24 hours after last build. To remove closed branches from display, set teamcity.activeBuildBranch.age.hours=0.

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, a Configuring VCS Triggers is available on the test details page and you can see a history of test passes or failures in a single branch.

Failure Conditions

If build fail condition is configured as follows: build metric has changed comparing to a last successful/finished/pinned build, then the build from the same branch will be used. If there is no suitable build on the same branch, then build from default branch is used and the corresponding message is added to the build log.

Triggers

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

Additionally, a Configuring VCS Triggers can be specified for the VCS, Schedule and Finish build triggers.

Dependencies

If a build configuration with branches has snapshot dependencies on other build configurations, when a build in a branch is triggered, the other builds in the chain also get the branch associated. In particular:

• all the builds down the chain (which the build depends on) which have the branch in their VCS root (not excluded by the branch specification) will be marked with the branch;

• all the builds up the chain (depending on the build) will be marked with the same branch. If their VCS roots have the branch and it is not excluded by their branch specification, the branch will be checked out. Otherwise the default branch will be checked out.

Starting from TeamCity 8.0, it is possible to configure artifact dependencies to retrieve artifacts from a build from a specific branch: artifact dependencies will use builds from the branch specified. The same applies to the the Schedule and Finish build triggers.

Notifications

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

Build configuration status

The Build Configuration status is calculated based on the builds from the default branch only. Consequently, per-configuration investigation works for builds from the default branch. For example, a successful build from a non-default branch will not remove a per-configuration investigation, but a successful build from the default branch will.

Multiple VCS roots

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

The VCS trigger groups branches from several VCS roots by logicalBranchName. When some root does not have a branch from the other root, its default branch is used. For example, you have 2 VCS roots, both have the default branch refs/heads/master, the first root has the branch specification refs/heads/7.1/* and changes in branches refs/heads/7.1/feature1 and refs/heads/7.1/feature2, the second root has the 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

If you need to get the branch name in the build script or use it in other build configuration settings as a parameter, please refer to Predefined Build Parameters.

Clean-up

Clean-up rules are applied Clean-Up to each ActiveBranches.