Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 10.x and 2017.x Documentation

Icon

You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: related to TW-35719, TW-18098

...

The list of supported build locator dimensions:

project:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project). 
affectedProject:<project locator> -  limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)
buildType:(<buildTypeLocator>) - only the builds of the specified build configuration

tags:<tags> - ","(comma) - a delimited list of build tags (only builds containing all the specified tags are returned)
status:<SUCCESS/FAILURE/ERROR> - list builds with the specified status only
user:(<userLocator>) - limit builds to only those triggered by the user specified
personal:<true/false/any> - limit builds by the personal flag. By default, perfsonal builds are not included.

canceled:<true/false/any> - limit builds by the canceled flag. By default, canceled builds are not included.
failedToStart:<true/false/any> -  limit builds by the failed to start flag. By default, canceled builds are not included.
running:<true/false/any> - limit builds by the running flag. By default, running builds are not included.
state:running,hanging:true - fetch hanging builds (since TeamCity 10.0
pinned:<true/false/any> - limit builds by the pinned flag.

Anchor
branchLocator
branchLocator
branch:<branch locator> - limit the builds by branch. <branch locator> can be the branch name displayed in the UI, or "(name:<name>,default:<true/false/any>,unspecified:<true/false/any>,branched:<true/false/any>)".  By default only builds from the default branch are returned. To retrieve all builds, add the following locator: branch:default:any. The whole path will look like this: /httpAuth/app/rest/builds/?locator=buildType:One_Git,branch:default:any

revision:<REVISION> - find builds by revision. The whole path is: /httpAuth/app/rest/app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID)
agentName:<name> - agent name to return only builds ran on the agent with name specified

sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified
sinceDate:<date> - limit the list of builds only to those started after the date specified. The date should be in the same format as dates returned by REST API (e.g. "20130305T170030+0400").
project:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project). Before TeamCity 9.1 this traversed projects recursively: with meaning "belonging to any build type directly or indirectly under the project".
affectedProject:<project locator> -  limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)
queuedDate/startDate/finishDate:(date:<time-date>,build:<build locator>,condition:<before/after>) - filter builds based on the time specified by the build locator, e.g. (finishDate:(date:20151123T203446+0100,condition:after) - (finished after November 23, 2015, 20:34:46)

 

count:<number> - serve only the specified number of builds
start:<number> - list the builds from the list starting from the position specified (zero-based)
lookupLimit:<number> - limit processing to the latest N builds only (the default is 5000). If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned. 

...

When the build is started, the request to the queued build (/app/rest/buildQueue/XXX) will return running/finished build data. This way, you can monitor the build completeness by querying build details using the "href" attribute of the build details returned on build triggering, until the build has the state="finished" attribute. (There is a related outstanding issue.)

Build node example

Basic build for a build configuration:

...

Code Block
xml
xml
<build personal="true" branchName="logicBuildBranch">
    <buildType id="buildConfID"/>
    <agent id="3"/>
    <comment><text>build triggering comment</text></comment>
    <properties>
        <property name="env.myEnv" value="bbb"/>
    </properties>
</build>

Queued build assignment to an agent pool:

Code Block
<build>...
  <agent>
    <pool id="N"/>
  </agent>
...
</build>

 

Build on a specified change, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Note that the change is set via the change's internal modification id; see more below):

...