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.

FAQ

Can I configure the Jira Cloud extension with multiple services?

Expand

Yes, you can. You can continue to select multiple PagerDuty services in step 7 of the In PagerDuty section above.

Can I connect Jira Cloud with more than one PagerDuty subdomain?

Expand

No, this integration can connect one Jira Cloud instance with one PagerDuty account.

Is this integration bidirectional?

Expand

Yes! You can create Jira issues from PagerDuty incidents and PagerDuty incidents from Jira issues.

🚧

Limitations

  • As users are not mapped from PagerDuty to Jira, a Jira status is not able to move the PagerDuty status to Acknowledged.
  • The flow of status changes cannot move backward in PagerDuty via mapping statuses.

You can create PagerDuty incidents from Jira issues by navigating to Integrations Extensions find Jira Cloud in your extensions list Edit on Jira Cloud Extension Page Edit the Jira Cloud Configuration check the Create incidents with JQL box and then input your JQL query in the following field.

Select "Create incidents with JQL"

Select "Create incidents with JQL"

Can I create multiple Jira issues for the same incident?

Expand

No, only one Jira issue will be created.

Can I create Jira issues from resolved PagerDuty incidents?

Expand

Yes, but it will create them with the status of Done in Jira.

What types of Jira fields can I populate from PagerDuty?

Expand

You can populate the following types of fields:

  • Any field that takes a string
  • Labels
  • Number Fields
  • Select Lists (single & multi-choice)
  • Text fields (single & multi-line)
  • URLs
  • User Pickers (single user)

How can I populate the label fields from PagerDuty?

Expand

You can populate this field while configuring the Jira Project in PagerDuty:

  1. Click the New Field button to create a custom field to sync data.
  2. Choose Constant value as the PagerDuty Attribute.
  3. A text box input will appear. Enter the value you'd like to use for the label field. Note you can add multiple values by using a comma as a delimiter. (I.E: blue,red) However, due to restrictions on Jira's end, this field does not allow any white space to be passed in.

How can I populate the Reporter or Assignee field from PagerDuty?

Expand

You can populate this field while configuring the Jira Project in PagerDuty:

  1. Click the New Field button to create a custom field to sync data.
  2. Choose Constant value as the PagerDuty Attribute.
  3. In the text box, input the Jira username.

In order for this feature to work, your user must be visible to and retrievable by the PagerDuty application, which may require that the "PagerDuty" user be a member of a Jira group that has the Browse users and groups permission.

When I update the PagerDuty incident's status, the Jira ticket isn't getting updated. What's happening?

Expand

This can happen for the following reasons:

  • The Jira project's workflow requires that some fields are populated when setting it to that given state, and those fields aren't populated. You can configure the Jira extension to populate them when creating Jira incidents using the above method.
  • The Jira project's workflow does not permit the transition between the issue states corresponding to the previous and current PagerDuty incident states. For instance, if your Jira workflow does not permit setting a To Do status Jira ticket directly to Done, and the Triggered status in PagerDuty maps to To Do while the Resolved status maps to Done, then if a triggered incident is resolved (i.e. without acknowledging it first) then the ticket will not move to the Done state because this modification is not permitted per your Jira project's configured workflow.

I just updated the priority of a PagerDuty incident, why didn't the priority update in the Jira issue?

Expand

The Jira Issue is 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.

Why do I receive a "Jira test failed: cannot change status to requested state" error when trying to create a test issue?

Expand

The Create Test Issue button in PagerDuty tries to create a Jira issue and automatically maps it to the Resolved status in Jira. You will see this error if the workflow for your Jira project does not allow the Jira issue to transition directly from the Triggered status mapping to the Resolved status mapping.

Please create a Jira issue from a normal PagerDuty incident to determine if the integration works as expected.