Deployment API

Opsgenie's deployment API can be used to perform deployment-related actions with the Investigate an incident feature which allows you to track your deployments leading up to, and during incidents. These deployments will contain commit information from the SCM tool that you connect with your Bitbucket account. Currently, Opsgenie supports only Bitbucket cloud as the SCM tool of choice. Therefore please ensure that before using the deployment API you have configured the Opsgenie with Bitbucket Cloud and have mapped your Bitbucket repositories to your Opsgenie services.

📘

Create an API Integration and obtain your apiKey to make requests listed below.

🚧

If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

Get Request Status

Deployment creation and update requests are processed asynchronously to provide higher availability and scalability. Therefore valid requests for those endpoints are responded with HTTP status 202 - Accepted. Get Request Status endpoint is used to track the status and deployment details (if any) of the request whose identifier is given.

In-Line Parameters

Referred Name

Description

requestId

Universally unique identifier of the questioned request. Please note: that ID of the request was provided within the response.

Get Deployment

In-Line Parameters

Referred Name

Description

identifier

Deployment identifier to specify which deployment to update.

Query Parameters

Parameter

Mandatory

Description

type

false

Deployments can be identified with the deployment id returned in the response after deployment is created. However you may also refer to deployments using an external id or Bitbucket Pipelines UUID if Bitbucket Pipelines is being used as the deployment tool. In that case specify the type as api or pipelines respectively.

Sample Request

curl --location --request GET 'http://api.opsgenie.com/v2/deployments/2b70a31e-90f0-3d1e-869c-b2cf27762464' \
-H 'Authorization: GenieKey e3cfa715-725d-49de-95cb-4fd18c878ag8'
curl --location --request GET 'http://api.opsgenie.com/v2/deployments/2b70a31e-90f0-3d1e-869c-b2cf27762464?type=api' \
-H 'Authorization: GenieKey e3cfa715-725d-49de-95cb-4fd18c878ag8'
curl --location --request GET 'http://api.opsgenie.com/v2/deployments/2b70a31e-90f0-3d1e-869c-b2cf27762464?type=pipelines' \
-H 'Authorization: GenieKey e3cfa715-725d-49de-95cb-4fd18c878ag8'

Sample Responses
There are two kinds of responses depending on whether the deployment tool is Atlassian's Bitbucket Pipeline or some third party tool. To use Bitbucket Pipelines along with Opsgenie read how to connect your Bitbucket workspaces to your Opsgenie account.

Deployments performed using Bitbucket Pipelines

{
    "data": {
        "id": "2b70a31e-90f0-3d1e-869c-b2cf27762464",
        "externalId": "{e4daecfb-9d84-5711-b49d-eae11a99d3e9}",
        "state": "successful",
        "environment": {
            "environmentType": "Production",
            "identifier": "{e5cfd278-1d21-47f2-bd64-423ea00fdd60}",
            "displayName": "production"
        },
        "type": "pipelines",
        "startedAt": "2020-03-26T14:05:07.594Z",
        "completedAt": "2020-03-26T14:15:07.594Z",
        "releases": [
            {
                "commit": {
                    "sha": "eb6d685a958183108588a8a91846fad3568b1bd5"
                },
                "type": "bbc",
                "repository": {
                    "repoSlug": "{33838c22-5066-425e-8a23-4a6699011119}",
                    "workspace": "{0a4fb641-0c65-44ab-bb4f-64a44bada7be}"
                }
            }
        ],
        "createdOn": "1970-01-01T00:26:23.273Z",
        "fullname": "opsgenie-plugin-test-1/opsgenie-notification-repository",
        "deployableName": "Owner or admin can delete the forwarding rule for everybody",
        "commitMessage": "Owner or admin can delete the forwarding rule for everybody"
    },
    "took": 0.051,
    "requestId": "a44339cf-ea48-42d5-bb09-d67b392674e8"
}

Deployments performed using other deployment tools

{
    "data": {
        "id": "7b25450b-c668-4eb4-b75c-77333ca1ada7",
        "externalId": "7b25450b-c668-4eb4-b75c-77333ca1ada7",
        "state": "successful",
        "environment": {
            "environmentType": "Test",
            "identifier": "og-test",
            "displayName": "og-test"
        },
        "type": "api",
        "startedAt": "2020-03-26T14:05:07.594Z",
        "completedAt": "2020-03-26T14:15:07.594Z",
        "releases": [
            {
                "commit": {
                    "sha": "0c9135c"
                },
                "type": "bbc",
                "repository": {
                    "repoSlug": "kagan-test-repo5",
                    "workspace": "saltbae-test"
                }
            }
        ],
        "message": "kagan-test"
    },
    "took": 5.134,
    "requestId": "6d50765f-7aae-44c2-bf8e-03cefedd2dfb"

Create Deployment

JSON Body Fields

Field

Mandatory

Description

Limit

state

true

Deployment state which can be any one of the following:
initial
started
successful
failed

environment

true

Depicts the environment in which the artifact was deployed. It contains the three fields where the type field can be any one of the values below:
Test
Staging
Production

The three values of the type field are for environment categorization purposes

startedAt

true

Date and time of when the deployment has begun

completedAt

false

Date and time of the completion of the deployment.

message

false

The deployment message

externalId

false

An identifier of the deployment other than that which will be created by the Opsgenie API upon completion of the Create request

description

false

Description of the deployment

externalLink

false

URL that links the deployment created within Opsgenie to the deployment in the deployment tool used

releases

true

Contians artifact information along with commits included which originate from the SCM tool of choice

Check out the list of SCM tools supported for the specific fields contained under releases.

enviornment field example:

"environment": {
  "type": "Test",
    "id": "us-west-2",
      "displayName": "Lab Oregon"
}

releases field example:
Check the SCM-specific fields here.

"releases": [
  {
    "type": "bbc",
    "repository": {
      "workspace": {
        "identifier": "opsgenie"
      },
      "repoSlug": "opsgenie-integration"
    },
    "commit": {
      "sha": "61445f308944af8f665326c29c02f16a4c3b0019"
    }
  }
]

Sample Payload

{
  "state": "started",
  "environment": {
    "type": "Test",
    "id": "us-west-2",
    "displayName": "Lab Oregon"
  },
  "startedAt": "2020-03-26T14:05:07.594Z",
  "completedAt": "2020-03-26T14:15:07.594Z",
  "message": "Hotfix for integration",
  "externalId": "2153ff23a294428ace87a89846699f35",
  "description": "Changed node types with versions: resource-deploy-RELEASE-20200323033142, api-RELEASE-20200323033142, devops-RELEASE-20200323033142, ",
  "reference": "http://jenkins.myownci.com//#/trace/2153ff23a294428ace87a89846699f35",
  "releases": [
    {
      "type": "bbc",
      "repository": {
        "workspace": {
          "identifier": "myownci"
        },
        "repoSlug": "myownci-integration"
      },
      "commit": {
        "sha": "61445f248943ag8a65346c29c03f16a4c3b0019"
      }
    }
  ]
}

Sample Request

curl --location --request POST 'https://api.opsgenie.com/v2/deployments' \
-H 'Content-Type: application/json' \
-H 'Authorization: GenieKey 5eebf5f6-7de1-454d-a590-ea3b271e8919' \
-d '{"state":"started","environment":{"type":"Test","id":"us-west-2","displayName":"Lab Oregon"},"startedAt":"2020-03-26T14:05:07.594Z","message":"Hotfix for integration","externalId":"2153ff23a294428ace87a89846699f35","description":"Changed node types with versions: resource-deploy-RELEASE-20200323033142, api-RELEASE-20200323033142, devops-RELEASE-20200323033142, ","reference":"http://jenkins-myownci.com/#/trace/2153ff23a294428ace87a89846699f35","releases":[{"type":"bbc","repository":{"workspace":{"identifier":"myownci"},"repoSlug":"myownci-integration"},"commit":{"sha":"61445f308944af8f665326c29c02f16a4c3b0019"}}]}'

Sample Response

📘

Createdeployment requests are processed asynchronously, therefore valid requests are responded with HTTP status 202 - Accepted.

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a23c5c-35bf-4ea4-9c26-a4f71023e120"
}

However, once getting the async response by using the Get Request Status operation either one of the responses below is expected, depending on whether the deployment has been successfully created or not.

Deployment creation is successful:

{
    "data": {
        "action": "Create",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": true,
        "status": "Deployment successfully created",
        "deploymentId": 5asdb4d8-6615-43c5-8613-c29f12bb630b"
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Deployment creation is unsuccessful:

{
    "data": {
        "action": "Create",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": false,
        "status": "Bitbucket Integration with name: opsgenie not found",
        "deploymentId": ""
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Update Deployment Status

In-Line Parameters

Referred Name

Description

identifier

Deployment identifier to specify which deployment to update.

Query Parameters

Parameter

Mandatory

Description

type

false

Deployments can be identified with the deployment id returned in the response after deployment is created. However you may also refer to deployments using an external id or Bitbucket Pipelines UUID if Bitbucket Pipelines is being used as the deployment tool. In that case specify the type as api or pipelines respectively.

JSON Body Fields

Field

Mandatory

Description

state

true

Deployment state which can be any one of the following:
initial
started
successful
failed

completedAt

true

Date and time of the completion of the deployment, or update of deployment state.

Sample Requests

curl --location --request PATCH 'https://api.opsgenie.com/v2/deployments/7b25450b-c668-4eb4-b75c-77333ca1ada7/updateState' \
-H 'Content-Type: application/json' \
-H 'Authorization: GenieKey 5eebfrf6-7we1-464d-a190-ea33271e4959' \
-d '{
    "state": "successful",
    "completedAt": "2019-11-07T14:44:02.374Z"
}'
curl --location --request PATCH 'https://api.opsgenie.com/v2/deployments/7b25450b-c668-4eb4-b75c-77333ca1ada7/updateState?type=api' \
-H 'Content-Type: application/json' \
-H 'Authorization: GenieKey 5eebfrf6-7we1-464d-a190-ea33271e4959' \
-d '{
    "state": "successful",
    "completedAt": "2019-11-07T14:44:02.374Z"
}'

Sample Response

📘

Update deployment requests are processed asynchronously, therefore valid requests are responded with HTTP status 202 - Accepted.

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a23c5c-35bf-4ea4-9c26-a4f71023e120"
}

However once getting the async response by using the Get Request Status operation the response below is expected.

{
    "data": {
        "action": "Update State",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": true,
        "status": "Deployment State updated successfully",
        "deploymentId": 5asdb4d8-6615-43c5-8613-c29f12bb630b"
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Update deployment

🚧

The Update endpoint is not compatible for Bitbucket pipeline deployments.

In-Line Parameters

Referred Name

Description

identifier

Deployment identifier to specify which deployment to update.

Query Parameters

Parameter

Mandatory

Description

type

false

Deployments can be identified with the deployment id returned in the response after deployment is created. .

JSON Body Fields

Field

Mandatory

Description

externalLink

false

URL that links the deployment created within Opsgenie to the deployment in the deployment tool used

description

false

Description of the deployment

message

false

The deployment message

externalId

false

An identifier of the deployment other than that which will be created by the Opsgenie API upon completion of the Create request

startedAt

false

Date and time of when the deployment has begun

Sample Request

curl -X PATCH \
  https://api.opsgenie.com/v2/deployments/80bb7f79-a730-4c10-a566-fd99023fc03b/update \
  -H 'authorization: GenieKey 422f0f3c-788b-7e0e-a8d7-93c7ec5bf2e8' \
  -H 'content-type: application/json' \
  -d '{
    "externalLink": "http://demo.in",
    "description": "test_description",
    "message": "test_message",
    "externalId": "test_externalId",
    "startedAt": "2020-08-07T14:44:02.374Z"
}'

Sample Response

📘

Update deployment requests are processed asynchronously, therefore valid requests are responded with HTTP status 202 - Accepted.

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a23c5c-35bf-4ea4-9c26-a4f71023e120"
}

However once getting the async response by using the Get Request Status operation the response below is expected.

{
    "data": {
        "action": "Update",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": true,
        "status": "Deployment updated successfully",
        "deploymentId": 5asdb4d8-6615-43c5-8613-c29f12bb630b"
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Search Deployments

Query Parameters

Parameter

Mandatory

Type

Description

serviceIds

true

Set<String>

A list of services to which the required deployments are mapped

environmentIds

false

Set<String>

Acts as a filter parameter to search for deployments within specific environments

startTime

false

@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)

Acts as a filter parameter to search on specific deployment start times

endTime

false

@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)

Acts as a filter parameter to search on specific deployment end times

paginationKey

false

Integer

Acts as the start index when returning a list of results in a paginated manner

limit

false

Integer

Allows to limit the number of search results

Sample Requests

curl --location --request GET 'https://api.opsgenie.com/v2/deployments/search?serviceIds=96f6655c-73f1-4d4b-a1a5-4b97dd8409b5&limit=10' \
--header 'Authorization: GenieKey a85cfdbf-3f6b-4ca4-a81b-2fe83da4fcbd' \
--header 'Content-Type: application/json'

Sample Response

{
   "data":[
      {
         "id":"0e1a5c8d-66a5-34a4-a315-733caa5e5636",
         "externalId":"{4d1cd861-99be-5708-9925-e4e153365098}",
         "type":"pipelines",
         "state":"successful",
         "startedAt":"2020-08-17T08:16:57.943Z",
         "completedAt":"2020-08-17T08:17:02.998Z",
         "message":"Deployment #5",
         "description":"2f5e052 Adding README123.md\n",
         "environment":{
            "type":"Production",
            "id":"{598f7ddd-21c3-4064-a569-4dac1b8b0280}",
            "displayName":"production"
         }
      },
      {
         "id":"a076ca38-a202-344c-afe0-c0b13baf51e5",
         "externalId":"{a5671456-6ebf-5bb5-a546-5ba44f480bf2}",
         "type":"pipelines",
         "state":"successful",
         "startedAt":"2020-08-07T04:55:56.815Z",
         "completedAt":"2020-08-07T04:56:01.439Z",
         "message":"Deployment #3",
         "description":"e20e4b7 Initial Bitbucket Deployments configuration",
         "environment":{
            "type":"Production",
            "id":"{598f7ddd-21c3-4064-a569-4dac1b8b0280}",
            "displayName":"production"
         }
      },
      {
         "id":"29a25632-1189-37ca-ae7b-8828e77ab077",
         "externalId":"{cf848148-506d-52ff-b909-9ec2d8312591}",
         "type":"pipelines",
         "state":"successful",
         "startedAt":"2020-08-17T08:11:33.326Z",
         "completedAt":"2020-08-17T08:11:37.91Z",
         "message":"Deployment #4",
         "description":"54135bc Adding readme file\n",
         "environment":{
            "type":"Production",
            "id":"{598f7ddd-21c3-4064-a569-4dac1b8b0280}",
            "displayName":"production"
         }
      }
   ],
   "took":4.448,
   "requestId":"3784efa6-fb53-4099-9ba6-5e71fc5f86d6"
}

SCM-Specific Fields

📘

Currently, Opsgenie only supports Bitbucket Cloud as the SCM tool managing the code base included in the artifacts deployed by the deployment tool of your choice. The deployment API allows you to capture deployments made by your preferred deployment tools. Hence before using the API, please connect your Bitbucket workspaces to your Opsgenie account and map your Bitbucket repositories to your Opsgenie services accordingly.

Bitbucket Cloud

Field

Mandatory

Description

Limit

type

Value should be bbc to set SCM tool holding release codebase as Bitbucket cloud

repository

Consists of two fields which are the workspace field and repoSlug which refer to the Bitbucket workspace and the specific repo within the workspace respectively. While referring your workspaces you can either type your workspace name or you can use UUID of the workspace as identifier and add type attribute with bbcUuid as it's value.

commit

The commit included in the release

Sample Payload

"releases": [
    {
      "type": "bbc",
      "repository": {
        "workspace": {
          "identifier": "opsgenie"
        },
        "repoSlug": "opsgenie-integration"
      },
      "commit": {
        "sha": "61445f308944af8f665326c29c02f16a4c3b0019"
      }
    },
    {
      "type": "bbc",
      "repository": {
        "workspace": {
          "identifier": "opsgenie"
        },
        "repoSlug": "opsgenie-apps"
      },
      "commit": {
        "sha": "61445f30894asdasdf665326c29c02f16a4c3b0019"
      }
    }
  ]

Did this page help you?