Jira Cloud Integration Guide | PagerDuty

Configure the Jira Cloud integration

Jira Cloud + PagerDuty Benefits

  • Tackle critical service requests and accelerate incident resolution with bidirectional sync between Jira Cloud issues and PagerDuty incidents.
  • Populate out-of-the-box or custom issue fields, sync incident priority and notes, and configure state mapping between Jira and PagerDuty.
  • Jira Cloud users can leverage PagerDuty’s integrations and PagerDuty AIOps functionality.
  • This integration also supports Jira Service Management.

📘

Availability

The Jira Cloud Integration is available on Professional, Business, and Digital Operations plans. This integration is not available in our free plan. Please contact our Sales team if you would like to upgrade your account to include the Jira Cloud Integration.

📘

Jira Server Integration

If you're using Jira on-premises, please refer to our Jira Server Integration Guide.

Requirements

To Configure the Integration

In PagerDuty:

  • Admins and Account Owners can configure the integration.
  • This integration only works with Jira Cloud for PagerDuty customers on our Professional, Business or Digital Operations plans.

To Use the Integration

In PagerDuty:

  • You must have a PagerDuty user license to use the integration.

How it Works

If the integration is configured to manually create incidents and issues:

  • When a user clicks Create Jira Issue on a PagerDuty incident, the action sends an Issue Created event to Jira Cloud, creating an issue.
  • When a user clicks Create New Incident on a Jira Cloud issue, the action sends a trigger event to PagerDuty, creating an incident.
  • PagerDuty incident and Jira issue statuses are mapped during integration configuration, and they are bidirectionally synced throughout the lifecycle of the incident and issue.

If the integration is configured to automatically create incidents and issues:

  • When a user creates a PagerDuty incident, it will automatically create a Jira issue.
  • When a user creates or updates a Jira issue matching a predefined JQL statement, it will automatically trigger a PagerDuty incident.
  • PagerDuty incident and Jira issue statuses are mapped during integration configuration, and they are bidirectionally synced throughout the lifecycle of the incident and issue.

Integration Walkthrough

In Jira Cloud

  1. Depending on your service region, navigate to one of the following apps in the Atlassian Marketplace:
  2. Once the app is installed, click Manage app in the confirmation dialog that appears. On the following screen, click Configure.
  3. You will see a PagerDuty Token in the instructions that populate. Copy this key and keep it in a safe place for later use. Note: For security reasons, the key in this step must be used within 30 minutes.

In PagerDuty

  1. Navigate to Integrations Extensions.
  2. On the Extensions page, click New Extension and then search and select Jira Cloud. A dialog will appear for the Jira Cloud Extension page; click Open.
  3. In the Jira key field, paste the PagerDuty Token generated in previous steps and then click Connect Jira Account.
  4. Next, search and select the service(s) where you want to add the extension from the dropdown. Then, select the Jira project that you want to connect to each PagerDuty service. When you are done, click Connect Jira Project.
  5. After connecting, you will be taken to a configuration screen. Enter the following information:
    • Configuration Name: Select a configuration name. We recommend using the name of the Jira project. For example: "Create Bug (Project Name)".
    • Jira Issue Type: Select a Jira issue type.
    • Create Issues Mode: Select one of the following based on your preferences:
      • Manually: To create an issue, users must click Create Jira Issue under the More button on an incident’s details page.
      • Automatically: PagerDuty will automatically create issues in Jira.
    • Sync Notes (optional): If you would like to sync notes with a user’s account, check this checkbox and select the user’s name from the dropdown.
    • Create incidents with JQL: If you would like to automatically create an incident if it matches a predefined Jira Query Language (JQL) statement, check this checkbox and then enter a JQL statement. Note: The issue must be in the same Jira project and be the same Jira issue type. If you are using Jira Service Management, incidents are created from JQL before automation rules are applied.
    • Map the status of PagerDuty incidents to the status of Jira Issues: Select the Jira status from the following dropdowns representing PagerDuty statuses:
      • Triggered Status
      • Acknowledged Status
      • Resolved Status
    • Sync PagerDuty incident priority levels with Jira priority levels (optional): Select the PagerDuty and Jira priority levels that you would like to sync.

      📘

      Priority Syncing via Incident Actions

      For priority syncing, Jira Issues are only updated when the PagerDuty incident triggers an action via webhook, such as an acknowledgement, assignment, resolve, etc. A full list of actions can be viewed in our webhook documentation.

      For example, an update to priority alone will not prompt the PagerDuty incident to sync with the Jira Issue. However, once the incident subsequently triggers an action via webhook, the priority will then sync.

      If you'd like PagerDuty to trigger an action for incident priority changes, please make a feature request by contacting our Support team.

    • Sync custom fields between a PagerDuty Attribute and Jira Issue Field Name (optional): Click New Field, check its checkbox and then select the PagerDuty Attribute and Jira Issue Field Name that you would like to sync. Repeat this process if you would like to sync more custom fields.
    • Create Test Issue: Click Create Test Issue to generate a test issue in your Jira account with your configured settings.
    • Click Save.
JQL configuration

JQL configuration

  1. Optional: To activate PagerDuty in a Jira project’s sidebar, navigate to your project Project settings Apps PagerDuty Sidebar and enable the toggle Enable Sidebar.
Configure PagerDuty sidebar

Configure PagerDuty sidebar

  1. The integration is now complete! Please see our Jira Cloud User Guide for instructions on using the integration.

Jira Service Management Required Steps

Follow our instructions to configure the Jira Service Management integration.

Jira Cloud User Guide

🚧

Required User Permissions

Jira Cloud users with PagerDuty user licenses can use the integration.

Create a Jira Issue From a PagerDuty Incident

If your Jira Cloud integration has been configured to create issues manually:

  1. Create a PagerDuty incident, or click an open incident’s Title to view its details page.
  2. Click the More dropdown and select Create Jira Issue.
  3. You then will see a confirmation dialog appear with a link to view the Jira issue. You may also view the Jira issue any time by clicking More and selecting View Jira Issue.

📘

Default Display

By default, PagerDuty will not be displayed on the sidebar for all Jira projects. See Step 9 above to enable this feature.

If your Jira Cloud integration has been configured to create issues automatically:

  1. Create a PagerDuty incident.
  2. In your Jira Cloud instance, an issue will automatically generate.

Create a PagerDuty Incident From a Jira Issue

If your Jira Cloud integration has been configured to create incidents manually:

  1. Create a Jira issue, or click an issue’s Title to view its details page.
  2. In the right panel, click PagerDuty Incident. The Incident Title will have the issue’s title auto-populated. You may enter an optional description. Click Create New Incident. Note: You may need to scroll down to view the Create New Incident button.
  3. You will then see the incident’s details within the Jira issue. You may view the incident in PagerDuty by clicking View in PagerDuty.

If your integration has been configured to create PagerDuty incidents based on issues matching a JQL statement:

  1. Create or update a Jira issue that matches the preconfigured JQL statement.
  2. In your PagerDuty instance, an incident will automatically trigger.

Jira Cloud Incident Workflow Action

📘

Configure Incident Workflow Actions

The following sections detail the capabilities of the Jira Cloud: Create an Issue for an Incident workflow action. For more information on how to configure this workflow action, please see our Incident Workflows article.

🚧

Requirements

  • The Jira Cloud Incident Workflow Action is available on Enterprise Incident Management plans.
  • PagerDuty Account Owners and Global Admins can create and edit all Incident Workflows. Other users can edit workflows and triggers for services where they have Manager access.

Create a Jira Issue With an Incident Workflow

In alignment with the conditional workflow trigger, the action to create a Jira Cloud issue will be initiated utilizing the data provided in the workflow configuration form.

The integration will validate the connection between Jira Cloud and PagerDuty, in addition to the following Jira Cloud information:

  • Jira Cloud project
  • Jira Cloud issue type
  • Jira Cloud issue fields

An API request is sent to create a Jira issue in accordance with the data provided in the workflow configuration form. Following a successful request, a new issue will be created in the associated project (created in the Open state).

No Synchronization of Data

There is no synchronization of data between the linked Jira issue and the PagerDuty incident, thus maintaining the intended separation between these two processes. Updates to the Jira issue will not cause a corresponding change to the PagerDuty incident, and updates to the PagerDuty incident will not cause a corresponding change to the Jira issue.

The linked Jira issue functions as a snapshot, capturing the PagerDuty incident state as it was when the Jira issue was created.

After the Workflow Executes

🚧

Limit

There is a maximum of 50 linked issues across all integrated applications.

  • The Jira issue link will be displayed on the incident details page in PagerDuty as an external reference (Linked Records) field.
  • A workflow log entry is added to the incident timeline, indicating the workflow and issue creation status.
  • The linked Jira issue will include a snapshot of the PagerDuty incident details, along with the incident link. Users can reference this information in the PagerDuty sidebar.

Examples

Expand

Supported Jira Fields and Data Types

The currently supported data types for a workflow action

Expand
  • text
  • integer
  • decimal
  • date
  • dateTime
  • boolean
  • singleChoice
  • multipleChoice
  • json
  • connection
  • trigger

The workflow action supports both standard and custom Jira fields. Users can send any value accessible from the configuration form to Jira. Once the user selects a Jira field, the dropdown menu will display all of the compatible PagerDuty fields.

Field Mapping

Mapping PagerDuty fields to Jira issue fields

Expand
  • PagerDuty text → Jira short text, paragraph (but no rich editor support), label
  • PagerDuty integer → Jira integer
  • PagerDuty URL → Jira URL
  • PagerDuty multi-select → Jira checkbox
  • PagerDuty single-select → Jira radio button, select list (single choice)
  • PagerDuty datetime → Jira date time picker
  • PagerDuty text → Jira label (tag)
  • PagerDuty assignee → Jira assignee (user picker)

Separate the Workflow Action From Existing Jira Cloud Configurations

As part of the integration walkthrough, users define the configuration rules between their Jira projects and PagerDuty services. This section highlights the separation between configuration rules and workflow actions, which are two separate and distinct processes.

Executing the Jira workflow Without Configuration Rules

When executing the workflow manually or automatically, if there are no configuration rules defined between the PagerDuty service and Jira project:

  • In PagerDuty: The workflow will create a Jira issue and add the link to the Linked Records field.
  • In Jira: The PagerDuty sidebar will include the incident link, as well as a snapshot of the incident state at the time the issue was created.
  • No Synchronization: Updates to the PagerDuty incident will not cause a corresponding change to the linked Jira issue. Updates to the linked Jira issue will not cause a corresponding change to the PagerDuty incident.

Executing the Jira Workflow with Configuration Rules Defined

When executing the workflow manually or automatically, if there are existing configuration rules defined between the PagerDuty service and Jira project:

Jira Issue Created by Configuration Rules

  • In PagerDuty: The configuration rule will create a separate issue, and link the issue in the Jira Issue field.
  • In Jira: The PagerDuty sidebar will include the Incident link and incident details.
  • Synchronization: Updates to the Jira issue will result in a corresponding change to the PagerDuty incident. Updates to the PagerDuty incident will result in a corresponding change to the Jira issue.
  • The issue is unaffected by workflow actions: This is a separate issue, so workflow actions will not apply.

Jira Issue Created by the Workflow

  • In PagerDuty: The workflow will create a separate Jira issue, and link the issue in the Linked Records field.
  • In Jira: The PagerDuty sidebar will include the incident link, as well as a snapshot of the incident state at the time the issue was created.
  • No Synchronization: Updates to the PagerDuty incident will not cause a corresponding change to the linked Jira issue. Updates to the linked Jira issue will not cause a corresponding change to the PagerDuty incident.
  • The issue is unaffected by configuration rules: This is a separate issue, so configuration rules will not apply.

FAQ

Please read Jira Cloud Integration FAQ for answers to common questions.