> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Linear Integration
> Sync Rootly incidents to Linear issues for seamless issue tracking, follow-up management, and engineering context from incident response to delivery.
Rootly's Linear integration connects your incident workflow to Linear. When an incident is declared, a Linear issue is automatically created. As the incident progresses, the issue stays in sync. When resolved, the Linear issue moves to Done.
Follow-up action items become Linear sub-issues under the parent incident issue, keeping post-incident work organized in one place.
## What You Can Do
Automatically create a Linear issue when an incident is declared, with title, description, severity, and assignee populated from incident data
Every follow-up action item created during an incident becomes a Linear sub-issue under the parent incident issue
When an incident resolves in Rootly, the linked Linear issue automatically moves to Done
Connect Rootly on-call schedules to Linear's Triage Responsibility so new issues auto-assign to whoever is on call
## How It Works
An incident is created in Rootly, either manually or via an alert from PagerDuty, Datadog, or another source.
Your configured workflow fires and creates a Linear issue in the specified team and project, with fields populated from incident data.
The Linear issue URL is automatically attached to the incident in Rootly. Teams can navigate between both systems.
As the incident progresses, action items become sub-issues. When the incident resolves, the Linear issue status updates automatically.
Connecting Linear to Rootly is a one-time OAuth setup that takes a few minutes. Once complete, Rootly can create and update Linear issues on your behalf as incidents move through their lifecycle — no manual copy-pasting between tools.
## Before You Begin
This setup involves authorizing Rootly inside your Linear workspace. Make sure you have the right access in both systems before starting — the OAuth flow will fail silently if your Linear account doesn't have the correct permissions.
You need:
* **Rootly:** Admin or Owner role to create and manage integrations
* **Linear:** Membership in at least one team with write permissions — read-only roles cannot create issues
## Installation
The connection is established through Linear's OAuth flow — Rootly redirects you to Linear, you approve access, and you're brought back to Rootly with the integration active. You won't need to handle any API keys or tokens manually.
Navigate to **Configuration → Integrations** in your Rootly dashboard. This is where all third-party integrations are managed.
Search for **Linear** in the integrations catalog and click **Setup** to begin the OAuth authorization flow.
You'll be redirected to Linear's authorization page. Review the requested permissions — Rootly needs write access to create and update issues on your behalf. Click **Allow Access** to proceed.
If you belong to multiple Linear workspaces, choose the one you want to connect to Rootly and click **Authorize**. You can only connect one workspace per Rootly account.
You'll be redirected back to Rootly and see a confirmation: *"Great! We've added that Linear account to your Rootly account!"* The integration is now active.
Linear is now connected. The [workflow actions](#workflow-actions) below configure automated issue creation for your incidents.
## Verify the Connection
Once connected, it's worth confirming the integration is active on both sides before building workflows.
**In Rootly:** The integration should show **Connected** status on the Integrations page.
**In Linear:** Open your workspace menu, go to **Settings → Integrations**, and confirm Rootly appears in your connected apps list. If it's missing, the OAuth flow may not have completed successfully — try reconnecting.
Once Linear is connected, you configure workflows that automatically create and update Linear issues as incidents move through their lifecycle. This page covers the three main workflow actions — creating issues, updating them, and creating sub-issues for action items — as well as setting up Triage Responsibility to keep your Linear queue synced with whoever is on call.
## Workflow Actions
### Create a Linear Issue
This is the core workflow: whenever an incident is declared in Rootly, a corresponding Linear issue is created automatically with incident data populated into the fields you configure.
Go to **Rootly → Workflows → Create Workflow**.
Select the event type that should trigger this workflow — for example, **Incident**, **Retrospective**, or **Pulse**.
Triggers define when this workflow fires. Choose the event that should kick off Linear issue creation.
| Trigger | When It Fires |
| ------------------------------- | ---------------------------------------- |
| **Incident Created** | A new incident opens |
| **Incident Updated** | Severity, status, or other fields change |
| **Incident Commander Assigned** | Someone takes ownership of the incident |
| **Manual Trigger** | Run on demand from the Rootly UI |
Conditions let you filter which incidents trigger the workflow — for example, only SEV-1 incidents, only specific teams, or only production environments.
Click **Add Action**, search for **Linear**, and select **Create Linear Issue**.
Fill in the fields to control how the Linear issue is created:
The Linear team where the issue will be created.
The initial workflow state for the issue — for example, **Todo** or **In Progress**.
Optional. Associate the issue with a specific Linear project.
Add labels to the issue for filtering and triage.
The issue title. Supports Liquid — use `{{ incident.title }}` to default to the incident title.
The issue body. Supports Liquid — use `{{ incident.summary }}` to populate with the incident summary.
The issue priority. Select **Auto** to automatically map incident severity to a corresponding Linear priority, or choose **Urgent**, **High**, **Medium**, or **Low** manually.
Email address of the Linear user to assign the issue to.
Optional. Map Linear custom fields using JSON. Values support Liquid, so you can populate Linear fields from Rootly context — in an [action item workflow](/workflows/action-item-workflows), reference the follow-up's [custom field values](/incidents/action-items/action-item-custom-fields):
```json theme={null}
{"customFieldKey": "{{ action_item.custom_fields_by_slug.your-field-slug }}"}
```
Click **Add**, give your workflow a name, and click **Create Workflow**.
### Update a Linear Issue
Use the **Update Linear Issue** action to keep the Linear issue in sync as the incident progresses — for example, moving it to Done when the incident resolves, or updating priority when severity changes.
Create a **separate workflow** for updates. Do not add the Update action to your Create workflow — they need to trigger on different events.
Configure the action with:
Use `{{ incident.linear_issue_id }}` to reference the issue that was created when the incident was declared.
Optional. JSON mapping of Linear custom fields, with Liquid support — same format as on the Create Linear Issue action.
Common use cases:
* Move to **Done** when the incident is resolved
* Update **priority** when severity escalates
* Change **assignee** as ownership transfers
* Sync a follow-up's [custom field values](/incidents/action-items/action-item-custom-fields) into Linear custom fields (in action item workflows, via `{{ action_item.custom_fields_by_slug.your-field-slug }}`)
### Create Linear Sub-Issues
To track action items as Linear sub-issues, create a separate workflow triggered by **Action Item Created** and use the **Create Linear Sub-Issue** action.
Use `{{ incident.linear_issue_id }}` to nest the sub-issue under the parent incident issue.
Use `{{ action_item.summary }}` to populate the sub-issue title from the action item.
The Create Linear Sub-Issue action also supports the **Custom fields mapping** input described above, so sub-issues can carry the action item's [custom field values](/incidents/action-items/action-item-custom-fields) into Linear.
This keeps all follow-up work organized under the parent incident issue in Linear.
***
### Triage Responsibility
Connect Linear's [Triage Responsibility](https://linear.app/docs/triage#triage-responsibility) feature to your Rootly on-call schedules so new Linear issues are automatically assigned to whoever is currently on call. This keeps your triage queue aligned with your incident response rotation.
Go to **Schedules** and click **Create Schedule**.
In the **Integrations** tab, toggle on **Sync with Linear**.
Give the schedule a name, add members, and click **Save**.
In Linear, navigate to **Settings → Teams** and select the team you want to configure.
Under **Workflow → Triage**, find **Triage responsibility** and select **Use schedule**. Choose the Rootly schedule you just created.
New Linear issues in triage will now be automatically assigned to whoever is on call in Rootly — no manual triage queue management needed.
## Troubleshooting
Confirm you completed the OAuth flow and granted Rootly access to your workspace. In Linear, go to **Settings → Integrations** and verify Rootly is listed and enabled. If it's missing or showing an error, disconnect the integration in Rootly and reconnect from scratch — the OAuth token may have expired or been revoked.
You must be a member of at least one Linear team with write permissions — read-only roles won't allow issue creation. If your workspace uses restricted teams, a Linear admin needs to add you before you can proceed. After your permissions are updated, restart the authorization flow so Linear returns the correct team list.
***
## Uninstall
To remove the Linear integration, go to **Configuration → Integrations**, find **Linear**, and click the **Connected** button to reveal the disconnect option.
Disconnecting stops all Linear-related workflows from running. Existing Linear issues created by Rootly are not affected.