TeamCity REST API Reference 2023.11 Help

Manage Build Configuration Details

This article shows how to get build configurations via TeamCity REST API.

List Build Configurations

To get all build configurations on the server, use:

/app/rest/buildTypes

Server will respond with a BuildTypes entity which contains the BuildType entities found by request.

Get Specific Build Configurations

To locate specific build configurations, use:

/app/rest/buildTypes/{buildConfigurationLocator}

where buildConfigurationLocator is a BuildTypeLocator-typed string used to locate the build configuration.

For example, to find a build configuration with the MyBuildConfigurationID ID use:

/app/rest/buildTypes/id:MyBuildConfigurationID

To locate all build configurations explicitly owned by a project with the MyProject ID, use:

/app/rest/buildTypes?locator=project:MyProject

The request above does not return build configurations owned by subprojects of the MyProject project. To obtain all configurations, including those owned by child subprojects, use the following request instead:

/app/rest/buildTypes?locator=affectedProject:<ProjectLocator>

Manage Build Parameters

To get all build parameters, use:

/app/rest/buildTypes/<buildTypeLocator>/parameters

To fetch a specific parameter by name, use:

/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:

/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>/value

For more details about managing typed build parameters, see Manage Typed Parameters.

Manage Build Steps

To get all build steps, use:

/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>
{ "name": "myCommandLineStep", "type": "simpleRunner", "properties": { "property": [ { "name": "script.content", "value": "echo 'Hello World!'" } ] } }

Manage Build Features

To get all build features, use:

/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>
{ "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 Build Triggers

To get all build triggers, use:

/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>
{ "type": "vcsTrigger", "properties": { "property": [ { "name": "branchFilter", "value": "+:*" }, { "name": "enableQueueOptimization", "value": "true" }, { "name": "quietPeriodMode", "value": "DO_NOT_USE" } ] } }

To invoke a Perforce Shelve Trigger, use this endpoint:

POST /app/perforce/runBuildForShelve?buildTypeId=<BuildConfigurationID>&vcsRootId=<VCSRootID>&shelvedChangelist=<ChangelistID>

Manage Agent Requirements

To get all agent requirements, use:

/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>
{ "type": "equals", "properties": { "property": [ { "name": "property-name", "value": "system.agent.name" }, { "name": "property-value", "value": "MySpecificAgent" } ] } }

Manage Dependencies

To get all dependencies, use:

/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies
/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>
{ "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>
{ "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:

/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>

To attach a new VCS root, use:

/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>
{ "id": "MyTestRepo", "vcs-root": { "id": "MyTestRepo" } }

To detach a VCS root, use:

/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>

For more details about managing VCS roots, see Manage VCS Roots.

Manage Templates

To retrieve all associated templates, use:

/app/rest/buildTypes/<buildTypeLocator>/templates

To attach a new template, use:

/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>
{ "id": "MyTemplate" }

To detach a template, use:

/app/rest/buildTypes/<buildTypeLocator>/templates/{templateLocator}
Last modified: 14 December 2023