Manage VCS Roots
This article lists REST API requests concerning VCS roots .
List VCS Roots To get all VCS roots, use:
/app/rest/vcs-roots
Endpoint responds with VcsRoots entity which contains instances of VcsRoot .
To get specific root(s), use:
/app/rest/vcs-roots/<vcsRootLocator>
The vcsRootLocator
is typed as a VcsRootLocator entity. For example, to get a VCS root with ID MyCustomRoot
use:
/app/rest/vcs-roots/id:MyCustomRoot
To get all Git-based VCS roots, use:
/app/rest/vcs-roots/type:jetbrains.git
Create VCS Root To create a new VCS root, POST a VcsRoot entity to:
/app/rest/vcs-roots
Example payload:
<vcs-root id="MyCustomRoot" name="MyCustomRoot" vcsName="jetbrains.git">
<project id="MyCustomProject"/>
<properties count="3">
<property name="authMethod" value="ANONYMOUS"/>
<property name="branch" value="refs/heads/master"/>
<property name="url" value="https://mygitserver.com/myrepo"/>
</properties>
</vcs-root>
{
"id": "MyCustomRoot",
"name": "MyCustomRoot",
"vcsName": "jetbrains.git",
"project": {
"id": "MyCustomProject"
},
"properties": {
"property": [
{
"name": "authMethod",
"value": "ANONYMOUS"
},
{
"name": "branch",
"value": "refs/heads/master"
},
{
"name": "url",
"value": "https://mygitserver.com/myrepo"
}
]
}
}
Delete VCS Root To delete a VCS root, use:
/app/rest/vcs-roots/<vcsRootLocator>
Update VCS Root Definition You can retrieve a certain VCS root property via:
/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>
and update it with the PUT request using text/plain
body:
/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>
Similarly, you can use GET/PUT
to receive and update field values (id
, name
, or project
— the latter accepts ProjectLocator for associating a VCS root with a specific project):
/app/rest/vcs-roots/<vcsRootLocator>/<property_name>
/app/rest/vcs-roots/<vcsRootLocator>/<property_name>
List VCS Root Instances VCS root is a setting configured in the TeamCity UI. VCS root instance is an internal TeamCity entity which is derived from the VCS root to perform the actual VCS operation. If a VCS root has no %
-references to parameters, a single VCS root corresponds to a single VCS root instance. A single VCS root can generate several VCS root instances: for example, if a VCS root has %
-reference to a parameter and the reference resolves to a different value, when the VCS root is attached to different configurations, or when a custom build is run.
To get VCS root instances, use:
/app/rest/vcs-root-instances?locator=<vcsRootInstanceLocator>
vcsRootInstanceLocator
is typed as VcsRootInstanceLocator . For example, to get all instances of a VCS root with the MyVCSRoot
ID use:
/app/rest/vcs-root-instances?locator=vcsRoot:(id:MyVCSRoot)
Post Commit Hook Notification To notify TeamCity about a new commit from the commit hook context, use:
/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstanceLocator>
It schedules checking for changes for the matched VCS root instances and returns a plain-text human-readable message on the action performed; HTTP response 202 in case of successful operation.
Last modified: 29 March 2022