Cloud

Jira Software Cloud / Reference / REST API

Builds

APIs related to integrating builds data with Jira Software. These APIs are available to Atlassian Connect apps. To use these APIs you must have the Build module see https://developer.atlassian.com/cloud/jira/software/modules/build/ in your app's descriptor. They are also related to integrating Jira Software Cloud with on-premises tools using OAuth 2.0 credentials, see https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/.

Operations

POST/rest/builds/0.1/bulk DEL/rest/builds/0.1/bulkByProperties GET/rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}DEL/rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}

POST

Submit build data

Update / insert builds data.

Builds are identified by the combination of pipelineId and buildNumber, and existing build data for the same build will be replaced if it exists and the updateSequenceNumber of the existing data is less than the incoming data.

Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The getBuildByKey operation can be used to confirm that data has been stored successfully (if needed).

In the case of multiple builds being submitted in one request, each is validated individually prior to submission. Details of which build failed submission (if any) are available in the response object.

Only Connect apps that define the jiraBuildInfoProvider module, and on-premise integrations, can access this resource. This resource requires the 'WRITE' scope for Connect apps.

Scopes

Connect app scope required: WRITE

Request

Header parameters

Authorization

string

Required

Request bodyapplication/json

Builds data to submit.

properties

Properties

builds

array<BuildData>

Required

providerMetadata

ProviderMetadata

Responses

Submission accepted. Each submitted build that is of a valid format will be eventually available in Jira.

Details of which builds were submitted and which failed submission (due to data format problems etc.) are available in the response object.

application/json

SubmitBuildsResponse

The result of a successful submitBuilds request.

POST/rest/builds/0.1/bulk

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/builds/0.1/bulk' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "properties": {
    "accountId": "account-234",
    "projectId": "project-123"
  },
  "builds": [
    {
      "schemaVersion": "1.0",
      "pipelineId": "my-build-plan",
      "buildNumber": 16,
      "updateSequenceNumber": 1523494301448,
      "displayName": "My Project build #16",
      "description": "My Project build #16: Failed",
      "label": "<string>",
      "url": "<string>",
      "state": "failed",
      "lastUpdated": "2018-01-20T23:27:25.000Z",
      "issueKeys": [
        "ISSUE-123"
      ],
      "testInfo": {
        "totalNumber": 150,
        "numberPassed": 145,
        "numberFailed": 5,
        "numberSkipped": 0
      },
      "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"
          }
        }
      ]
    }
  ],
  "providerMetadata": {
    "product": "Bamboo 6.10.2"
  }
}'

202Response

{
  "acceptedBuilds": [
    {
      "pipelineId": "my-build-plan",
      "buildNumber": 16
    }
  ],
  "rejectedBuilds": [
    {
      "key": {
        "pipelineId": "my-build-plan",
        "buildNumber": 16
      },
      "errors": [
        {
          "message": "<string>",
          "errorTraceId": "<string>"
        }
      ]
    }
  ],
  "unknownIssueKeys": [
    "ISSUE-123"
  ]
}

DEL

Delete builds by Property

Bulk delete all builds data that match the given request.

One or more query params must be supplied to specify Properties to delete by. Optional param _updateSequenceNumber is no longer supported. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND).

See the documentation for the submitBuilds operation for more details.

e.g. DELETE /bulkByProperties?accountId=account-123&repoId=repo-345

Deletion is performed asynchronously. The getBuildByKey operation can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraBuildInfoProvider module, and on-premise integrations, can access this resource. This resource requires the 'DELETE' scope for Connect apps.

Scopes

Connect app scope required: DELETE

Request

Query parameters

_updateSequenceNumber

integer

Header parameters

Authorization

string

Required

Responses

Delete accepted. Data will eventually be removed from Jira.

DEL/rest/builds/0.1/bulkByProperties

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/builds/0.1/bulkByProperties'

GET

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.

Only Connect apps that define the jiraBuildInfoProvider module, and on-premise integrations, can access this resource. This resource requires the 'READ' scope for Connect apps.

Scopes

Connect app scope required: READ

Request

Path parameters

pipelineId

string

Required

buildNumber

integer

Required

Header parameters

Authorization

string

Required

Responses

The build data currently stored for the given key.

application/json

BuildData

Data related to a single build

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

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}' \
  --header 'Accept: application/json'

200Response

{
  "schemaVersion": "1.0",
  "pipelineId": "my-build-plan",
  "buildNumber": 16,
  "updateSequenceNumber": 1523494301448,
  "displayName": "My Project build #16",
  "description": "My Project build #16: Failed",
  "label": "<string>",
  "url": "<string>",
  "state": "failed",
  "lastUpdated": "2018-01-20T23:27:25.000Z",
  "issueKeys": [
    "ISSUE-123"
  ],
  "testInfo": {
    "totalNumber": 150,
    "numberPassed": 145,
    "numberFailed": 5,
    "numberSkipped": 0
  },
  "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"
      }
    }
  ]
}

DEL

Delete a build by key

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

Deletion is performed asynchronously. The getBuildByKey operation can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraBuildInfoProvider module, and on-premise integrations, can access this resource. This resource requires the 'DELETE' scope for Connect apps.

Scopes

Connect app scope required: DELETE

Request

Path parameters

pipelineId

string

Required

buildNumber

integer

Required

Query parameters

_updateSequenceNumber

integer

Header parameters

Authorization

string

Required

Responses

Delete has been accepted. Data will eventually be removed from Jira if it exists.

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

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}'