VCS Labeling

TeamCity can label (tag) sources of a particular build (automatically or manually) in your version control. The list of labels applied and their application status is displayed on the on the Changes tab of the build results page.

Automatic VCS labeling

You can set TeamCity to label the sources of a build depending on the build status automatically. The process takes place in the background after the build finishes and does not affect the build status, which means that a labeling failure is not a standard notification event. However, the users subscribed for notifications about failed builds of the current build configuration will be notified about a labeling failure.

Any errors encountered during labeling are reported on the Changes tab of the build results page.

Labeling is configured for a build configuration/template.

Automatic VCS labeling is configured on the Build Features page of the Build Configuration settings.

To configure automatic labeling, you need to specify the root to label and the labeling pattern. If you have branches configured for your build configuration, you can label builds from branches you select.

You can override the labeling settings inherited from a template completely; you can also apply different labels to different VCS roots.

Note that if you change the VCS settings of a build configuration, they will be used for labeling only in the new builds.

"Moving" labels (a label with the same name for different builds, e.g. "SNAPSHOT") are currently supported only for CVS.

For an example of using the Teamcity VCS labeling feature to automate tag creation, refer to this external posting.

Manual VCS labeling

To label the sources manually:

Navigate to the build results page, click Actions and select Label this build sources from the drop-down.

Manual labeling uses the VCS settings actual for the build.

Subversion Labeling Rules

To label Subversion VCS roots, additional configuration - labeling rules defining the SVN repository structure - is required.

Labeling rules are specified as newline-delimited rules in the following format:

The repository paths can be relative and absolute (starting from "/"). Absolute paths are resolved from the SVN repository root (the topmost directory you have in your repository), relative paths are resolved from the TeamCity VCS root.

When creating a label, the sources residing under TrunkOrBranchRepositoryPath will be put into the tagDirectoryRepositoryPath/tagName directory, where tagName is the name of the label as defined by the labeling pattern of the build configuration. If no sources match the TrunkOrBranchRepositoryPath, no label will be created. The tagDirectoryRepositoryPath path must already exist in the repository. If the tagDirectoryRepositoryPath directory already contains a subdirectory with the current label name, the labeling process will fail, and the old tag directory won't be deleted or affected.

For example, there is a VCS root with the URL svn://address/root/project where svn://address/root is the repository root, and the repository has the structure:

In this case the labeling rules should be:

Labeling Rule Examples

You can use variables substitution in both labeling rules and labeling patterns. See a labeling rule example in a VCS root used in different configurations:

This will require you to set the %\projectName% configuration parameter in the build configuration settings.

By default, TeamCity will append the label name to the end of the specified target path. If you want to have a different directory structure and put the label in the middle of the target path, you can use the following syntax:

Thus, %\%system.build.label%\% will be replaced with the tag name (please note the double %% sign at the beginning - it is important).