Linear Integration Overview

The Linear integration enables seamless bidirectional synchronization between PagerDuty incidents and Linear issues. Automatically create incidents when critical issues arise and keep both systems in sync throughout the incident lifecycle.

What You Can Do

Automatic Incident Creation

Create PagerDuty incidents automatically when Linear issues match your configured rules. You have complete control over which issues trigger incidents based on:

Priority - Urgent, High, Medium, Low, or No Priority
Status - Triage, Backlog, Todo, In Progress, etc.
Team - Specific Linear teams
Projects - Specific projects within Linear teams
Labels - Any Linear labels

Projects

Linear organizes work into projects within teams. Integration Hub allows you to filter which projects trigger PagerDuty incidents, giving you precise control over incident creation:

Monitor Specific Projects: Only create incidents for production-related projects
Exclude Internal Work: Filter out internal tooling or feature work projects
Route by Project Type: Send different projects to different PagerDuty services
Team Organization: Each team's projects are independently configurable

Example: Your Engineering team has three projects: "Production Bugs," "Feature Development," and "Internal Tools." You can create a rule that only monitors the "Production Bugs" project with Urgent priority, ensuring only critical production issues create incidents.

Labels

Labels are powerful cross-cutting filters that work across all projects within a team. Use labels to identify issues that require immediate escalation regardless of project:

Severity Labels: "Critical," "High-Impact," "Outage," "Data Loss"
Environment Labels: "Production," "Staging," "Development"
Type Labels: "Security," "Performance," "Bug," "Incident"
Customer Impact: "Customer-Reported," "Revenue-Impact"

Pro Tip: Combine labels with priority for powerful filtering. For example, create a rule that monitors Urgent OR High priority issues with the "Production" label. This catches all critical production issues regardless of which project they belong to.

Label Best Practices:

Establish consistent label standards across your Linear workspace
Document when to use each label
Use descriptive label names (e.g., "Production" instead of "Prod")
Combine labels with projects for precise filtering
Review and clean up unused labels periodically

Bidirectional Status Sync

Changes in PagerDuty automatically update Linear and vice versa:

PagerDuty Action	Linear Update
Acknowledge Incident	Issue moves to configured status (e.g., "In Progress")
Resolve Incident	Issue moves to configured status (e.g., "Done")
Add Note	Comment added to Linear issue

Linear Action	PagerDuty Update
Mark as "Done" (completed)	Incident automatically resolved
Mark as "Canceled"	Incident automatically resolved

Note: Only Linear status types "completed" and "canceled" will resolve PagerDuty incidents. Moving an issue to "In Progress" or other non-terminal states will NOT resolve the incident.

Comment Synchronization

Notes added to PagerDuty incidents automatically sync to Linear as comments, keeping your team informed regardless of which tool they're using.

How It Works

1. Connect Your Accounts

OAuth connections to both PagerDuty and Linear ensure secure, authorized access.

2. Create Webhooks

Set up webhooks for each Linear team you want to monitor. Webhooks enable real-time updates when issues change in Linear.

Important: Create one webhook per Linear team. This ensures you receive updates only from teams you care about and helps organize your integration.

3. Configure Rules

Define exactly when PagerDuty incidents should be created by configuring rules with:

Linear webhook (team)
Issue priorities to monitor
Issue status types to monitor
Projects to monitor (optional - filter by specific projects)
Labels to monitor (optional - filter by specific labels)
PagerDuty service to create incidents in
Incident urgency (high or low)
Status mapping for bidirectional sync

4. Automatic Synchronization

Once configured, Integration Hub automatically handles all synchronization in real-time.

Use Cases

Production Incidents

Scenario: Your engineering team files critical bugs in Linear with "Urgent" priority.

Solution: Configure a rule to create PagerDuty incidents for all Urgent issues, automatically paging your on-call responders.

Rule: "Critical Production Issues"
Webhook: Engineering Team
Priorities: Urgent
Status Types: Triage, Started
Projects: "Production Bugs"
Labels: "Bug", "Outage"
Service: Production On-Call
Urgency: High
Acknowledged Status: In Progress
Resolved Status: Done

Customer-Reported Issues

Scenario: Support team creates High priority issues for customer-impacting problems.

Solution: Create incidents for High priority support issues to ensure quick response.

Infrastructure Monitoring

Scenario: Platform team tracks infrastructure issues in Linear.

Solution: Page on-call engineers when infrastructure issues reach Urgent or High priority.

Key Benefits

Reduced Manual Work - No more copying issue details between tools
Faster Response - Critical issues automatically escalate to on-call
Single Source of Truth - Status always synchronized between systems
Better Visibility - All team members see updates regardless of tool preference
Flexible Configuration - Rules adapt to your team's workflow

Next Steps

Ready to set up the Linear integration?

Need Help?

Check out our guides:

Best Practices - Proven configuration strategies
Troubleshooting - Common issues and solutions
Bidirectional Sync Details - Deep dive into how sync works