Icon

You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.1 documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 
Skip to end of metadata
Go to start of metadata

VCS Roots in TeamCity

A VCS root defines a connection to a version control system and consists of a set of settings (paths to sources, username, password, and other settings) that defines how TeamCity communicates with a version control (SCM) system to monitor changes and get sources for a build. A VCS root can be attached to a build configuration or template. You can add several VCS Roots to a build configuration or a template and specify portions of the repository to checkout and target paths via VCS Checkout Rules.


VCS roots are created in a project and are available to all the Build Configurations defined in that project or its subprojects.


You can view all VCS roots configured within the project and create/edit/delete/detach them using the VCS Roots page under the project settings in the Administration UI.
If someone attempts to modify a VCS root that is used in more than one project or build configuration, TeamCity will issue a warning that the changes to the VCS root could potentially affect other projects or build configurations. The user is then prompted to either save the changes and apply them to all the affected projects and build configurations, or to make a copy of the VCS root to be used by either a specific build configuration or project.

On an attempt to create a new VCS root, TeamCity checks whether there are other VCS roots accessible in this project with similar settings. If such VCS roots exist, TeamCity suggests using them.

Once a VCS root is configured, TeamCity regularly queries the version control system for new changes and displays the changes in the Build Configurations that have the root attached. You can set up your build configuration to trigger a new build each time TeamCity detects changes in any of the build configuration's VCS roots, which suits most cases. When a build starts, TeamCity gets the changed files from the version control and applies the changes to the Build Checkout Directory.

Common VCS Root Properties

Property

Description

Type of VCS

Type of Version control system supported by TeamCity, for example, Perforce, Subversion, etc

VCS root name

Unique name of VCS root across all VCS roots of the project.

VCS root ID

Unique ID of VCS root across all VCS roots in the system. VCS root ID can be used in parameter references to VCS root parameters and REST API. If not specified, will be generated automatically from VCS root parameters.

Repository URL

URL to VCS repository. Supports URLs in different formats, like: http(s)://, svn://, ssh://git@, git:// and others as well as URLs in Maven format.

Minimum checking interval

Specifies how often TeamCity polls the VCS repository for VCS changes. By default, the global predefined server setting is used that can be modified on the Administration | Global Settings page. The interval time starts as soon as the last poll is finished on the per-VCS root basis. Here you can specify a custom interval for the current VCS root.

Icon

Some public servers may block access if polled too frequently.

If TeamCity detects that a VCS commit hook is used to trigger checking for changes, this interval is automatically increased up to the predefined value (4 hours). If the periodical check finds changes undetected via the commit hook, the checking interval is reset to the specified minimum.

Belongs to project

Each VCS root belongs to some project, and in this section the name of this project is displayed. A VCS root can be moved to the common parent project of all subprojects, build configurations and templates where the root is currently used.

Please refer to the following pages for VCS-specific configuration details:

Icon

Make sure to synchronize the system time at the VCS server, TeamCity server and TeamCity agent (if agent-side checkout is used) if you use the following version controls:

  • CVS
  • StarTeam (if the audit is disabled or the server version is older than 9.0).
  • Subversion repositories connected through externals to the main repository defined in the VCS root.
  • VSS (all VSS clients and TeamCity server should have synchronized clocks)