Deployment gating

This module allows third-party providers to receive callbacks for deployments they've submitted for deployment gating.

Module type

jiraDeploymentGating

Sample JSON

1
2
"modules": {
    "jiraDeploymentGating": {
        "key": "my-deployment-gating",
        "name": {
            "value": "My deployment gating"
        },
        "callback": {
            "type": "jwt",
            "url": "/callback"
        }
    }
}

Properties

key

• Type: string (^[a-zA-Z0-9-]+$)
• Required: yes
• Description: A key to identify this module. This key must be unique relative to the app, with the exception of Confluence macros: their keys need to be globally unique. Keys must only contain alphanumeric characters and dashes.

name

• Type: i18n Property
• Required: yes
• Description: A human readable name. This name will not currently be visible in product.

callback.type

• Type: string
• Required: yes
• Allowed values: jwt
• Description: The method for authenticating and delivering the callback. This will be REST via HTTP using the standard Connect JWT authentication for jwt. See Callback for more information.

callback.url

• Type: URL
• Required: yes
• Description: The URL of the app resource that will receive the callback POST request when a gated deployment has a status update. This URL must be relative to the app's baseUrl. See Callback for more information.

Callback

A callback will be triggered when the status of a gated deployment is updated. Callbacks will only be received for deployments submitted by this app.

When the callback is triggered, the callback resource specified by the app will receive a POST request. The JSON payload of the request will contain the following fields:

• updatedTimestamp
  • Time the deployment gating status was updated.
• gatingStatus
  • Gating status at the time of update. This can be one of awaiting, allowed, prevented, or invalid. See Gating status for more information.
• details
  • Details associated with the gated deployment. Details have a type, such as issue, and additional fields are based on that type. For example, the issue type has an issueLink for a full HTTPS URL to the Jira issue gating the deployment, and an issueKey with the issue key.
• pipelineId
  • Unique identifier of the pipeline provided for the deployment.
• environmentId
  • Unique identifier of the environment provided for the deployment.
• deploymentSequenceNumber
  • Identifier provided for the deployment.

Note that these fields are the same as those returned when querying the Get deployment gating status by key API.

Callback retry policy

Deployment gating callbacks use the same retry mechanism and policy as Jira platform webhooks.

Gating status

There are currently four possible gating statuses that can be received in the callback payload. The meaning of each status is:

• awaiting
  • The submitted deployment has an associated change request that has not yet been transitioned to "allow" or "prevent" the deployment.
• allowed
  • The submitted deployment has an associated change request that has been transitioned to allow the deployment to proceed.
• prevented
  • The submitted deployment has an associated change request that has been transitioned to prevent the deployment from proceeding.
• invalid
  • The submitted deployment is not valid for deployment gating. This can happen when the configuration in Jira Service Desk is invalid.

Example

An example of the payload received in the callback is:

1
2
{
    "updatedTimestamp": "2020-08-25T06:04:50.239+00:00",
    "gatingStatus": "awaiting",
    "details": [
        {
            "type": "issue",
            "issueKey": "ITSM-1",
            "issueLink": "https://YOUR_SUBDOMAIN.atlassian.net/servicedesk/customer/portal/1/ITDSM-1"
        }
    ],
    "pipelineId": "e9c906a7-451f-4fa6-ae1a-c389e2e2d87c",
    "environmentId": "8ec94d72-a4fc-4ac0-b31d-c5a595f373ba",
    "deploymentSequenceNumber": 100
}