Documentation Grafana Cloud Observe and act Manage on-call and incidents Connect integrations Development and operations Jira

Jira integration for Grafana IRM

The Jira integration for Grafana IRM connects incident response to the Jira projects your teams already use. When you declare an incident, IRM can create a Jira issue for it and update the issue status as the incident progresses. During the incident, you can also turn incident tasks into Jira issues so you can track follow-up work in Jira.

Key features

The Jira integration provides the following features:

• Automatic Jira issue creation when you declare an incident
• Jira issue status updates when an incident becomes active or resolved
• Conversion of incident tasks to Jira issues
• Jira issue status on linked tasks, with the option to change it from IRM
• Links from IRM incidents to their Jira issues

Before you begin

The Jira integration works with Jira Cloud sites and classic Atlassian API tokens.

To set up the integration, you need:

• The Admin basic role or the IRM Admin RBAC role in Grafana. For more information, refer to Roles and permissions for Grafana IRM.
• A Jira Cloud account with administrative access.
• A classic Atlassian API token for that account. To create one, refer to Atlassian API tokens.
• The email address of the Atlassian account that owns the API token.
• Your Atlassian site URL, for example, https://your-domain.atlassian.net.

IRM acts in Jira as the Atlassian account that owns the API token. That account needs permission to do the following in each Jira project you use with IRM:

• Read its own user profile. IRM uses this to test the connection when you install the integration.
• Browse projects and read their issue types and statuses.
• Create issues.
• View and perform issue transitions.
• View the Jira issues linked to incident tasks.

Connect IRM to Jira

To install the Jira integration:

1. In the main menu, go to IRM > Integrations.
2. Select the Apps tab.
3. Click the Jira tile.
4. Enter the following information:
   • Atlassian Server URL: Your Atlassian site URL, for example, https://your-domain.atlassian.net.
   • User email registered with Atlassian: The email address of the Atlassian account that owns the API token.
   • Personal User Access Token: The API token by itself, not <EMAIL>:<TOKEN>.
5. Click Install Integration.

IRM tests the connection before it saves the integration. If the test fails, refer to Installation fails with insufficient permissions.

Create Jira issues automatically

After you install the integration, add an action that creates a Jira issue whenever someone declares an incident.

To add the action:

1. On the Jira integration page, find Create a Jira issue and click Run when an event fires.
2. Configure the following settings:
   • Jira Project to raise Issues: The Jira project where IRM creates issues.
   • Select issue type: The type of issue to create, for example, Task or Bug.
   • Select Incident active status: The Jira status for the issue while the incident is active, for example, In Progress.
   • Select Incident resolved status: The Jira status for the issue after the incident is resolved, for example, Done.
3. In Run this action when:, select Incident is declared. This is the only event available for this action.
4. Click Save.

The next time someone declares an incident, IRM creates a Jira issue with the following content:

• Summary: The incident title. For drill incidents, the summary starts with [DRILL].
• Description: A link to the incident in IRM. For drill incidents, the description also notes that the incident is a drill.

The incident shows a link to the new Jira issue.

How IRM updates Jira

After IRM creates the Jira issue, it moves the issue to the statuses you configured as the incident changes:

• When the incident becomes active, IRM moves the issue to the active status.
• When the incident is resolved, IRM moves the issue to the resolved status.

IRM only sends status changes to Jira. Keep the following in mind:

• Other incident changes, such as a new title or severity, don’t update the Jira issue.
• IRM doesn’t copy incident comments or timeline notes to Jira.
• Changes you make in Jira, such as a new status or comment, don’t update the IRM incident.
• IRM moves the issue with a single, direct transition in your Jira workflow. If the workflow doesn’t allow a direct move to the configured status, the issue keeps its current status. For more information, refer to Jira issue status doesn’t change.

Convert a task to a Jira issue

You can turn an incident task into a Jira issue to keep tracking the work in Jira after the incident ends. You can’t link a task to an existing Jira issue.

To convert a task:

1. In the incident, click the menu icon (three dots) next to the task.
2. Select Convert to Jira Issue.
3. Select the Jira Project and Issue Type.
4. Review the Issue title.
5. Optional: Add an Issue Body.
6. Click Create Jira Issue.

IRM creates the issue and adds a link to it on the task.

For more information about incident tasks, refer to Add and manage tasks.

Change the status of a linked Jira issue

A task that you converted to a Jira issue shows the issue’s current Jira status.

To move the issue to another status, click the status on the task and select one of the transitions that your Jira workflow allows. If someone deletes the issue in Jira, the task shows Deleted.

Troubleshooting

If the Jira integration doesn’t work as expected, first check the following:

• The API token is valid and hasn’t expired.
• The Atlassian site URL is correct.
• The Atlassian account that owns the token has the permissions listed in Before you begin.
• The Jira project you selected still exists, and the Atlassian account can access it.

Installation fails with insufficient permissions

When you install the integration, IRM tests the connection by reading the profile of the Atlassian account that owns the API token. If Jira denies that request, installation fails with an error such as jira.myself: client: atlassian insufficient permissions.

To fix this, make sure that:

• You’re using a classic API token, not an API token with scopes.
• The Atlassian account that owns the token has access to your Jira site.

Jira issue status doesn’t change

IRM moves a Jira issue with a single, direct transition. It doesn’t move the issue through intermediate statuses. If your Jira workflow has no transition from the issue’s current status to the status you configured, the issue keeps its current status.

Transitions are part of your Jira workflow, not the IRM configuration. To fix this, do one of the following:

• Ask a Jira administrator to add a direct transition to the target status, for example, a transition from any status to Done.
• In the IRM action, select a status that the issue can reach directly.

Other ways to connect Jira

If the Jira integration doesn’t fit your workflow, IRM offers two other options:

• Sync Jira issue with incidents in Grafana IRM: Use outgoing webhooks to create, update, and close Jira issues. Choose this option when you need more control over the fields and updates that IRM sends to Jira.
• Jira alert source integration: Send Jira issue events to IRM to create, acknowledge, and resolve alert groups. This option works with alert groups, not incidents.