TeamCity 2020.2 Help

Manage Build Configurations

This article lists REST API requests concerning build configurations and build configuration templates.

Get build configuration/template details

GET http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildConfigurationLocator>

Read more on the build configuration locator.

Note that there is no transaction, for example support for settings editing in TeamCity, so all the settings modified via REST API are taken into account at once. This can result in half-configured builds triggered and other issues. Make sure you pause a build configuration before changing its settings if this aspect is important for your case.

To get aggregated status for several build configurations, see the Build Status Icon article.

Get/set paused build configuration state

GET/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/paused

Put true or false text as text/plain.

Build configuration settings

GET/DELETE/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>

Build configuration parameters

GET/DELETE/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>

It produces XML, JSON, and plain text depending on the Accept header, accepts plain text, XML, and JSON. The .../parameters/<parameter_name>/name and .../parameters/<parameter_name>/value requests are also supported.

Build configuration steps

GET/DELETE http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>

Create build configuration step

POST http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps

The XML/JSON posted is the same as retrieved by GET request to .../steps/<step_id> except for the secure settings like password: these are not included into responses and should be supplied before POSTing back.

Features, triggers, agent requirements, artifact, and snapshot dependencies follow the same pattern as steps (above) with the respective URLs

http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/features/<id> http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/triggers/<id> http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/ http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id> http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies/<id>

Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements.

Disable/enable an artifact dependency

PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled

Put true or false text as text/plain.

Build configuration VCS roots

GET/DELETE http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>

Attach VCS root to a build configuration

POST http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries

The XML/JSON posted is the same as retrieved by GET request to http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id> except for the secure settings like password: these are not included into responses and should be supplied before POSTing back.

Create a new build configuration with all settings

POST http://<TeamCity URL>:<port>/app/rest/buildTypes

The XML/JSON posted is the same as retrieved by GET request. Note that /app/rest/project/XXX/buildTypes still uses the previous version notation and accepts another entity.

Create a new empty build configuration

POST plain text (name) to http://<TeamCity URL>:<port>/app/rest/projects/<projectLocator>/buildTypes.

Copy a build configuration

POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:XXX' copyAllAssociatedSettings='true' shareVCSRoots='false'/>

to http://<TeamCity URL>:<port>/app/rest/projects/<projectLocator>/buildTypes.

Read, detach, and attach a build configuration from/to a template

Since TeamCity 2017.2:

GET/DELETE/POST/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates

Before TeamCity 2017.2:

GET/DELETE/POST/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/template

Put accepts template locator with the text/plain Content-Type).

Set build number counter

curl -v --basic --user <username>:<password> --request PUT http://<<TeamCity URL>:<port>>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberCounter --data <new number> --header "Content-Type: text/plain"

Set build number format

curl -v --basic --user <username>:<password> --request PUT http://<<TeamCity URL>:<port>>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberPattern --data <new format> --header "Content-Type: text/plain"

Build Configuration Locator

The most frequently used values for <buildTypeLocator> are id:<buildConfigurationOrTemplate_id> and name:<Build%20Configuration%20name>.

Since TeamCity 2017.2, the experimental type locator is supported with one of the values: regular, composite, or deployment.

Other supported dimensions are (these are in experimental state):

  • internalId – internal ID of the build configuration.

  • project<projectLocator> to limit the build configurations to those belonging to a single project.

  • affectedProject<projectLocator> to limit the build configurations under a single project (recursively).

  • template<buildTypeLocator> of a template to list only build configurations using the template.

  • templateFlag – boolean value to get only templates or only non-templates.

  • paused – boolean value to filter paused/not paused build configurations.

Last modified: 21 December 2020