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/configView the current value of the specific configuration setting.
/app/rest/projects/{locator}/versionedSettings/config/parameters/{name} # Example /app/rest/projects/DotNetSamples/versionedSettings/config/parameters/allowUIEditingEdit 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/allowUIEditingModify 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/checkForChangesCommit current project settings to the related VCS.
/app/rest/projects/{locator}/versionedSettings/commitCurrentSettingsLoad 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/projectsRequest 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-rootsRequest 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/configRequest 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/affectedProjectsObtain the list of context parameters. To modify an existing parameter, send the POST request with the VersionedSettingsContextParameters body.
/app/rest/projects/{locator}/versionedSettings/contextParametersReturn 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/statusReturn 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