Manage VCS Roots | TeamCity REST API Reference Documentation

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>

List VCS Root Instances

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.