TeamCity REST API Reference 2023.11 Help

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.

  1. 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 }
  2. 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" } ] } }
  3. Set up version control settings for your new project.

    /app/rest/projects/<PROJECT_ID>/versionedSettings/config

    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