Jira Server Integration Guide | PagerDuty

Jira Server + PagerDuty Benefits

  • Tackle critical service requests and accelerate incident resolution with bidirectional sync between Jira Server 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 Server users can leverage PagerDuty’s integrations and PagerDuty AIOps functionality.
  • This integration also supports Jira Service Management.

📘

Jira Cloud Integration

If you use Jira Cloud, please see the Jira Cloud integration guide.

Requirements

To Configure the Integration

In PagerDuty:

  • This integration only works with Jira Server for PagerDuty customers on the following pricing plans: Professional, Business, Digital Operations (legacy) and Enterprise for Incident Management.
  • You will need an Admin or Account Owner role to create a REST API key.
  • The Jira administrator configuring this integration needs to also be a user within the PagerDuty account with valid login credentials.

In Jira Server:

  • To configure the integration, you must have Jira administrator permissions.
  • This integration is for Jira Server (self-hosted) for Jira Server 7.13.0 - 9.0.0, which can be downloaded from the Atlassian Marketplace.

To Use the Integration

In PagerDuty:

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

How it Works

  • Based on predefined rules set in Jira, when a PagerDuty incident performs a condition’s action, a webhook is sent to Jira where it can create or update an issue.
  • When a Jira issue performs a predefined condition’s action, a webhook is sent to PagerDuty where it can create or update an incident.

Version

This guide details configuration of the Jira Server V4.3.3 integration.

📘

Looking For a Different Version?

Our Jira Server v3 integration is also available.

Integration Walkthrough

In PagerDuty

  1. Navigate to Integrations API Access Keys and then click Create New API Key.
  2. Enter a description, e.g. Jira Server API Key, and then click Create Key.
  3. On the next screen, copy the API Key and paste it in a safe place for future use.

In Jira Server

  1. From the Jira Administration menu in the top right corner, click Manage Apps.
  2. In the Atlassian Marketplace, search for PagerDuty and then select the appropriate Jira Server download for your service region:
  1. After installing, select Manage Apps from the left menu, select PagerDuty, and click Configure.
  2. Click Login with PagerDuty and log in to connect your PagerDuty account.
  3. Click Connect Jira to PagerDuty to open up the next screen where you will configure your account.
  4. Paste the API Key you copied from PagerDuty and click Save.
  5. Add the required fields for the Jira instance that you’re working in.
  • For URLs, be sure to specify http or https in the field. If the protocol is not specified, the integration will use http. Click Save.
  • The user credentials should have read/write access to the connected projects and they should be basic auth credentials (username/password), not SSO.

Configure Automation Rules

To configure automation rules via the PagerDuty web app, continue to follow instructions below. If you would like to configure automation rules via API, please check out our Jira Server Integration API documentation.

  1. Next, you will configure automation rules, which will allow you to automatically trigger incidents, create issues, and keep status updates synchronized between PagerDuty and Jira. If you are already on the PagerDuty settings page, select the Rules tab and then click Create Rule. If you are returning to configuration, navigate to Manage Apps PagerDuty Configure Rules tab and click Create Rule.
  2. Enter a Rule name, Select PagerDuty service(s), Select JIRA Project(s), Select JIRA Issue Type(s) and you may optionally check the Sync comments & notes checkbox.
  3. Check the following rule options based on your preferences:

Automatically create PagerDuty incidents from JIRA issues:

  • When issue matches JQL: Enter your preferred JQL. Select whether you would like this rule to run On issue create and/or On issue update.
    • Additional actions after incident is created (optional): Select your preferred actions.
    • Another form will auto-populate below, and you may choose to add multiple conditions, based on your preferences.

Сreate JIRA issues from PagerDuty incidents:

  • Create issue when incident: Select your preferred incident action that will generate a Jira issue. Optionally, you may also choose to specify the priority and/or the urgency by selecting an option from the AND priority is one of and/or AND urgency is dropdowns.
    • Create issue into project: Select the Jira project where you would like PagerDuty incidents to generate Jira issues. Next, select the Issue type that you would like generated, and if your Jira issue type has any required fields, you will need to set those required fields to populate by choosing Additional actions on issue create (optional).
    • Another form will auto-populate below, and you may choose to add multiple conditions, based on your preferences.

Automatically update Jira issue:

  • When PagerDuty incident has linked issue AND: Select your preferred incident action that will update a Jira issue. Optionally, you may also choose to specify the priority and/or the urgency by selecting an option from the AND priority is one of and/or AND urgency is dropdowns.
    • Actions: Select your preferred Jira issue action that will occur based on the condition specified above.
    • Another form will auto-populate below, and you may choose to add multiple conditions, based on your preferences.

Automatically update PagerDuty incident

  • When Issue status changes to: Select your preferred Jira status that will update the PagerDuty incident.

    • Actions: Select your preferred PagerDuty incident action that will occur based on the condition specified above.
    • Another form will auto-populate below, and you may choose to add multiple conditions, based on your preferences.
  • Click Save to save your rule(s). You should see the following webhook check dialog if the connection was successful:

Webhook update summary

Webhook update summary

If you receive an unsuccessful webhook error, navigate back to the Rules tab and click the Check webhooks… button to troubleshoot the error. Once the webhook check has been successfully completed, you may move on to the next section to link your PagerDuty and Jira accounts.

Link PagerDuty and Jira User Accounts

Linking PagerDuty and Jira user accounts allows us to identify which user changed an incident or issue using the integration workflows. It also allows users to define who an incident/issue should be assigned to. If a user account is not linked and if the user hasn't configured a Jira fallback user (see step 17) then the integration will not pick up those user-made changes. You can either have a Jira administrator link user accounts, or individuals can link their own PagerDuty accounts between systems.

  • To have a Jira administrator link the accounts: Follow steps 14-17 below.
  • To have individual users link their accounts: Skip to step 18.
  1. If you are still on the PagerDuty settings page, select the User mapping tab and then skip to step 16. If you are returning to configuration, from the top right Jira Administration menu, select Manage Apps.

  2. Select Manage Apps again from the left menu, click the PagerDuty add-on, then click Configure.

  3. Under PagerDuty settings, click the User mapping tab and click Link Users to start mapping user accounts between systems.

User mapping configuration

User mapping configuration

  1. On this page you can also set up users to be optionally mapped based on email, and a fallback user in the event that a user wants to take action on an incident but their account isn’t mapped.
  2. To have individual users link their accounts, they will need to go to an issue in your Jira project, and click on the Users icon to link their user accounts. If the icon is orange, their user account isn't linked. Once linked, the icon will appear grey.
Incident details

Incident details

Once your Jira and PagerDuty accounts have been linked, the integration is complete.

Connect Multiple PagerDuty Accounts

To connect multiple PagerDuty accounts, navigate to the Account Integrations page, click Logout at the bottom of the page. Click Login with PagerDuty and log in on the screen that pops up to connect your PagerDuty account. You will need to complete the Integration Walkthrough steps 1-3 (above) and complete the Link PagerDuty and Jira User Accounts section again based on your secondary account information.

Connect Multiple Jira Accounts

To add another Jira account, log in to the secondary Jira instance and complete the Integration Walkthrough steps 1-13, above.

Jira Service Management Required Steps

  1. If you are integrating PagerDuty with Jira Service Management, you need to ensure that the PagerDuty user account in Jira has the necessary permissions.
  2. For each of your Service Desk projects, ensure that the PagerDuty user account has Service Desk Team access.
    a. From the Jira Administration menu in the top right corner, click Projects.
    b. Select your Jira Service Management project.
    c. Click the Users and roles tab under the Project settings navigation bar.
    d. Select the Add users to a role button.
    e. Add the jira-servicedesk-users group or PagerDuty user to the Service Desk Team role.

You can learn more about managing users and roles in Atlassian’s documentation.

Migrate from Jira Server to Jira Cloud

We do not provide an automatic migration path at this time. In order to migrate from Server to Cloud:

  1. Follow the instructions to configure the Jira Cloud integration with necessary service mappings. Test the flow by following the Jira Cloud User Guide.
  2. Uninstall your Jira Server integration following steps below once have configured the Jira Cloud integration.

Uninstall Jira Server

  1. Navigate to Integrations Extensions click Jira Cloud Extension Page to the right of your extension.
  2. Click How to Uninstall, follow the instructions listed and then click Delete Configuration.

FAQ

Is this integration bidirectional?

Expand

Yes, you can create Jira issues from PagerDuty incidents and PagerDuty incidents from Jira issues.

What if my JIRA Server is behind a firewall?

Expand

In order to allow bidirectional integration between PagerDuty and your JIRA Server, it may be necessary for you to configure your firewall to allow for incoming traffic from PagerDuty. For more information, please see Safelist IPs. You’ll specifically need to safelist IPs for PagerDuty webhooks, the REST API, and specific IPs for Jira Server.

Does the JIRA Server integration support mandatory custom fields?

Expand

Yes. You can have PagerDuty populate mandatory Jira fields. You can define then while configuring the Create Jira Issues from PagerDuty incidents settings.

Mandatory custom field configuration

Mandatory custom field configuration

When testing, I don’t see an incident or issue being created?

Expand

To troubleshoot, the Jira administrator can navigate to global settings , select Manage Apps, click the PagerDuty app, and click Configure. Select the Debug logs tab. With this window still open, open another tab or window on your browser and then try to test the integration’s workflow. You will be able to see any errors or successes in the debug logs as long as you keep the window open while testing.

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 be populated when setting it to that given state, and those fields aren't populated.
  • 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.

One way that you can ensure the workflow configuration does not interfere is to edit the statuses corresponding to acknowledged and/or resolved, and enabling transitions from all other statuses to it.

Configure transition status

Configure transition status

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 that would trigger a v2 webhook. A full list of actions can be viewed in our webhook documentation. If you'd like PagerDuty to trigger an action for PagerDuty incident priority changes, please make a feature request with our Support Team.

Can we turn off the PagerDuty sidebar app for projects that don't use PagerDuty?

Expand

You can disable the sidebar for a specific project by navigating to that project in Jira, clicking into the Project Settings PagerDuty integration and toggling off next to Show PagerDuty issue sidebar for this project.

What happens to my workflow rules when I upgrade from another version to this version (4.x.x)?

Expand

If you upgrade from another version, we maintain all your existing workflow rules in the PagerDuty web app. They will continue to use the PagerDuty integration user, and they can be edited in the PagerDuty web app. New rules can be created in Jira, and the previously-created rules will appear in a read-only format.

If you wish to upgrade these rules to the v4 version, you can recreate them by following steps 11-13.

What happens when the Jira user who set up the integration is removed from the Jira account?

Expand

You will need to reauthorize the integration by following steps 1-3 and steps 6-10 in the guide above.

In the Rules settings page, what happens if I use the toggle “Show PagerDuty sidebar on projects by default”?

Expand When the toggle is switched to OFF for the first time:
  • The PD sidebar will continue to be displayed for connected projects
  • The PD sidebar will now be hidden for non-connected projects
  • The PD sidebar will not be displayed for newly created projects going forward, until it is connected to a PD
  • Service or it is manually enabled in the project-level settings page
  • A dialog box will appear that will guide the user with this bulk operation experience

When the toggle is switched to ON:

  • The PD sidebar will continue to be displayed for connected projects
  • The PD sidebar will now be displayed for non-connected projects
  • New projects created after this operation will display the PD sidebar

When the toggled is switched to OFF for subsequent times:

  • The PD sidebar will continue to be displayed for connected projects
  • The PD sidebar will now be hidden for non-connected projects
  • The PD sidebar will not be displayed for newly created projects going forward, until it is connected to a PD
  • Service or it is manually enabled in the project-level settings page
  • A dialog box will no longer appear during this operation.

I have renamed a Jira Base URL in my Jira Server instance. How can I update the Jira Base URL on the PagerDuty side?

Expand If you have renamed a Jira Base URL, or plan to do so, please reach out to [email protected] and our Support team will assist with the rename.