The Jira Software Cloud REST API

Deployments

APIs related to integrating deployments data with Jira Software. These APIs are available to Atlassian Connect apps. To use these APIs you must have the Deployment module see https://developer.atlassian.com/cloud/jira/software/modules/deployment/ 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/.

Submit deployment data

POST /deployments/0.1/bulk

Update / insert deployment data.

Deployments are identified by the combination of pipelineId, environmentId and deploymentSequenceNumber, and existing deployment data for the same deployment will be replaced if it exists and the updateSequenceNumber of existing data is less than the incoming data.

Submissions are processed 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 getDeploymentByKey operation can be used to confirm that data has been stored successfully (if needed).

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

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

Connect apps cannot access this REST resource.

OAuth scopes required:

NONE

Request

Header parameters

Authorization Required

string

All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.

If the Connect JWT token corresponds to an app that does not define jiraDeploymentInfoProvider module it will be rejected with a 403.

See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations.

Pattern: JWT \S+

Body parameters

The payload used to submit (update / insert) deployment data.

properties

Properties

Properties assigned to deployment data that can then be used for delete / query operations.

Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system.

Properties are supplied as key/value pairs, and a maximum of 5 properties can be supplied, keys cannot contain ':' or start with '_'.

Max properties: 5

deployments Required

Array<DeploymentData>

A list of deployments to submit to Jira. Each deployment may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.

Min items: 1

providerMetadata

ProviderMetadata

Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. It is not considered private information. Hence, it may not contain personally identifiable information.

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.com/deployments/0.1/bulk' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "properties": {
    "accountId": "account-234",
    "projectId": "project-123"
  },
  "deployments": [
    {
      "deploymentSequenceNumber": 100,
      "updateSequenceNumber": 1,
      "issueKeys": [
        "ABC-123"
      ],
      "associations": [
        {
          "associationType": "issueIdOrKeys",
          "values": [
            "ABC-123",
            "ABC-456"
          ]
        }
      ],
      "displayName": "Deployment number 16 of Data Depot",
      "url": "http://mydeployer.com/project1/1111-222-333/prod-east",
      "description": "The bits are being transferred",
      "lastUpdated": "2018-01-20T23:27:25.000Z",
      "label": "Release 2018-01-20_08-47-bc2421a",
      "state": "in_progress",
      "pipeline": {
        "id": "e9c906a7-451f-4fa6-ae1a-c389e2e2d87c",
        "displayName": "Data Depot Deployment",
        "url": "http://mydeployer.com/project1"
      },
      "environment": {
        "id": "8ec94d72-a4fc-4ac0-b31d-c5a595f373ba",
        "displayName": "US East",
        "type": "production"
      },
      "commands": [
        {
          "command": "initiate_deployment_gating"
        }
      ],
      "schemaVersion": "1.0"
    }
  ],
  "providerMetadata": {
    "product": "Bamboo 6.10.2"
  }
}'

Responses

202

400

401

403

413

429

503

default

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

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

Content type	Value
application/json	SubmitDeploymentsResponse

Delete deployments by Property

DELETE /deployments/0.1/bulkByProperties

Bulk delete all deployments that match the given request.

One or more query params must be supplied to specify the 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 (i.e. treated as AND). See the documentation for the submitDeployments operation for more details.

Example operation: DELETE /bulkByProperties?accountId=account-123&createdBy=user-456

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

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

Connect apps cannot access this REST resource.

OAuth scopes required:

NONE

Request

Query parameters

_updateSequenceNumber Deprecated

integer

This parameter usage is no longer supported.

An optional updateSequenceNumber to use to control deletion.

Only stored data with an updateSequenceNumber less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together.

If not provided, all stored data that matches the request will be deleted.

Format: int64

Header parameters

Authorization Required

string

All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.

If the Connect JWT token corresponds to an app that does not define jiraDeploymentInfoProvider module it will be rejected with a 403.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.com/deployments/0.1/bulkByProperties'

Responses

202

400

401

403

429

503

default

Delete accepted. Data will eventually be removed from Jira.

A schema has not been defined for this response code.

Get a deployment by key

GET /deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}

Retrieve the currently stored deployment data for the given pipelineId, environmentId and deploymentSequenceNumber combination.

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

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

Connect apps cannot access this REST resource.

OAuth scopes required:

NONE

Request

Path parameters

pipelineId Required

string

The ID of the deployment's pipeline.

Max length: 255

environmentId Required

string

The ID of the deployment's environment.

Max length: 255

deploymentSequenceNumber Required

integer

The deployment's deploymentSequenceNumber.

Format: int64

Header parameters

Authorization Required

string

All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.

If the Connect JWT token corresponds to an app that does not define jiraDeploymentInfoProvider module it will be rejected with a 403.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.com/deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}' \
  --header 'Accept: application/json'

Responses

200

401

403

404

429

503

default

The deployment data currently stored for the given ID.

Content type	Value
application/json	DeploymentData

Delete a deployment by key

DELETE /deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}

Delete the currently stored deployment data for the given pipelineId, environmentId and deploymentSequenceNumber combination.

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

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

Connect apps cannot access this REST resource.

OAuth scopes required:

NONE

Request

Path parameters

pipelineId Required

string

The ID of the deployment's pipeline.

Max length: 255

environmentId Required

string

The ID of the deployment's environment.

Max length: 255

deploymentSequenceNumber Required

integer

The deployment's deploymentSequenceNumber.

Format: int64

Query parameters

_updateSequenceNumber Deprecated

integer

This parameter usage is no longer supported.

An optional _updateSequenceNumber to use to control deletion.

Format: int64

Header parameters

Authorization Required

string

All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira.

If the Connect JWT token corresponds to an app that does not define jiraDeploymentInfoProvider module it will be rejected with a 403.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.com/deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}'

Responses

202

401

403

429

503

default

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

A schema has not been defined for this response code.

Get deployment gating status by key

GET /deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}/gating-status

Retrieve the Deployment gating status for the given pipelineId + environmentId + deploymentSequenceNumber combination. Only apps that define the jiraDeploymentInfoProvider module can access this resource. This resource requires the 'READ' scope.

Connect apps cannot access this REST resource.

OAuth scopes required:

NONE

Request

Path parameters

pipelineId Required

string

The ID of the Deployment's pipeline.

Max length: 255

environmentId Required

string

The ID of the Deployment's environment.

Max length: 255

deploymentSequenceNumber Required

integer

The Deployment's deploymentSequenceNumber.

Format: int64

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.com/deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}/gating-status' \
  --header 'Accept: application/json'

Responses

200

401

403

404

429

503

default

The current gating status for the given Deployment

Content type	Value
application/json	SubmitDeploymentsResponse