Manage VCS Roots

This article lists REST API requests concerning VCS roots.

VCS Roots


List all VCS roots	GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots Add the `locator=<vcsRootLocator>` parameter to list only the matched VCS roots.
Get details of a VCS root/delete a VCS root	GET/DELETE http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator> where `<vcsRootLocator>` can be `id:<internal VCS root id>` or other VCS root locator.
Create a new VCS root	`POST VCS root XML` (similar to the one retrieved by a GET request for VCS root details) to `http://<TeamCity Server host>:<port>/app/rest/vcs-roots`. Also supported: `GET/PUT` `http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>` `GET/PUT` `http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>/<field_name>` where `<field_name>` is `id`, `name`, `project` (post the project locator to `project` to associate a VCS root with a specific project).
List VCS root instances*	GET http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>

Since TeamCity 10.0:

There are two endpoints dedicated to being used in commit hooks from the version control repositories: POST http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances/checkingForChangesQueue?locator=<vcsRootInstancesLocator>

It schedules checking for changes for the matched VCS root instances and returns the list of VCS root instances matched (just like GET http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator> ): POST http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstancesLocator>

It schedules checking for changes for the matched VCS root instances and returns plain-text human-readable message on the action performed, HTTP response 202 in case of successful operation.

Both perform the same action (put the VCS root instances matched by the <locator>) to the queue for "checking for changes" process and differ only in responses they produce.

Note that since the matched VCS root instances are the same as for ../app/rest/vcs-root-instances?locator=<locator> request and that means that by default only the first 100 are matched and the rest are ignored. If this limit is reached, consider tweaking the <locator> to match fewer instances (recommended) or increase the limit, for example by adding ,count:1000 to the locator.

VCS root instance locator

Some supported <vcsRootInstancesLocator> from above:

type:<VCS root type> — VCS root instances of the specified version control (for example, jetbrains.git, mercurial, svn ).
vcsRoot:(<vcsRootLocator>) — VCS root instances corresponding to the VCS root matched by <vcsRootLocator>.
buildType:(<buildTypeLocator>) — VCS root instances attached to the matching build configuration.
property:(name:<name>,value:<value>,matchType:<matching>) — VCS root instances with the property of name <name> and value matching condition <matchType> (for example, equals, contains) by the value <value>.

Last modified: 20 February 2021