Tracking build progress with TeamCity REST API

9
votes

I use the TeamCity (7.0) REST API to allow developers to trigger custom builds. I add the build to the queue like this:

http://teamcity/httpAuth/action.html?add2Queue=[buildTypeId]&name=[propName]&value=[propValue]

My question is how I best can track the progress of the build just triggered. The REST call does not return any info about build ID assigned to the build, so even if I poll the list of builds (running/finished) I will not know if one of them is the one I triggered. There could potentially be several builds for the same buildTypeId in the queue, so I need a way to separate out the one I am after.

I read somewhere a suggestion that you could add a build property with a unique value to each build you put in the queue, and then later poll the build list and look for one with that exact property value. I have however not found a way of listing the properties for the builds, so I am still stuck. This REST call does not provide information about properties:

http://teamcity/httpAuth/app/rest/builds/?locator=buildType:[buildTypeId]

Any suggestions on how to solve this? I would ideally like to know if the build is in the queue, if it is running, and when it's done I would like to get the status. The most important is however to know if it is done and what the status has.

3
restcontinuous-integrationteamcity

3 Answers

11
votes

After some further investigation I came up with a solution for this which seems to work fine:

I found out that even though you did not get any information about the custom build properties using the "/builds/?locator=buildType:x" call, you could extract the build ID for each one of the builds in that list and then do another REST call to get more details about one specific build. The rest call looks like this:

http://teamcity/httpAuth/app/rest/builds/id:{0}

The response from this call will give you a "build object" which contains a list of build properties, among other things.

My solution for tracking the build progress was then like this:

When a build is added to the TeamCity queue, I first add a property to the URL called "BuildIdentifier". The value is just a GUID. I pass this identifier back to the client application, and then the client starts polling the server, asking for the status of the build with this specific identifier. The server then goes through some steps to identify the current stage of the build:

1: Check if the build is running. I get the list of running builds with the call "/builds?locator=running:true", iterate through the builds and use the build ID to query the REST API for details. I then go through the details for each running build looking for a build with a matching "BuildIdentifier" property to the one I received from the client. If there is a match in one of the running builds I send a response with a message that the build is running at x percent (PercentageComplete property of the build object) to the client who is tracking the progress. If a match is not found I move on to step 2.

2: Check if it is finished: First get the latest build list using the "/builds/?locator=buildType:x" call. Then do the same thing as in step 1, and extract the X latest builds from the list (I chose 5). In order to limit the number of REST calls I set an assumption that the build would be in the latest 5 builds if it was finished. I then look for a match on the BuildIdentifier, and if I get one I return the status of the build (FAILED, SUCCESS, etc.).

3: If there was no match for the BuildIdentifier in step 1 or 2 I can assume that the build is in the queue, so I return that as the current status.

On the client side I poll the server for the status every x seconds as long as the status is saying that the build is either in the queue, or running.

Hope this solution could be helpful if there are someone else with the same problem out there! I would think that tracking the progress of a triggered build is a pretty common task if you use the TeamCity REST API.

4
votes

The Queued Builds rest api is the best way to accomplish this but has only been available since version 8.1.

  • To start the build send a POST request to ~/httpAuth/app/rest/buildQueue like this

    {
    buildType: { id: "bt667" },
    branchName: "master",
    properties: {
        property: [
            { "name": "Property", "value": "test" }
        ]
    }
}

  • The response contains a href which can be used to check the status of the build.

    {
    ...
    "href": "/httpAuth/app/rest/buildQueue/taskId:49337",
    ...
}

  • To check the status of the build queued send a GET request to the href specified in the response from step 1.

This is a huge improvement over the previous API.

1
votes

Since TeamCity 8.1, REST API got a dedicated way to trigger a build and tracking the queued build results is much easier as the build queue request returns the link to the queued build which can later be used to track the build's current status. See details in the TeamCity documentation.