Configuring VCS Roots
A VCS root is a cornerstone of the TeamCity ←→ VCS repository communication. This integral element defines a connection to a VCS provider required to perform a wide range of operations: repository checkout, code sources tagging, communicating build statuses back to VCS, and so on.
VCS roots store the following information:
Fetch and push URLs that TeamCity uses to pull and push remote files.
Branch information: the list of repository branches TeamCity should track and which branch is the default (main) one.
Authentication settings: credentials TeamCity uses to access a repo.
Checkout settings: specify how remote files should be stored and whether submodules should be checked out along with the main repository.
Custom changes polling settings that allow you to override the default 60-second interval.
Sections related to VCS roots are available in both project and configuration settings.
However, configurations never own roots. You can "attach" a VCS root to a configuration, but roots are always stored in (owned by) projects. This technique results in the following:
A VCS root can be attached to multiple configurations, meaning that multiple build configurations can access the same repository with the same auth and checkout settings.
A single configuration may have multiple VCS roots attached, which allows you to work with different repositories within one configuration.
Editing VCS roots affects all configurations that use it. When modifying VCS root settings, you have an option to duplicate this root and store updated settings in this new clone, keeping the original root unchanged. This allows you to customize one build configuration but leave other configurations that share this root unaffected.
Although a VCS root is an existential part of any build configuration that works with a remote repository, in many scenarios TeamCity generates roots automatically and does not require that you create them by hand for each new build configuration. See this tutorial for an example.
Common VCS Root Properties
- Type of VCS
The type of version control system supported by TeamCity. For example, Git, Perforce, Subversion, and more.
- VCS root name
The unique name of VCS root across all VCS roots of the project. This is the public name shown in TeamCity UI (for example, in the build configuration's "Attach VCS root" menu).
- VCS root ID
Unique ID of VCS root across all VCS roots in the system. By default, the root ID combines truncated names of its parent project and the root itself, divided with an underscore. For example,
MyProject_HttpsGitHubComJohndoeMyrepoRefsHeadsMain. When changing the root name, you can click the Regenerate ID link to update this value.Root IDs are used in build parameters that allow you to read root properties, for example
vcsroot.ProjectName_RootName.branchandvcsroot.ProjectName_RootName.url. In addition, IDs can be used in REST API.- Repository URL
The URL of a VCS repository. Supports URLs in different formats, like:
http(s)://,svn://,ssh://git@,git://and others as well as URLs in Maven format.If a project (or its parent projects) has connections to VCS providers, TeamCity displays corresponding VCS icons next to this field. If you have multiple connections to the same provider (for example, GitHub OAuth and GitHub App), hover over an icon to see the connection name.
Click an icon to view the list of repositories TeamCity detected using this connection. Since a connection stores all necessary repo access data, not only does selecting a repository fill in the Repository URL, but it also fills authentication settings (Username and Password / Access token).
- Minimum polling 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.
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 polling interval is reset to the specified minimum.
- Belongs to project
Displays the project that owns this VCS root. You can move a VCS root to a parent project so that it becomes available for all build configurations inside this new owner and its subprojects.
Refer to the pages inside this section for VCS-specific configuration details.