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:
/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
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>
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>
To detach a template, use:
/app/rest/buildTypes/<buildTypeLocator>/templates/{templateLocator}
Last modified: 01 June 2022