The Develocity Export API allows you to pull out build data from your Develocity instance - making it easy to push your build data into other systems and use your build data for internal dashboards and graphs.
The Export API is available at https://«develocity-host»/build-export/
and provides a number of Server-Sent Event (SSE) based resources over HTTPS.
The Develocity Export API described in this document will eventually be replaced by the Develocity API. At this time, the Develocity API does not allow consuming the raw events of a build as the Export API does. If your existing usage of the Export API can be replaced with the easier-to-use Develocity API, please consider migrating. For assistance, please contact Develocity support. |
Before you get started
Server-Sent Events (SSE)
Server-Sent Events (SSE) is an API for continuously receiving push based notifications from a server over a HTTP connection. With its event based approach and a defined mechanism for reconnect-resume, SSE is ideal for real-time streaming of events from server to client but also an efficient way of streaming large volumes of data.
SSE clients are available for most programming languages. The following are some examples:
Most modern browsers provide a JavaScript SSE client. However, this implementation doesn’t provide a way to send arbitrary request headers and is lacking in other features. An alternative implementation, such as EventSourcePolyfill, is recommended.
Compression
All of the Export API resources detailed below support gzip compression which will considerably reduce the amount of data being sent over the wire. Compression can be enabled by simply adding the header Accept-Encoding: gzip
to your request.
Reconnect-resume
All Export API SSE messages will have their id
field set, allowing you to take advantage of reconnect-resume functionality should the connection drop.
Connecting to a resource with the Last-Event-ID
http header set will resume the stream from that point. In the case of a stream that has no further messages to emit and is complete, a response status of 204 No Content
will be returned and further reconnection attempts should not be attempted.
Some SSE clients include this functionality out-of-the-box.
Streaming
Some Export API resources allow opting-in to streaming by including a stream
URL query parameter with any value. When enabled, the connection is long lived and new data is pushed as it becomes available. When not enabled, all data that is available at the time of the request is sent and then the connection is closed. The reference information for the API resources below indicates which support streaming.
In order to keep a streaming connection alive during periods of inactivity, a "heart beat" message is periodically sent as an SSE comment and can be safely ignored. Most SSE clients are configured to ignore such comments by default.
Streaming requests are compatible with reconnect-resume, making it convenient to have long lived processes that make streaming requests and reconnect on any connection disruption and resume processing data.
If you are accessing Develocity through a reverse proxy server you may need to explicitly disable or limit response buffering streaming to avoid new data being delayed. |
Access control
By default, Develocity does not allow anonymous access to the Export API. Requests must be authenticated, and the user granted the “Export API” permission.
To check whether your user account has this permission:
-
Sign in to Develocity
-
Access “My settings” from the user menu in the top right hand corner of the page
-
Access “Permissions” from the left hand menu
If you do not have permission to access the Export API according to this page, contact your Develocity system administrator.
The Export API supports HTTP basic authentication, and bearer token authentication (since Develocity 2021.1). Bearer token authentication is recommended for clients that are capable of supporting it. If you authenticate with an external service when signing in to Develocity (e.g. an organizational SAML identity provider), only bearer token authentication is supported.
When authenticating with the Export API over a plain HTTP connection (opposed to HTTPS), your authentication credentials are potentially interceptable by someone else. Use of HTTPS is strongly recommended. |
Bearer token authentication
Using bearer token authentication requires a valid Develocity “access key”.
To create an access key for your account:
-
Sign in to Develocity:
-
Access “My settings” from the user menu in the top right hand corner of the page
-
Access “Access keys” from the left hand menu
-
Click “Generate”
To authenticate with an access key, the following header must be sent with each request:
Authorization: Bearer access-key
For example, given an access key of 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja
, the following header would be required:
Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja
The standard EventSource implementation available in browser runtimes doesn’t provide a way to send arbitrary request headers, and therefore does not support bearer token authentication. An alternative, such as EventSourcePolyfill, can be used instead. |
Basic authentication
For user accounts that authenticate directly with Develocity with a username and password, standard HTTP Basic Authentication can be used.
Authenticating with a bearer token instead of using basic authentication is recommended.
Cross-origin requests (CORS)
Export API requests made from a browser runtime may be subject to cross origin resource sharing access control, depending on the runtime. All requests made using a bearer token respond with the HTTP headers required to allow cross-origin requests. If you are experiencing errors when making requests that mention “CORS” or “cross origin access control”, authenticating with a bearer token will allow the requests to be made.
Version 2
https://«develocity-host»/build-export/v2
Available since Develocity 2021.2.
Version 2 offers effectively the same functionality as version 1, but allows observing builds from build tools other than Gradle.
Build listing
All build listing endpoints emit build events in order of when the build was received and processed by Develocity.
GET /builds/since/:date[?stream]
Emits events for each build that has been received and processed by Develocity, since the given date.
Parameters
:date |
Required |
A unix-epoch-time value. The value refers to the instant that Develocity completed receiving and processing the build. It is not the time that the build occurred. A value of A special value of |
stream |
Optional |
Enables streaming. The connection will remain open indefinitely with new build events emitted as new builds are received and processsed. |
Example requests
https://«develocity-host»/build-export/v2/builds/since/1466640000000
https://«develocity-host»/build-export/v2/builds/since/0
https://«develocity-host»/build-export/v2/builds/since/now?stream
GET /builds/sinceBuild/:buildId[?stream]
Stream summary build data for all builds received and process since after the given build ID.
Parameters
:buildId |
Required |
The 13 character id of the build. |
stream |
Optional |
Enables streaming. The connection will remain open indefinitely with new build events emitted as new builds are received and processsed. |
Example requests
gkoprlkauv35q
was received until now
https://«develocity-host»/build-export/v2/builds/sinceBuild/gkoprlkauv35q
gkoprlkauv35q
was received and all future builds
https://«develocity-host»/build-export/v2/builds/sinceBuild/gkoprlkauv35q?stream
Individual builds
GET /build/:buildId/events[?eventTypes=type1,type2,…]
Stream build information for an individual build.
Whilst running a build, build data is mapped to a series of events. The combination of build agent and build tool version used to run the build will determine what events are produced and at what version. You can see the full list of events in the Javadoc of the Develocity Event Model. These events are serialized as JSON and streamed as the data
attribute of BuildEvent messages.
It is recommended to specify the event types you require whenever possible to reduce the amount of data streamed. |
Parameters
:buildId |
Required |
The 13 character id of the build. |
eventTypes |
Optional |
A comma separated list of BuildEvent event types. |
Response
A stream consisting of the following messages in strict order:
-
a single message of type Build
-
n messages of type BuildEvent
A 503 Service Unavailable
response indicates that the build data is still being stored and is not yet ready for reading. Clients should retry the request.
Example request
gkoprlkauv35q
https://«develocity-host»/build-export/v2/build/gkoprlkauv35q/events
BuildStarted
and BuildFinished
events for the build with the id gkoprlkauv35q
https://«develocity-host»/build-export/v2/build/gkoprlkauv35q/events?eventTypes=BuildStarted,BuildFinished
Event types
Build
id: gkoprlkauv35q event: Build data: { "buildId": "gkoprlkauv35q", "timestamp": 1466640000000, "toolType": "gradle", "toolVersion": "3.3", "agentVersion": "1.6" }
Attribute | Description |
---|---|
buildId |
The 13 character ID of the build. |
timestamp |
The time the build was received and processed by Develocity as a unix-epoch-time value. |
toolType |
The build tool type used to run the build (one of "gradle", "maven", "bazel"). |
toolVersion |
The build tool version used to run the build. |
agentVersion |
The version of the plugin or extension applied to build in order to connect with Develocity. |
BuildEvent
Information about a particular event that occurred during a build.
Message data is event type and version specific. You can discover what data to expect by using the Javadoc of the Develocity Event Model. Note that some event types have an empty data payload.
id: 1 event: BuildEvent data: { "timestamp":1466640000000, "type": { "majorVersion": 1, "minorVersion": 0, "eventType": "BuildStarted" }, "data": {} }
id: 2 event: BuildEvent data: { "timestamp": 1466640000001, "type": { "majorVersion": 1, "minorVersion": 0, "eventType": "BuildRequestedTasks" }, "data": { "excluded": [], "requested": ["build"] } }
Attribute | Description |
---|---|
timestamp |
The time the event occurred as a unix-epoch-time value. |
type |
The specific type of the event, including event type, major and minor version. To be used in data parsing. |
data |
A JSON object containing properties specific to the event type and version. See the Javadoc of the Develocity Event Model for details about specific event types. |
Migrating from version 1
In order to migrate from version 1 to version 2, three things are needed:
-
Replace
/v1/
with/v2/
in request URLs -
For the
/builds
endpoint, use the fieldtoolVersion
in place ofgradleVersion
andagentVersion
in place ofpluginVersion
-
Respect the new
toolType
field which indicates the build tool type if interested in a particular build tool type (values are one ofgradle
,maven
orbazel
)
No other changes are required.
Version 1
https://«develocity-host»/build-export/v1
Available since Develocity 2017.1.
Version 1 is limited to builds from the Gradle build tool.
Build listing
All build listing endpoints emit build events in order of when the build was received and processed by Develocity.
GET /builds/since/:date[?stream]
Emits events for each Gradle build that has been received and processed by Develocity, since the given date.
Parameters
:date |
Required |
A unix-epoch-time value. The value refers to the instant that Develocity completed receiving and processing the build. It is not the time that the build occurred. A value of A special value of |
stream |
Optional |
Enables streaming. The connection will remain open indefinitely with new build events emitted as new builds are received and processsed. |
Example requests
https://«develocity-host»/build-export/v1/builds/since/1466640000000
https://«develocity-host»/build-export/v1/builds/since/0
https://«develocity-host»/build-export/v1/builds/since/now?stream
GET /builds/sinceBuild/:buildId[?stream]
Stream summary build data for all Gradle builds received and processed since after the given build ID.
Parameters
:buildId |
Required |
The 13 character id of the build. |
stream |
Optional |
Enables streaming. The connection will remain open indefinitely with new build events emitted as new builds are received and processsed. |
Example requests
gkoprlkauv35q
was received until now
https://«develocity-host»/build-export/v1/builds/sinceBuild/gkoprlkauv35q
gkoprlkauv35q
was received and all future builds
https://«develocity-host»/build-export/v1/builds/sinceBuild/gkoprlkauv35q?stream
Individual builds
GET /build/:buildId/events[?eventTypes=type1,type2,…]
Stream build information for an individual build.
Whilst running a build, build data is mapped to a series of events. The combination of build agent and build tool version used to run the build will determine what events are produced and at what version. You can see the full list of events in the Javadoc of the Develocity Event Model. These events are serialized as JSON and streamed as the data
attribute of BuildEvent messages.
It is recommended to specify the event types you require whenever possible to reduce the amount of data streamed. |
Parameters
:buildId |
Required |
The 13 character id of the build. If the provided id is not for a Gradle build, no events will be streamed, and the request will result in a |
eventTypes |
Optional |
A comma separated list of BuildEvent event types. |
Response
A stream consisting of the following messages in strict order:
-
a single message of type Build
-
n messages of type BuildEvent
A 503 Service Unavailable
response indicates that the build data is still being stored and is not yet ready for reading. Clients should retry the request.
Example request
gkoprlkauv35q
https://«develocity-host»/build-export/v1/build/gkoprlkauv35q/events
BuildStarted
and BuildFinished
events for the Gradle build with the id gkoprlkauv35q
https://«develocity-host»/build-export/v1/build/gkoprlkauv35q/events?eventTypes=BuildStarted,BuildFinished
Event types
Build
id: gkoprlkauv35q event: Build data: { "buildId": "gkoprlkauv35q", "timestamp": 1466640000000, "gradleVersion": "3.3", "pluginVersion": "1.6" }
Attribute | Description |
---|---|
buildId |
The 13 character ID of the build. |
timestamp |
The time the build was received and processed by Develocity as a unix-epoch-time value. |
gradleVersion |
The version of Gradle used to run the build. |
pluginVersion |
The version of the Develocity plugin used. |
BuildEvent
Information about a particular event that occurred during a build.
Message data is event type and version specific. You can discover what data to expect by using the Javadoc of the Develocity Event Model. Note that some event types have an empty data payload.
id: 1 event: BuildEvent data: { "timestamp":1466640000000, "type": { "majorVersion": 1, "minorVersion": 0, "eventType": "BuildStarted" }, "data": {} }
id: 2 event: BuildEvent data: { "timestamp": 1466640000001, "type": { "majorVersion": 1, "minorVersion": 0, "eventType": "BuildRequestedTasks" }, "data": { "excluded": [], "requested": ["build"] } }
Attribute | Description |
---|---|
timestamp |
The time the event occurred as a unix-epoch-time value. |
type |
The specific type of the event, including event type, major and minor version. To be used in data parsing. |
data |
A JSON object containing properties specific to the event type and version. See the Javadoc of the Develocity Event Model for details about specific event types. |
Examples
Please see the Export API samples GitHub repository for working example usages of the Export API in Java and JavaScript.