Manage Build Configurations
This article lists REST API requests concerning build configurations and build configuration templates.
Get build configuration/template details |
GET http://<TeamCity Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/paused
Put |
Build configuration settings |
GET/DELETE/PUT http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>
|
Build configuration parameters |
GET/DELETE/PUT http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>
It produces XML, JSON, and plain text depending on the |
Build configuration steps |
GET/DELETE http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>
|
Create build configuration step |
POST http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps
The XML/JSON posted is the same as retrieved by GET request to |
Features, triggers, agent requirements, artifact, and snapshot dependencies follow the same pattern as steps (above) with the respective URLs |
http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/features/<id>
http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/triggers/<id>
http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/
http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>
http://<TeamCity Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled
Put |
Build configuration VCS roots |
GET/DELETE http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>
|
Attach VCS root to a build configuration |
POST http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries
The XML/JSON posted is the same as retrieved by GET request to |
Create a new build configuration with all settings |
POST http://<TeamCity Server host>:<port>/app/rest/buildTypes
The XML/JSON posted is the same as retrieved by GET request. Note that |
Create a new empty build configuration |
|
Copy a build configuration |
POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:XXX' copyAllAssociatedSettings='true' shareVCSRoots='false'/>
to |
Read, detach, and attach a build configuration from/to a template | Since TeamCity 2017.2:
GET/DELETE/POST/PUT http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates
Before TeamCity 2017.2:
GET/DELETE/POST/PUT http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/template
Put accepts template locator with the |
Set build number counter |
curl -v --basic --user <username>:<password> --request PUT http://<<TeamCity Server host>:<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 Server host>:<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.