Manage VCS Roots

To get all VCS roots, use:

GET
/app/rest/vcs-roots

Endpoint responds with VcsRoots entity which contains instances of VcsRoot.

To get specific root(s), use:

GET
/app/rest/vcs-roots/<vcsRootLocator>

The vcsRootLocator is typed as a VcsRootLocator entity. For example, to get a VCS root with ID MyCustomRoot use:

GET
/app/rest/vcs-roots/id:MyCustomRoot

To get all Git-based VCS roots, use:

GET
/app/rest/vcs-roots/type:jetbrains.git

To create a new VCS root, POST a VcsRoot entity to:

POST
/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"
            }
        ]
    }
}

To delete a VCS root, use:

DELETE
/app/rest/vcs-roots/<vcsRootLocator>

You can retrieve a certain VCS root property via:

GET
/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>

and update it with the PUT request using text/plain body:

PUT
/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>

You can also use the DELETE request with an empty body to delete the property:

DELETE
/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):

GET
/app/rest/vcs-roots/<vcsRootLocator>/<property_name>

PUT
/app/rest/vcs-roots/<vcsRootLocator>/<property_name>

tip

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:

GET
/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:

GET
/app/rest/vcs-root-instances?locator=vcsRoot:(id:MyVCSRoot)

To notify TeamCity about a new commit from the commit hook context, use:

POST
/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.