Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

3.5.3. build

resource type: build
Attributes:

  • buildid (integer) – the unique ID of this build

  • number (integer) – the number of this build (sequential for a given builder)

  • builderid (integer) – id of the builder for this build

  • buildrequestid (integer) – build request for which this build was performed, or None if no such request exists

  • workerid (integer) – the worker this build ran on

  • masterid (integer) – the master this build ran on

  • started_at (date) – time at which this build started

  • complete (boolean) – true if this build is complete. Note that this is a calculated field (from complete_at != None). Ordering by this field is not optimized by the database layer.

  • complete_at? (date) – time at which this build was complete, or None if it’s still running

  • locks_duration_s (integer) – time spent acquiring locks so far, not including any running steps

  • properties? (sourcedproperties) – a dictionary of properties attached to build.

  • results? (integer) – the results of the build (see Build Result Codes), or None if not complete

  • state_string (string) – a string giving detail on the state of the build.

example

{
    "builderid": 10,
    "buildid": 100,
    "buildrequestid": 13,
    "workerid": 20,
    "complete": false,
    "complete_at": null,
    "masterid": 824,
    "number": 1,
    "results": null,
    "started_at": 1451001600,
    "state_string": "created",
    "properties": {}
}

This resource type describes completed and in-progress builds. Much of the contextual data for a build is associated with the build request, and through it the buildset.

Note

The properties field of a build is only filled out if the properties filterspec is set. That means the property filter allows one to request properties through the Builds DATA API like so:

  • api/v2/builds?property=* (returns all properties)

  • api/v2/builds?property=propKey1&property=propKey2 (returns the properties that match the given keys)

  • api/v2/builds?property=propKey1&property=propKey2&limit=30 (filters combination)

Important

When combined with the field filter, for someone to get the build properties, they should ensure the properties field is set:

  • api/v2/builds?field=buildid&field=properties&property=workername&property=user

3.5.3.1. Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.builds.Build
newBuild(builderid, buildrequestid, workerid)
Parameters:

  • builderid (integer) – id of the builder performing this build

  • buildrequestid (integer) – id of the build request being built

  • workerid (integer) – id of the worker on which this build is performed

Returns:

(buildid, number) via Deferred

Create a new build resource and return its ID. The state strings for the new build will be set to ‘starting’.

setBuildStateString(buildid, state_string)
Parameters:

  • buildid (integer) – the build to modify

  • state_string (unicode) – new state string for this build

Replace the existing state strings for a build with a new list.

finishBuild(buildid, results)
Parameters:

  • buildid (integer) – the build to modify

  • results (integer) – the build’s results

Mark the build as finished at the current time, with the given results.

3.5.3.2. Endpoints

path: /builders/{builderid_or_buildername}/builds
Path Keys:

builderid_or_buildername (number|string) – the ID or name of the builder

This path selects all builds for a builder (can return lots of data!)

GET
returns

collection of build

path: /builders/{builderid_or_buildername}/builds/{build_number}
Path Keys:

  • builderid_or_buildername (number|string) – the ID or name of the builder

  • build_number (number) – the number of the build within the builder

This path selects a specific build by builderid and buildnumber

GET
returns

collection of build

POST with method: /builders/{builderid_or_buildername}/builds/{build_number} (method=stop)
Body keys:

  • method (string) – must be stop

  • reason (string) – The reason why the build was stopped

  • results (integer) – optionally results value override (default CANCELLED)

POST with method: /builders/{builderid_or_buildername}/builds/{build_number} (method=rebuild)
Body keys:

method (string) – must be rebuild

path: /buildrequests/{buildrequestid}/builds
Path Keys:

buildrequestid (number) – the id of the buildrequest

GET
returns

collection of build

path: /builds
GET
returns

collection of build

path: /builds/{buildid}
Path Keys:

buildid (number) – the id of the build

This path selects a build by id

GET
returns

collection of build

POST with method: /builds/{buildid} (method=stop)
Body keys:

  • method (string) – must be stop

  • reason (string) – The reason why the build was stopped

POST with method: /builds/{buildid} (method=rebuild)
Body keys:

method (string) – must be rebuild