Sign in

v1

latestOpenAPI 3.0.1Apache 2.02026-07-1310566642.9 KB
Builds

Get a build by key

Retrieve the currently stored build data for the given pipelineId and buildNumber combination.

The result will be what is currently stored, ignoring any pending updates or deletes.

get/rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}

Path parameters

pipelineIdstring required

The pipelineId of the build.

buildNumberinteger required

The buildNumber of the build.

Response

The build data currently stored for the given key.

schemaVersion'1.0'

The schema version used for this data.

Placeholder to support potential schema changes in the future.

pipelineIdstring required

An ID that relates a sequence of builds. Depending on your use case this might be a project ID, pipeline ID, plan key etc. - whatever logical unit you use to group a sequence of builds.

The combination of pipelineId and buildNumber must uniquely identify a build you have provided.

buildNumberinteger required

Identifies a build within the sequence of builds identified by the build pipelineId.

Used to identify the 'most recent' build in that sequence of builds.

The combination of pipelineId and buildNumber must uniquely identify a build you have provided.

updateSequenceNumberinteger required

A number used to apply an order to the updates to the build, as identified by pipelineId and buildNumber, in the case of out-of-order receipt of update requests.

It must be a monotonically increasing number. For example, epoch time could be one way to generate the updateSequenceNumber.

Updates for a build that is received with an updateSqeuenceNumber less than or equal to what is currently stored will be ignored.

displayNamestring required

The human-readable name for the build.

Will be shown in the UI.

descriptionstring

An optional description to attach to this build.

This may be anything that makes sense in your system.

labelstring

A human-readable string that to provide information about the build.

urlstring URL required

The URL to this build in your system.

state'pending' | 'in_progress' | 'successful' | 'failed' | 'cancelled' | 'unknown' required

The state of a build.

  • pending - The build is queued, or some manual action is required.
  • in_progress - The build is currently running.
  • successful - The build completed successfully.
  • failed - The build failed.
  • cancelled - The build has been cancelled or stopped.
  • unknown - The build is in an unknown state.
lastUpdatedstring date-time required

The last-updated timestamp to present to the user as a summary of the state of the build.

issueKeysstring[]

The Jira issue keys to associate the build information with.

You are free to associate issue keys in any way you like. However, we recommend that you use the name of the branch the build was executed on, and extract issue keys from that name using a simple regex. This has the advantage that it provides an intuitive association of builds to issue keys.

Example response

{
  "schemaVersion": "1.0",
  "pipelineId": "my-build-plan",
  "buildNumber": 16,
  "updateSequenceNumber": 1523494301448,
  "displayName": "My Project build #16",
  "description": "My Project build #16: Failed",
  "state": "failed",
  "lastUpdated": "2018-01-20T23:27:25.000Z",
  "issueKeys": [
    "ISSUE-123"
  ],
  "associations": [
    {
      "associationType": "issueIdOrKeys",
      "values": [
        "ABC-123",
        "ABC-456"
      ]
    }
  ],
  "testInfo": {
    "totalNumber": 150,
    "numberPassed": 145,
    "numberFailed": 5
  },
  "references": [
    {
      "commit": {
        "id": "08cd9c26b2b8d7cf6e6af6b49da8895d065c259f",
        "repositoryUri": "https://bitbucket.org/atlassian/biij-vendor-api"
      },
      "ref": {
        "name": "feature/ISSUE-123-some-work",
        "uri": "https://bitbucket.org/atlassian/biij-vendor-api/refs/feature/ISSUE-123-some-work"
      }
    }
  ]
}