VCS Labeling
TeamCity can label (tag) sources of a particular build (automatically or manually) in your Version Control System. The list of applied labels and their application status is displayed on the Changes tab of Build Results.
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 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:
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:
In this case, the labeling rules should be:
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:
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 (note the double %%
sign at the beginning — it is important).