Configuring VCS Settings

Added by Irina Megorskaya, last edited by Ekaterina Ivanova on May 23, 2008  (view change)
Documentation Index

Configuring VCS Settings

This section provides notes on configuring the following VCS Settings:

Configuring VCS Roots

A VCS Root is a description (a number of connection settings) of a version control system where project sources are located.

VCS roots are configured on the Version Control Systems page of a build configuration.

Note to users upgrading from version 2.1.1
Starting with version 3.0, VCS roots are now specific to build configurations rather than projects.
System time at the VCS server and the machines that check out the project sources (server or agents, depending on the value of the build configuration VCS checkout mode setting) must be synchronized.
This requirement applies to CVS, Subversion, and ClearCase configurations, as well as to StarTeam if the audit is disabled or the server is older than 9.0.

Shared VCS Roots

By default, the same VCS root(s) can be used by all of the project's build configurations. They can also be used by different projects when VCS Roots Sharing is enabled on the New or Edit VCS Roots page. Sharing VCS roots saves the administrator's time and the hassle of creating and maintaining identical VCS roots in the repository.

If someone attempts to modify a VCS root that is shared, TeamCity will issue a warning that the changes to the VCS root could potentially affect more that one project. The user is then prompted to either save the changes and apply them to all the projects using the VCS root, or to make a copy of the VCS root for use by either a specific build configuration or project.

VCS Checkout Mode

The VCS Checkout mode is a configuration that sets how project sources reach an agent. Agents do not need any additional software for automatic checkout modes.

TeamCity has three different VCS checkout modes:

Checkout mode Description
Automatically on server The TeamCity server will export the sources and pass them to an agent before each build. Since sources are exported rather than checked out, no administrative data is stored in the file system and version control operations (like check in or label or update) can not be preformed.
Automatically on agent The build agent will check out the sources before the build. This checkout mode is supported only for CVS and Subversion. Agent-side checkout frees more server resources and provides the ability to access version control-specific directories (.svn, CVS) i.e. the build script can perform VCS operations (like check-ins into the version control) - in this case please ensure the build script uses necessary credentials for the check-in.
Please note that "exclude" Checkout Rules cannot improve agent checkout performance because it checks out the entire included directory, then deletes the files that were excluded.
Do not check out files automatically TeamCity will not check out any sources. The build script will contain the commands to check out the sources. Please note that this mode can cause TeamCity to inaccurately report changes.

VCS Checkout Rules

VCS Checkout Rules allow you to exclude paths and/or map paths (copy directories and all their contents) to a different location on the Build Agent during checkout.

To add a checkout rule click the edit checkout rules link on the build configuration's Version Control Settings page and a pop-up window will appear where you can enter the rule.

The general syntax of a single checkout rule is as follows:

+|- : VCSPath [=> AgentPath]

When entering rules please note the following:

  • To enter multiple rules, each rule should be entered on a separate line.
  • For each file the most specific rule will apply if the file is included, regardless of what order the rules are listed in.
  • If you don't enter an operator it will default to +:

Rules can be used to perform the following operations:

Syntax Explanation
+:.=>Path Checks out the root into Path directory
-:PathName Excludes PathName (note: the path must be a directory and not a filename)
+:VCSPath=>. Maps the VCSPath from the VCS to the Build Agent's default work directory
VCSPath=>NewAgentPath Maps the VCSPath from the VCS to the NewAgentPath directory on the Build Agent
+:VCSPath Maps the VCSPath from the VCS to the same-named directory (VCSPath) on the Build Agent

An example with three VCS checkout rules:

-:src/help
+:src=>production/sources
+:src/samples=>./samples

In the above example, the first rule excludes the src/help directory and its contents from checkout. The third rule is more specific than the second rule and maps the scr/samples path to the samples path in the Build Agent's default work directory. The second rule maps the contents of the scr path to the production/sources on the build agent, except src/help which was excluded by the first rule and scr/samples which was mapped to a different location by the third rule.

Exclude checkout rules will only speed up server-side checkouts. Agent-side checkouts emulate the exclude checkout rules by checking out all the root directories mentioned as include rules and deleting the excluded directories. So, exclude checkout rules should generally be avoided for the agent-side checkout.

VCS Labeling Support

TeamCity can optionally add a label into the version control system for the sources used for a particular build. This is useful if you need to collect all of the sources for a specific build in order to recreate it. You can choose to apply the VCS label for all builds or only for successful ones. You can also manually invoke VCS labeling action for a finished build: Check "Label this build sources" in the "VCS revisions and labels" section of the Changes tab of the build results.

The labeling process takes place after the build finish and doesn't affect the build status. If the label fails it will not change the build's status.

VCS labeling is supported for ClearCase, CVS, Perforce, StarTeam and Subversion.

  • Make sure the credentials you specify allow write access to the sources repository.
  • Perforce roots require specification of Perforce client (not TeamCity mapping) for labeling to work.
"Moving" labels (label with the same name for different builds e.g. "SNAPSHOT") are currently supported only for CVS

Subversion

Subversion VCS roots need additional configuration for VCS labeling to work. The labeling rules need to be specified to define the SVN repository structure.

Labeling rules are specified as newline-delimited rules each of uses the following format:

TrunkOrBranchRepositoryPath => tagDirectoryRepositoryPath

The repository paths can be relative and absolute (starting from "/"). Absolute paths are resolved from the SVN repository root, relative paths are resolved from the 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, then no label will be created.
The path tagDirectoryRepositoryPath should already exist in the repository.
If tagDirectoryRepositoryPath directory already contains 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

See also:

Labels