TeamCity 2021.1 Help

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