TeamCity 2021.1 Help

Edit Build Configuration Settings

This article shows how to edit build configurations via TeamCity REST API.
For every endpoint below, you can use GET (retrieve), POST (create), PUT (update existing) or DELETE (delete) HTTP methods to update the corresponding resource. For POST/PUT, use the payload from the corresponding section as an example.

Manage Build Parameters

To get all build parameters, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/parameters

To fetch a specific parameter by name, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>

Parameters can be created/updated by sending Property (or a group of parameters, formed as Properties) entity to the above endpoints:

<property name="string" value="string" />
{ "name" : "name", "value" : "value" }

To update a parameter's value, PUT a new value in the text/plain format to:

PUT http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>/value

Manage Build Steps

To get all build steps, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps

Requests respond with a Steps or Step entity, which is also expected in the modifying requests.

Example payload (a command line step that prints "Hello World!"):

<steps> <step name="myCommandLineStep" type="simpleRunner"> <properties count="4"> <property name="script.content" value="echo 'Hello World!'"/> </properties> </step> </steps>
{ "step": [ { "name": "myCommandLineStep", "type": "simpleRunner", "properties": { "property": [ { "name": "script.content", "value": "echo 'Hello World!'" } ] } } ] }

Manage Build Features

To get all build features, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/features

Requests respond with Features or Feature entity, which is also expected in the modifying requests.

Example payload (a simple setup of a Commit Status Publisher feature):

<features> <feature type="commit-status-publisher"> <properties> <property name="github_authentication_type" value="token"/> <property name="github_host" value="https://api.github.com"/> <property name="publisherId" value="githubStatusPublisher"/> <property name="secure:github_access_token" value="someToken"/> <property name="vcsRootId" value="MyVCSRootId"/> </properties> </feature> </features>
{ "feature": [ { "type": "commit-status-publisher", "properties": { "count": 5, "property": [ { "name": "github_authentication_type", "value": "token" }, { "name": "github_host", "value": "https://api.github.com" }, { "name": "publisherId", "value": "githubStatusPublisher" }, { "name": "secure:github_access_token", "value": "someToken" }, { "name": "vcsRootId", "value": "MyVCSRootId" } ] } } ] }

Manage Triggers

To get all build triggers, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/triggers

Requests respond with a Triggers or Trigger entity, which is also expected in the modifying requests.

Example of payload (a VCS trigger):

<triggers> <trigger type="vcsTrigger"> <properties> <property name="branchFilter" value="+:*"/> <property name="enableQueueOptimization" value="true"/> <property name="quietPeriodMode" value="DO_NOT_USE"/> </properties> </trigger> </triggers>
{ "trigger": [ { "type": "vcsTrigger", "properties": { "property": [ { "name": "branchFilter", "value": "+:*" }, { "name": "enableQueueOptimization", "value": "true" }, { "name": "quietPeriodMode", "value": "DO_NOT_USE" } ] } } ] }

Manage Agent Requirements

To get all agent requirements, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/

Requests respond with an AgentRequirements or AgentRequirement entity, which is also expected in the modifying requests.

Example payload:

<agent-requirements> <agent-requirement type="equals"> <properties> <property name="property-name" value="system.agent.name"/> <property name="property-value" value="MySpecificAgent"/> </properties> </agent-requirement> </agent-requirements>
{ "agent-requirement": [ { "type": "equals", "properties": { "property": [ { "name": "property-name", "value": "system.agent.name" }, { "name": "property-value", "value": "MySpecificAgent" } ] } } ] }

Manage Dependencies

To get all dependencies, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies
GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies

Requests respond with one of the below:

which is also expected in the modifying requests.

Example payload of a snapshot dependency:

<snapshot-dependencies> <snapshot-dependency type="snapshot_dependency"> <properties> <property name="run-build-if-dependency-failed" value="RUN_ADD_PROBLEM"/> <property name="run-build-if-dependency-failed-to-start" value="MAKE_FAILED_TO_START"/> <property name="run-build-on-the-same-agent" value="false"/> <property name="sync-revisions" value="true"/> <property name="take-started-build-with-same-revisions" value="true"/> <property name="take-successful-builds-only" value="true"/> </properties> <source-buildType id="MyDependencyID"/> </snapshot-dependency> </snapshot-dependencies>
{ "snapshot-dependency": [ { "type": "snapshot_dependency", "properties": { "property": [ { "name": "run-build-if-dependency-failed", "value": "RUN_ADD_PROBLEM" }, { "name": "run-build-if-dependency-failed-to-start", "value": "MAKE_FAILED_TO_START" }, { "name": "run-build-on-the-same-agent", "value": "false" }, { "name": "sync-revisions", "value": "true" }, { "name": "take-started-build-with-same-revisions", "value": "true" }, { "name": "take-successful-builds-only", "value": "true" } ] }, "source-buildType": { "id": "MyDependencyID" } } ] }

Example payload of an artifact dependency:

<artifact-dependencies> <artifact-dependency type="artifact_dependency"> <properties> <property name="cleanDestinationDirectory" value="false"/> <property name="pathRules" value="myArtifact.txt"/> <property name="revisionBranch" value="+:*"/> <property name="revisionName" value="lastSuccessful"/> <property name="revisionValue" value="latest.lastSuccessful"/> </properties> <source-buildType id="MyDependencyID"/> </artifact-dependency> </artifact-dependencies>
{ "artifact-dependency": [ { "type": "artifact_dependency", "properties": { "property": [ { "name": "cleanDestinationDirectory", "value": "false" }, { "name": "pathRules", "value": "myArtifact.txt" }, { "name": "revisionBranch", "value": "+:*" }, { "name": "revisionName", "value": "lastSuccessful" }, { "name": "revisionValue", "value": "latest.lastSuccessful" } ] }, "source-buildType": { "id": "MyDependencyID" } } ] }

Manage VCS Roots

To get all attached VCS roots, use:

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

To attach a new VCS root, use:

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

Requests respond with a VcsRootEntries or VcsRootEntry entity, which is also expected in the modifying requests.

Example payload (a reference to a VCS root defined in one of the parent projects):

<vcs-root-entries> <vcs-root-entry id="MyTestRepo"> <vcs-root id="MyTestRepo"/> </vcs-root-entry> </vcs-root-entries>
{ "vcs-root-entry": [ { "id": "MyTestRepo", "vcs-root": { "id": "MyTestRepo" } } ] }

To detach a VCS root, use:

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

Manage Templates

To retrieve all associated templates, use:

GET http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates

To attach a new template, use:

POST http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates

Requests respond with a BuildTypes or BuildType entity (as a template is a special case of a build configuration), which is also expected in the modifying requests.

Example payload (reference to a template with the MyTemplate ID):

<templates> <buildType id="MyTemplate"/> </templates>
{ "buildType": [ { "id": "MyTemplate" } ] }

To detach a template, use:

DELETE http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates/{templateLocator}
Last modified: 14 October 2021