Smart Defaults
Custom Workflows
Field Mapping
Action Items → Subtasks
How It Works
Connect Jira
Configure Automation
Incident Declared
Updates Flow Both Ways
Before You Begin
Required Jira Permissions
The Jira account you use to install must have these permissions:Required OAuth Scopes
Rootly requests these OAuth scopes during installation:View all 28 OAuth scopes
View all 28 OAuth scopes
read:application-role:jiraread:avatar:jiraread:field-configuration:jiraread:group:jiraread:issue:jiraread:issue-status:jiraread:issue-meta:jiraread:issue-security-level:jiraread:issue-type:jiraread:issue-type-hierarchy:jiraread:issue.changelog:jiraread:issue.transition:jiraread:issue.vote:jiraread:priority:jiraread:project:jiraread:project-category:jiraread:project-version:jiraread:project.component:jiraread:project.property:jiraread:status:jiraread:user:jiraread:user.property:jira
write:attachment:jirawrite:comment:jirawrite:comment.property:jirawrite:issue:jirawrite: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.Go to Settings → Integrations

Find Jira Cloud and click Setup

Authorize in Jira


Installation complete

Installing Additional Instances
If your organization uses multiple Jira Cloud instances, you can connect them separately.company.atlassian.net). You can have multiple projects within one instance — most organizations have a single instance with multiple projects.- Go to Integrations and search for Jira Cloud
- Click Set up another instance
- Follow the same 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.Open Jira Webhooks


Create a new webhook

Configure the webhook

Add the Rootly webhook URL


Filter by project (optional)

Select events

Keep request body enabled

Save the webhook


Verify Installation
Once connected, confirm the integration is working end-to-end:- Check integration status — The Jira tile in Rootly should show Connected.
- Test Rootly → Jira — Create a test incident and verify that a Jira issue is created in the expected project.
- Test Jira → Rootly — Create or update a Jira issue, then check the Alerts page in Rootly to confirm the event arrived.
Workflows
Smart Defaults
Custom Workflow
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.Webhook
Webhook

Jira Ticket for Incidents
Jira Ticket for Incidents

{{ incident.title }}. Supports Liquid syntax.{{ incident.summary }}. Supports Liquid syntax.Jira Ticket for Action Items
Jira Ticket for Action Items

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.Create a new workflow



Configure triggers

Add conditions

- 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
Add a Jira action


Create Jira Issue
Creates a new Jira issue for an incident or retrospective.
{{ incident.title }}).{{ incident.summary }}).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.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.Name and save the workflow
Action Reference
Create Jira Issue
Create Jira Issue

{{ incident.title }}).{{ incident.summary }}).Update Jira Issue
Update Jira Issue
{{ incident.jira_issue_id }}.
{{ incident.jira_issue_id }} to dynamically target the issue linked to the current incident.Create Jira Subtask
Create Jira Subtask

{{ incident.jira_issue_id }} to link the subtask to the current incident’s issue.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.Labels (Native Jira Field)
Labels (Native Jira Field)
customfield_12345 with your actual Jira field ID. Find field IDs in Jira Settings → Issues → Custom Fields.Team (Native Jira Field)
Team (Native Jira Field)
Custom Fields Mapping
The Custom Fields Mapping section lets you map Rootly incident data to Jira custom fields dynamically.
What You Need
Field Type Mappings
Text and Paragraph Fields
Text and Paragraph Fields
Single Select Fields
Single Select Fields
{ "value": ... } wrapper required by Jira:Multi-Select Fields
Multi-Select Fields
Labels Fields (Custom)
Labels Fields (Custom)
Number Fields
Number Fields
Date/Time Fields
Date/Time Fields
User Fields
User Fields
How to Test Your Mapping
- Create a test incident in Rootly
- Run your workflow manually
- Check the Jira issue to verify fields are populated correctly
- 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.set, add, and remove.When to Use API Payload
API Payload Examples
Set Priority Based on Severity
Set Priority Based on Severity
Add Comments
Add Comments
Link Issues Together
Link Issues Together
Set Native Labels Field
Set Native Labels Field
Set Components Field
Set Components Field
API Payload Verbs
Best Practices
- Name workflows clearly. Use names like
Create Bug on High-Priority IncidentorUpdate Jira Issue on Resolutionso 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
- Jira sends events to Rootly via webhook
- Events appear as alerts on Rootly’s Alerts page
- Alert workflows process these events and create or update incidents
Create an Alert Workflow
Create a new workflow
Set the trigger
Add conditions
- Set Source equals
Jira - Use label filters to narrow by event type or project:
event:jira:issue_created— responds to new Jira issuesevent:jira:issue_updated— responds to Jira issue updatesproject_key:YOUR_PROJECT— (optional) limits to a specific Jira project
$.issue.fields.issuetype.name). You can preview your syntax using the JSON Path Explorer.Add an action
Sync Actions
- Create Incident
- Update Incident
{{ alert.data.* }} to reference Jira fields when populating incident properties:Field Mapping Examples
Use Custom Field Mapping to dynamically set incident properties from Jira data.Set Severity from Jira Priority
Set Severity from Jira Priority
Set Status from Jira Status
Set Status from Jira Status
in_triage, active, resolved, closed, cancelledSet Custom Field (Hardcoded)
Set Custom Field (Hardcoded)
form_field_id with your actual field ID.Set Custom Field (From Jira)
Set Custom Field (From Jira)
Set Multi-Select Custom Field
Set Multi-Select Custom Field
selected_option_ids instead of value.Troubleshooting
Jira integration not appearing after OAuth
Jira integration not appearing after OAuth
- 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
Rootly cannot access Jira projects
Rootly cannot access Jira projects
- 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 creation fails
Issue creation fails
- 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
Webhook events not appearing in Rootly
Webhook events not appearing in Rootly
- 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
Uninstall
To remove the Jira integration:- Go to Settings → Integrations and find Jira
- Click Connected to reveal the disconnect option
- Click Disconnect
