Skip to main content
Rootly’s Jira integration keeps incidents and Jira issues in sync. When an incident is declared, a Jira issue is automatically created. Updates flow both ways: incident changes update Jira, and Jira changes can update incidents.

Smart Defaults

Auto-create Jira issues at incident start without building workflows

Custom Workflows

Advanced automation with triggers, conditions, and multiple actions

Field Mapping

Map incident data to Jira native and custom fields

Action Items → Subtasks

Follow-up tasks become Jira subtasks linked to the parent issue

How It Works

1

Connect Jira

Authenticate via OAuth and configure webhooks for bidirectional sync.
2

Configure Automation

Use Smart Defaults for instant setup, or build custom workflows for conditional logic.
3

Incident Declared

When an incident is created, Rootly automatically creates a Jira issue.
4

Updates Flow Both Ways

Changes to incidents update Jira. Jira events can trigger incident updates.

Before You Begin

Before you start, you’ll need:
  • A Rootly account with Admin or Owner permissions
  • A Jira Cloud account with admin rights to your instance

Required Jira Permissions

The Jira account you use to install must have these permissions:
Learn more about Jira permissions in Atlassian’s documentation.

Required OAuth Scopes

Rootly requests these OAuth scopes during installation:
Read permissions:
  • read:application-role:jira
  • read:avatar:jira
  • read:field-configuration:jira
  • read:group:jira
  • read:issue:jira
  • read:issue-status:jira
  • read:issue-meta:jira
  • read:issue-security-level:jira
  • read:issue-type:jira
  • read:issue-type-hierarchy:jira
  • read:issue.changelog:jira
  • read:issue.transition:jira
  • read:issue.vote:jira
  • read:priority:jira
  • read:project:jira
  • read:project-category:jira
  • read:project-version:jira
  • read:project.component:jira
  • read:project.property:jira
  • read:status:jira
  • read:user:jira
  • read:user.property:jira
Write permissions:
  • write:attachment:jira
  • write:comment:jira
  • write:comment.property:jira
  • write:issue:jira
  • write:issue.property:jira

Installation

Setting up the Jira integration involves two parts: connecting your Jira account via OAuth and configuring a webhook so Jira can send events back to Rootly. Both are required for full bidirectional sync. The OAuth flow connects your Jira Cloud instance to Rootly. You’ll be redirected to Jira to authorize the connection, then returned to Rootly automatically.
1

Go to Configuration → Integrations

In the Rootly sidebar, click Configuration → Integrations.Rootly integrations menu
2

Find Jira Cloud and click Setup

Search for Jira Cloud and click Setup.Jira Cloud integration setup
3

Authorize in Jira

You’ll be redirected to Jira. Verify you’re installing on the correct instance, then click Accept.Jira OAuth authorizationJira permissions acceptance
4

Installation complete

You’ll be redirected back to Rootly with a success message confirming the connection.Jira installation success
Your Jira Cloud instance is now connected to Rootly.

Installing Additional Instances

If your organization uses multiple Jira Cloud instances, you can connect them separately.
A Jira Cloud instance is not the same as a Jira project. An instance is a separate domain (for example, company.atlassian.net). You can have multiple projects within one instance — most organizations have a single instance with multiple projects.
To add another instance:
  1. Go to Integrations and search for Jira Cloud
  2. Click Set up another instance
  3. Follow the same authorization flow
Make sure you’re logged into the correct Jira instance in your browser before starting the authorization flow.

Setting Up the Jira Webhook

To enable Jira → Rootly sync, you must configure a webhook in Jira. This allows Rootly to receive events when Jira issues are created or updated. Without this step, changes in Jira won’t reflect back in Rootly.
1

Open Jira Webhooks

In Jira, navigate to Settings → System → WebHooks.Jira system settingsJira webhooks menu
2

Create a new webhook

Click Create a WebHook.Create webhook button
3

Configure the webhook

Give it a descriptive name (for example, “Rootly Webhook Listener”) and ensure the status is set to Enabled.Webhook name and status
4

Add the Rootly webhook URL

In Rootly, go to Integrations → Jira → Configure and copy the webhook URL. Paste it into the URL field in Jira.Rootly webhook URLWebhook URL field in Jira
5

Filter by project (optional)

To limit which projects send events to Rootly, add a JQL filter under Issue related events. Leave this blank to receive events from all projects.JQL filter for projects
6

Select events

Choose the Jira events you want Rootly to receive — at minimum, select issue created and issue updated.Webhook event selection
7

Keep request body enabled

Ensure Exclude body is not checked. Jira may enable this by default, but Rootly requires the full event payload to process events correctly.Exclude body checkbox
8

Save the webhook

Click Create to save your webhook configuration.Save webhookWebhook created confirmation
Your Jira webhook is now configured for bidirectional sync.

Verify Installation

Once connected, confirm the integration is working end-to-end:
  1. Check integration status — The Jira tile in Rootly should show Connected.
  2. Test Rootly → Jira — Create a test incident and verify that a Jira issue is created in the expected project.
  3. Test Jira → Rootly — Create or update a Jira issue, then check the Alerts page in Rootly to confirm the event arrived.
If events appear on the Alerts page, your webhook is configured correctly.

Workflows

Smart Defaults

Setup fast and effortlessAutomatically create and manage Jira issues at incident start using pre-configured settings

Custom Workflow

Use workflows for conditional or advanced Jira issue automation

Smart Defaults

Smart Defaults let you automatically generate a Jira issue whenever an incident begins — without building a workflow. New Rootly accounts have Smart Defaults enabled automatically. Existing accounts have it off by default to avoid conflicting with existing workflows. To configure Smart Defaults, go to Integrations → Jira → Configure.
Configure webhooks in your Jira Admin using this endpoint to allow updates made in Jira to reflect back in Rootly.
See Setting Up Jira Webhook for detailed steps.
Jira webhook URL configuration in Rootly
This section controls how Jira tickets are created from Rootly incidents.Jira ticket configuration panel for incidents
toggle
Automatically create a Jira ticket in the specified project as soon as an incident is declared in Rootly.
select
The Jira project where tickets will be created. If you need to route tickets to different projects based on conditions, disable this and use custom workflows instead.
select
The type of Jira issue to create. Options are pulled from the project specified in Project Key.
select
The initial status of the new ticket. Options are pulled from the selected project and issue type.
string
The Summary field of the Jira ticket. Defaults to {{ incident.title }}. Supports Liquid syntax.
string
The Description field of the Jira ticket. Defaults to {{ incident.summary }}. Supports Liquid syntax.
string
Assign the Jira ticket to a user by email address. If blank, the ticket is assigned to the incident creator. Supports Liquid syntax.
toggle
Automatically create a bookmark to the Jira ticket in the incident’s Slack channel for quick access.
toggle
Automatically update the matching Jira ticket whenever the incident is updated. This is one-way: changes flow from Rootly to Jira only.
This section controls how Jira subtasks are created from Rootly action items.Jira subtask configuration for action items
toggle
Automatically create a Jira subtask under the parent Jira ticket every time a new action item is created in Rootly.
select
Leave this field blank. Jira subtasks can only be one type. This field will be expanded in a future release.
select
The initial status of the new subtask. Options are pulled from the project specified in Project Key.
toggle
Automatically update the matching Jira subtask whenever an action item is updated. This is one-way: changes flow from Rootly to Jira only.
toggle
Automatically set the Jira subtask priority to match the action item priority in Rootly.
Use Smart Defaults when you want instant, built-in Jira issue automation without touching workflows. Build a workflow when you need conditions, custom triggers, multiple actions, or more advanced issue routing.

Custom Workflows

Custom workflows give you full control over when and how Jira issues are created or updated. You can filter by severity, service, environment, and more — or chain multiple Jira actions together in a single workflow.
1

Create a new workflow

Open Rootly → Workflows → Create Workflow and choose the workflow type that matches your use case.Rootly workflows pageCreate workflow buttonWorkflow type selection showing Incident, Retrospective, and Pulse options
2

Configure triggers

Triggers define when the workflow runs. Choose the event that should create or update a Jira issue.Workflow trigger configuration options
Choose the trigger that fires only when you actually need a Jira issue. Avoid creating issues earlier than necessary.
3

Add conditions

Conditions let you control when the workflow should run after it’s been triggered. This keeps your Jira project clean by limiting automation to the incidents that matter.Workflow conditions panel showing filter optionsCommon condition setups:
  • Severity-based — Only create Jira issues for SEV-1 or SEV-2 incidents
  • Team or service filters — Only fire for incidents impacting specific teams or services
  • Incident type — Ensure the workflow only runs when the Kind is set to Incident
  • Environment — Trigger only for customer-facing or production-impacting incidents
Use conditions to avoid unnecessary Jira issues and keep the workflow focused.
4

Add a Jira action

Actions are the steps that run when the workflow fires. Click Add Action, then search for Jira to see the available actions.Add action button in workflow editorJira action search in action picker

Create Jira Issue

Creates a new Jira issue for an incident or retrospective.Create Jira Issue action configuration
string
Optional label for this action. Does not affect behavior.
select
The Jira project where the issue will be created.
select
The type of Jira issue to create (for example, Bug, Task, Story). Options are pulled from the selected project.
string
Title of the Jira issue. Supports Liquid syntax (for example, {{ incident.title }}).
string
Detailed description. Supports Liquid syntax (for example, {{ incident.summary }}).
select
Priority of the Jira issue (for example, High, Medium, Low).
select
Initial status of the issue. Options are pulled from the selected project and issue type.
array
Jira labels to categorize the issue. Supports multiple values.
string
Optional due date. Supports Liquid syntax or fixed dates.
string
The reporter for the Jira issue. Defaults to the incident creator. Supports Liquid syntax.
string
The assignee for the Jira issue. Supports Liquid syntax.
toggle
Prevents the workflow from stopping if this action fails.
toggle
Toggle this action on or off, useful when testing.
Use Rootly’s Liquid Variable Explorer to test variables before using them in your workflow.

Update Jira Issue

Updates an existing Jira issue. You must reference the issue using {{ incident.jira_issue_id }} in the Jira Issue to Update field.
This action only works if a Jira issue has already been created and linked to the incident.
The Update Jira Issue action also works inside Action Item Workflows. When paired with the Action Item Updated trigger, it’s the canonical way to enrich Jira tickets created via Export to ticketing with incident context (Rootly URL, severity, services, etc.) — see Linking Exported Tasks Back to the Incident. In an action item workflow, use {{ action_item.jira_issue_id }} instead of the incident-side variable.

Create Jira Subtask

Creates a subtask under an existing Jira issue. Reference the parent issue using {{ incident.jira_issue_id }} in the Parent Jira Issue field. The Project Key must match the one used to create the parent issue.
This action is intended for action items or sub-incidents.
5

Name and save the workflow

Give your workflow a descriptive name (for example, “Create Jira Issue on SEV-1 Incident”), then click Create Workflow.

Action Reference

Creates a new ticket in a Jira project. You must select the Project Key and Issue Type for the ticket to be created correctly.This action can be used for both incidents and action items. For action items, using Create Jira Subtask is recommended if your team uses subtasks — but if not, this action works as well.
Create Jira Issue action
select
The Jira project where the issue will be created.
select
The type of Jira issue to create. Options are pulled from the selected project.
string
The title of the Jira issue. Supports Liquid syntax (for example, {{ incident.title }}).
string
The description of the Jira issue. Supports Liquid syntax (for example, {{ incident.summary }}).
string
Assign the Jira issue to a user by email. Supports Liquid syntax.
Updates an existing ticket in Jira. You must reference the issue in the Jira Issue to Update field using {{ incident.jira_issue_id }}.
Update Jira Issue action
This action only works if a Jira issue has already been created and linked to the incident.
string
Reference to the existing Jira issue. Use {{ incident.jira_issue_id }} to dynamically target the issue linked to the current incident.
string
Updated title of the Jira issue. Supports Liquid syntax.
string
Updated description. Supports Liquid syntax.
select
Transition the issue to a new status. Options are pulled from the selected project and issue type.
string
Reassign the Jira issue to a different user. Supports Liquid syntax.
Creates a subtask under an existing Jira issue. Intended for action items or sub-incidents. The Project Key must match the one used when creating the parent issue.
Create Jira Subtask action
string
Reference to the parent Jira issue. Use {{ incident.jira_issue_id }} to link the subtask to the current incident’s issue.
select
Must match the project used to create the parent issue.
string
Title of the subtask. Supports Liquid syntax.
string
Description of the subtask. Supports Liquid syntax.
string
Assign the subtask to a user by email. Supports Liquid syntax.

Jira Native Field Mapping

Some Jira fields behave differently than standard custom fields. This section explains how to correctly map Rootly fields to Jira’s native fields.
These mappings go in the Custom Fields Mapping section of the Jira action, not the API Payload section.
Jira’s native Labels field uses a different syntax than custom label-type fields.Map Rootly services to Jira Labels:
Map a Rootly custom multi-select to Jira Labels:
Replace customfield_12345 with your actual Jira field ID. Find field IDs in Jira Settings → Issues → Custom Fields.
Jira’s native Team field is stored as a custom field but only allows a single team selection.Map a static Jira Team ID:
Map Rootly’s first team dynamically:
This example assumes you store the corresponding Jira Team ID in the Rootly team’s description field. Adjust based on how your teams are configured.

Custom Fields Mapping

The Custom Fields Mapping section lets you map Rootly incident data to Jira custom fields dynamically. Advanced tab for custom field mapping in Jira action

What You Need

For detailed instructions on finding Jira field IDs, see Atlassian’s documentation.

Field Type Mappings

Note the { "value": ... } wrapper required by Jira:
Simple approach (Rootly custom multi-select):
Manual array building (Rootly native fields):
For Jira custom fields of type “Labels” (different from the native Labels field):
Must use ISO 8601 format:
Single user:
Multiple users:

How to Test Your Mapping

  1. Create a test incident in Rootly
  2. Run your workflow manually
  3. Check the Jira issue to verify fields are populated correctly
  4. If errors occur, go to Workflows → Your Workflow → … → View Runs to see the error details

API Payload

The API Payload section provides direct access to Jira’s REST API for advanced field updates not available through Custom Fields Mapping.
API Payload uses Jira’s update issue REST API. Fields use verb-based operations: set, add, and remove.

When to Use API Payload

API Payload Examples

Add a comment to an existing Jira issue. Only works with the Update Jira Issue action.
Comments can only be added to existing issues. Use this with the Update Jira Issue action, not Create.
Component names must match exactly between Rootly and Jira. If a component doesn’t exist in Jira, the update will fail.

API Payload Verbs


Best Practices

  • Name workflows clearly. Use names like Create Bug on High-Priority Incident or Update Jira Issue on Resolution so the intent is obvious.
  • Keep logic simple. Avoid overly complex conditions or chained automations — simpler workflows are easier to debug.
  • Test in a sandbox project. Before applying to production, trigger test incidents to verify issues are created and updated as expected.

Syncing Jira Changes Back to Rootly

  1. Jira sends events to Rootly via webhook
  2. Events appear as alerts on Rootly’s Alerts page
  3. Alert workflows process these events and create or update incidents

Create an Alert Workflow

1

Create a new workflow

Go to Workflows → Create Workflow and select Alert as the workflow type.
2

Set the trigger

Select Alert Created as the trigger. This fires whenever a new alert arrives in Rootly — including events from Jira.
3

Add conditions

Filter to only process Jira alerts so the workflow doesn’t fire on unrelated alert sources. You can filter by source and by label:
  • Set Source equals Jira
  • Use label filters to narrow by event type or project:
    • event:jira:issue_created — responds to new Jira issues
    • event:jira:issue_updated — responds to Jira issue updates
    • project_key:YOUR_PROJECT — (optional) limits to a specific Jira project
For more targeted filtering, use the Payload condition with JSON path syntax (for example, $.issue.fields.issuetype.name). You can preview your syntax using the JSON Path Explorer.
Only a single payload field can be filtered at a time. Use label conditions as much as possible before falling back to payload filtering.
4

Add an action

Choose Create Incident or Update Incident from the action picker depending on whether you want to open a new incident or update an existing one.

Sync Actions

Creates a new Rootly incident from a Jira alert.Use {{ alert.data.* }} to reference Jira fields when populating incident properties:Link back to Jira — Add this to Custom Field Mapping so Rootly knows which Jira issue this incident came from. This mapping is required if you later want to update the incident when the Jira issue changes.

Field Mapping Examples

Use Custom Field Mapping to dynamically set incident properties from Jira data.
Maps Jira priority levels to Rootly severity IDs. Adjust the priority names to match your Jira configuration.
Maps Jira workflow statuses to Rootly incident statuses. Replace the Jira status names with your actual values.
Valid Rootly statuses: in_triage, active, resolved, closed, cancelled
Sets a Rootly custom field to a fixed value. Replace form_field_id with your actual field ID.
Pulls a value from a Jira custom field and sets it on the Rootly incident. Inspect the alert payload to find the correct field path.
Find the correct JSON path by inspecting alert payloads on the Alerts page in Rootly.
For single or multi-select Rootly custom fields, use selected_option_ids instead of value.

Troubleshooting

Issue: After completing OAuth, Jira doesn’t show under Connected Apps.Solutions:
  • Ensure you completed the full OAuth consent flow without navigating away
  • Confirm your Jira user has admin or manage apps permissions
  • Log out of other Jira accounts and retry authorization
  • Revoke the app in Jira (Settings → Apps → Manage Apps) and reconnect
Issue: Jira connects but no projects appear in Rootly.Solutions:
  • Verify your Jira account has Browse Projects permission
  • Check project-level permissions for Create Issues, Edit Issues, and Add Comments
  • Re-authenticate to refresh your permission scopes
Issue: Integration connects but Rootly can’t create issues in Jira.Solutions:
  • Verify your Jira user has: Create Issues, Edit Issues, Assign Issues, Add Comments
  • Check for required custom fields in Jira that aren’t being populated by Rootly
  • Confirm the issue type exists in the selected project
  • Review Jira workflow validators that may block external issue creation
Issue: Jira events don’t show on Rootly’s Alerts page.Solutions:
  • Verify the webhook URL in Jira matches the one from Rootly
  • Ensure Exclude body is NOT checked in the Jira webhook settings
  • Confirm the webhook status is Enabled
  • Check that your JQL filter (if used) includes the project you’re testing with

Debugging Workflows

To view error details, locate the workflow in Rootly, then select … → View Runs → View.

Debugging Sync

View error details: Workflows → Your Workflow → … → View Runs → View

Uninstall

To remove the Jira integration:
  1. Go to Configuration → Integrations and find Jira
  2. Click Connected to reveal the disconnect option
  3. Click Disconnect
Click Connected to reveal the Disconnect option
Disconnecting Rootly does not remove the webhook from Jira. To stop Jira from sending events, you must also delete the webhook in Jira under Settings → System → WebHooks.