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