VCS Labeling

Automatic VCS labeling

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

Labeling is configured per a build configuration/template, as a build feature. When adding this feature, you need to specify the root to label and a labeling pattern. If there are branches configured for the current build configuration, you can label only builds from specific branches you select.

It is possible to override the labeling settings inherited from a template completely and apply different labels to different VCS roots.

note

Labeling uses credentials specified for the VCS root. The write access to the source repository is required.

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

"Moving" labels (a label with the same name for different builds, for example, 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 post.

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 menu.

Manual labeling uses the VCS settings actual for the build.

Subversion Labeling Rules

To label Subversion VCS roots, it is required to set labeling rules defining the SVN repository structure.

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

TrunkOrBranchRepositoryPath => tagDirectoryRepositoryPath

The repository paths can be relative and absolute (starting with /). 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:

-project
--trunk
--branch1
--branch2
--tags

In this case, the labeling rules should be:

/project/trunk=>/project/tags
/project/branch1=>/project/tags
/project/branch2=>/project/tags

Labeling in Perforce

Since 2021.2, TeamCity creates automatic labels instead of static ones. Automatic labels work as aliases for changelists. In a label's Revision field, TeamCity displays the revision checked out in the current build. For the View field, it uses the mapping associated with all paths of the current VCS root.

For Perforce labels, TeamCity supports only include rules and ignores exclude rules.

If you prefer using static labels, you can enable the previous behavior by setting the teamcity.perforce.useStaticLabels=true internal property.

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:

/projects/%projectName%/trunk => /projects/%projectName%/tags

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:

/project/trunk => /tagged_configurations/%%system.build.label%%/project
/modules/module1/trunk => /tagged_configurations/%%system.build.label%%/module1
/modules/module2/trunk => /tagged_configurations/%%system.build.label%%/module2

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