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 NameDescription
requestIdUniversally unique identifier of the questioned request. Please note: that ID of the request was provided within the response.

Get Deployment

In-Line Parameters

Referred NameDescription
identifierDeployment identifier to specify which deployment to update.

Query Parameters

ParameterMandatoryDescription
typefalseDeployments 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

FieldMandatoryDescriptionLimit
statetrueDeployment state which can be any one of the following:
initial
started
successful
failed
environmenttrueDepicts 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
startedAttrueDate and time of when the deployment has begun
completedAtfalseDate and time of the completion of the deployment.
messagefalseThe deployment message
externalIdfalseAn identifier of the deployment other than that which will be created by the Opsgenie API upon completion of the Create request
descriptionfalseDescription of the deployment
externalLinkfalseURL that links the deployment created within Opsgenie to the deployment in the deployment tool used
releasestrueContians 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 NameDescription
identifierDeployment identifier to specify which deployment to update.

Query Parameters

ParameterMandatoryDescription
typefalseDeployments 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

FieldMandatoryDescription
statetrueDeployment state which can be any one of the following:
initial
started
successful
failed
completedAttrueDate 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 NameDescription
identifierDeployment identifier to specify which deployment to update.

Query Parameters

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

JSON Body Fields

FieldMandatoryDescription
externalLinkfalseURL that links the deployment created within Opsgenie to the deployment in the deployment tool used
descriptionfalseDescription of the deployment
messagefalseThe deployment message
externalIdfalseAn identifier of the deployment other than that which will be created by the Opsgenie API upon completion of the Create request
startedAtfalseDate 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

ParameterMandatoryTypeDescription
serviceIdstrueSet<String>A list of services to which the required deployments are mapped
environmentIdsfalseSet<String>Acts as a filter parameter to search for deployments within specific environments
startTimefalse@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)Acts as a filter parameter to search on specific deployment start times
endTimefalse@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)Acts as a filter parameter to search on specific deployment end times
paginationKeyfalseIntegerActs as the start index when returning a list of results in a paginated manner
limitfalseIntegerAllows 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

FieldMandatoryDescriptionLimit
typeValue should be bbc to set SCM tool holding release codebase as Bitbucket cloud
repositoryConsists 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.
commitThe 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"
      }
    }
  ]