Manage Version Control Settings

TeamCity allows you to store project settings as configuration files kept inside VCS repositories. These settings can be stored in the simple XML format, or using the Kotlin programming language.

In TeamCity UI, version control settings can be accessed on the Administration | Project Settings | Versioned Settings page. This article explains how to read and modify the same settings via REST API.

All endpoints related to versioned settings start with /app/rest/projects/project_locator/versionedSettings/....

View and Edit Common Configuration Settings

The current versioned settings configuration can be viewed and edited via the ...config endpoint.

View configuration
/app/rest/projects/{locator}/versionedSettings/config
View the current value of the specific configuration setting.
/app/rest/projects/{locator}/versionedSettings/config/parameters/{name} # Example /app/rest/projects/DotNetSamples/versionedSettings/config/parameters/allowUIEditing
Edit the specific configuration setting. The new value is passed in the text/plain format in the request body.
/app/rest/projects/{locator}/versionedSettings/config/parameters/{name} # Example # Request body: "false" /app/rest/projects/DotNetSamples/versionedSettings/config/parameters/allowUIEditing
Modify the entire configuration. The request body must contain payload according to the VersionedSettingsConfig schema.
/app/rest/projects/{locator}/versionedSettings/config # Example # Request body (JSON): {"allowUIEditing":"true","buildSettingsMode":"alwaysUseCurrent", # "format":"xml","showSettingsChanges":"false","storeSecureValuesOutsideVcs":"true", # "syncronizationMode":"enabled", # "vcsRootId":"DotNetSamples_HttpsGithubComValravnTeamcityDotnetSamples2refsHeadsMaster"} /app/rest/projects/DotNetSamples/versionedSettings/config

Synchronize Settings

Emulate a click on the Versioned Settings | Change Log | Check for changes button. Schedules the TeamCity task to check for pending changes.
/app/rest/projects/{locator}/versionedSettings/checkForChanges
Commit current project settings to the related VCS.
/app/rest/projects/{locator}/versionedSettings/commitCurrentSettings
Load settings from the related VCS and override current project settings. In case of success, the response returns the list of all synchronized projects.
/app/rest/projects/{locator}/versionedSettings/loadSettings

Automatically Create TeamCity Projects from New Repositories

If you set up an automation task that periodically scans your organization account and finds all repositories with the .teamcity folder, you can add the following sequence of REST API requests to this task so that it automatically imports all new projects to TeamCity.

Create a new blank project.
/app/rest/projects
Request Body:
<newProjectDescription copyAllAssociatedSettings="true" id="NewProjID" name="New Empty Project"> <parentProject locator="id:_Root" /> </newProjectDescription>
{ "parentProject": { "locator": "id:_Root" }, "name": "New Empty Project", "id": "NewProjID", "copyAllAssociatedSettings": true }
Create a new VCS root for this new project.
/app/rest/vcs-roots
Request Body:
<vcs-root id="NewProjID_NewRootID" name="NewRoot" vcsName="jetbrains.git"> <project id="NewProjID"/> <property name="authMethod" value="ACCESS_TOKEN"/> <property name="branch" value="refs/heads/main"/> <property name="url" value="REPO_URL"/> <property name="tokenId" value="YOUR_ACCESS_TOKEN"/> </properties> </vcs-root>
{ "id": "NewProjID_NewRootID", "name": "NewRoot", "vcsName": "jetbrains.git", "project": { "id": "NewProjID" }, "properties": { "property": [ { "name": "authMethod", "value": "ACCESS_TOKEN" }, { "name": "branch", "value": "refs/heads/main" }, { "name": "url", "value": "REPO_URL" }, { "name": "tokenId", "value": "YOUR_ACCESS_TOKEN" } ] } }
Set up version control settings for your new project.
/app/rest/projects/<PROJECT_ID>/versionedSettings/config
Note that once you enable settings versioning, a conflict between the current project settings and settings stored in the VCS emerges. To resolve this conflict, set the importDecision parameter to "importFromVCS" to tell TeamCity it should import project settings from the repository.
Request body:
<versionedSettingsConfig allowUIEditing="true" buildSettingsMode="alwaysUseCurrent" format="kotlin" showSettingsChanges="false" storeSecureValuesOutsideVcs="true" synchronizationMode="enabled" vcsRootId="NewProjID_NewRootID" importDecision="importFromVCS"/>
{ "format": "kotlin", "synchronizationMode": "enabled", "allowUIEditing": true, "storeSecureValuesOutsideVcs": true, "portableDsl": true, "showSettingsChanges": true, "vcsRootId": "NewProjID_NewRootID", "buildSettingsMode": "alwaysUseCurrent", "importDecision": "importFromVCS" }

After step #3, your new project will apply settings specified in the .teamcity directory files. If needed, you can send another POST request to the /app/rest/projects/<PROJECT_ID>/versionedSettings/loadSettings endpoint to manually re-apply settings from the repository.

Other Tasks

View all subprojects whose versioned settings are inherited from the current project.
/app/rest/projects/{locator}/versionedSettings/affectedProjects
Obtain the list of context parameters. To modify an existing parameter, send the POST request with the VersionedSettingsContextParameters body.
/app/rest/projects/{locator}/versionedSettings/contextParameters
Return the message displayed on the Versioned Settings | Configuration page. This message conveys the result of the most recent settings update.
/app/rest/projects/{locator}/versionedSettings/status
Return the list of tokens. You can send POST and DELETE requests to this endpoint to create new and remove existing tokens. Note that you can only remove currently unused tokens.
/app/rest/projects/{locator}/versionedSettings/tokens

Last modified: 08 September 2023