JIRA Integration Guide (Legacy)

This legacy integration has been replaced by two new JIRA extensions. Our JIRA Cloud extension guide can be found here and our JIRA Server (on-premises) extension guide can be found here.

JIRA Software is a project management tool that enables collaboration between teams within an organization. This guide will walk you through the process of configuring JIRA and PagerDuty so that new issues created in JIRA will also create new incidents in PagerDuty, and marking an issue “Done” in JIRA will resolve the incident in PagerDuty.

In PagerDuty

1. From the Services menu, select Service Directory.
2. On your Services page: If you are creating a new service for your integration, click +New Service. If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the +New Integration button.
3. Select your integration from the Integration Type menu. To integrate with JIRA using this guide, select your integration type as JIRA Software. Next, enter an Integration Name.If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.
4. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.
5. Copy the Integration URL for your new integration.

In JIRA

Note: You must be an administrator in JIRA to perform these steps.

1. Go to the Administration cog icon, select System.
2. Click WebHooks on the left menu, under the Advanced links, then click Create a WebHook on the top right corner. Give your new webhook a Name, make sure its Status is set to Enabled, then paste the Integration URL you copied in step 3 earlier in to the URL field.Check created and updated under the Issue column so that JIRA will use this webhook to create incidents in PagerDuty for new issues, and resolve incidents in PagerDuty when an issue is marked Done in JIRA. By default, all JIRA issues will be included, however you can filter for specific issues by entering your desired search criteria (using JQL) in the text area above the event checkboxes.

FAQ

What versions of JIRA does this integration support?

At this time only JIRA Software is supported by this integration.

What JIRA events does this integration support?

The current version supports triggering new PagerDuty incidents when a JIRA issue is created, and resolving PagerDuty incidents when a JIRA issue is marked “Done.”

 

---

 

Email-based Integration Guide

If you prefer, you can also integrate with JIRA by creating an email-based service. This guide will walk you through how to configure your PagerDuty and JIRA accounts so that when a new issue is created in JIRA, a PagerDuty incident will get triggered, as well as how to configure PagerDuty to create tickets in JIRA, using the open-source tool.

In PagerDuty

1. In your account, under the Services tab, select Service Directory from the dropdown menu.
2. Click Add New Service.
3. Enter a Name for your service. Select your Escalation Policy. Begin to type JIRA in “Select a tool” next to the Integration Type menu. Click Add Service..
4. Copy the Integration Email in the Integration Settings section.

In JIRA

1. In order to integrate with PagerDuty, you’ll first need to create a JIRA user that’s associated with the PagerDuty email service that you just created. You must create a user since JIRA will not let you send out email notifications on projects that are not open to the public. Click on the Settings cog and select User management.
2. Click Create user.
3. Enter the username and name for your user.  Use the email address from step 6 (above) as the email address for the new user.  When completed, click the Create user button.  Note:  As soon as you create the user, it will trigger an incident within the new service that you created in PagerDuty.  You can go ahead and resolve the incident. 
4. Next you’ll need to either create a new Notification Scheme or add the new user to an existing notification scheme. For this guide, we will create a new notification scheme.  Click on the Settings cog icon and then select Issues.
5. Select Notification Schemes on the left menu, then select Add Notification Scheme.
6. Enter a name for your notification scheme, then click the Add button.
7. Under Operations, click on Add to add a new notification for when an issue is created.
8. Check the Single User radio button, then select the user that you created that’s tied to your PagerDuty account. Then click the Add button.
9. Now you will need to associate this Notification Scheme with the Project(s) that you want to notify PagerDuty. Click on the Settings cog icon and then select Projects.
10. Select the project that you’d like to associate with PagerDuty. For this guide, we are using a project named “Customer Critical” which is only used to trigger incidents in PagerDuty.
11. Click on Notifications on the left hand menu, then select Use a different scheme from the Actions menu.
12. Select the notification scheme that you created, then select Associate.
13. Now once you create a new JIRA issue in your project, an incident will get triggered within PagerDuty!

Using PagerDuty incidents to open JIRA tickets

If you would like PagerDuty incidents from any service to open a JIRA ticket when they are triggered, you can follow the steps below to use this open-source tool:  https://github.com/ryanhoskin/pd2jira.

1. You can host this on Heroku, or host it yourself. If you’re hosting this yourself, you will need to populate the variables at the beginning of the PHP script.  Once you’ve done this, you can skip to Step 5. If hosting on Heroku, continue to Step 2.
2. You should have a Heroku account set up first. Once you’ve set up your Heroku account and the PagerDuty service which you would like to trigger JIRA incidents, visit https://github.com/ryanhoskin/pd2jira and click Deploy to Heroku.
3. In Heroku, fill out the fields for the variables: JIRA_USERNAME (the username of the JIRA user you would like to create the JIRA ticket), JIRA_PASSWORD (that user’s password in JIRA), JIRA_SUBDOMAIN, JIRA_PROJECT (the prefix for the project in which you would like your JIRA tickets created), JIRA_ISSUE_TYPE (the issue type you want PagerDuty to create: Bug, Deliverable, etc), PAGERDUTY_API_TOKEN (found on your PagerDuty API Access page), and PAGERDUTY_SUBDOMAIN. The app name can optionally be left blank, or you can choose a name, but all other fields must completed.
4. When you have filled in this information, click Deploy at the bottom of the page. When your app has finished deploying, right click View It and copy the link address, or click View It and copy the URL from your browser’s address bar.
5. Visit your PagerDuty service, navigate to the Integrations tab and click New Extension. Choose “Generic Webhook” from the dropdown. Enter a name for your webhook, and paste your URL (from Heroku, or if hosting yourself, the URL where the PHP script is located) in the Endpoint URL field. If you’re pasting in your Heroku url, add pd2jira.php at the end, so that the finished product reads https://[YOUR-APP-NAME].herokuapp.com/pd2jira.php.To test: Trigger an incident on the PagerDuty service where you added the JIRA webhook. In the incident, you’ll see a note to the incident which will provide you with the JIRA ticket number, and a link to the ticket in JIRA.If you click on the link, you’ll be taken to the ticket in JIRA, where you’ll see a summary (with the PagerDuty service name, incident #, and incident summary), the reporter set to the user you defined in the variables, and the description with a link to the PagerDuty incident.

FAQ

Will the ticket in JIRA automatically close once the PagerDuty incident is resolved?

No. However, this is an open source integration, and it can be modified to satisfy your use case.

Will the PagerDuty Incident automatically resolve when the JIRA ticket is closed?

Yes, you can automatically resolve incidents in PagerDuty when a JIRA ticket closes if you have configured the email parsing feature for your JIRA service.

The following document will explain how to setup the email parsing feature for a JIRA integration: JIRA Email Parsing Guide.

How can I set up JIRA to be tied to multiple PagerDuty services?

In order to tie JIRA to more than one PagerDuty service, you would need to associate the PagerDuty user within JIRA to more than one Notification Scheme, which is then tied to different JIRA projects.