|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.|
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.
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.
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.
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.
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.
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.
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.
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:
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:
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:
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:
A number of existing features in TeamCity were affected by branches support.
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.
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.
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:
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.
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.
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:
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:
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:
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.
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.
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".
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.
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
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.
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.
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.
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:
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.
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.
Read more in our documentation.
TeamCity VS-addin is now fully compatible with Visual Studio 2012, including dark theme support.
TeamCity 7.1 fully supports NuGet 1.8 and 2.0.
Other improvements are:
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:
Read more in our documentation.
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.
It is now possible to specify the Amazon Instance ID instead of Image ID in TeamCity cloud profile settings:
A number of usability improvements has been done, for example, TeamCity now shows cloud agents with starting instances in agent compatibility lists.