feat: Linear Integration

[research-developer]

Overview

Add Linear issue tracking integration for PR ↔ Issue correlation.

Webhook Support ✅

Linear has robust webhook support:

Events

• Issue: create, update, remove
• Comment: create, update, remove
• Project, Cycle, Label changes

Identification

• Header: Linear-Signature (HMAC)
• Header: Linear-Event (event type)
• Payload: Contains type, action, data, webhookId

Payload Structure

{
  "action": "create",
  "type": "Issue",
  "data": {
    "id": "issue_uuid",
    "identifier": "ENG-123",
    "title": "Fix authentication bug",
    "url": "https://linear.app/team/issue/ENG-123",
    "state": { "name": "In Progress" },
    "assignee": { "name": "John" }
  },
  "webhookId": "webhook_uuid"
}

GitHub ↔ Linear Correlation

Linear auto-links via:

• Branch names: eng-123-fix-auth-bug
• PR descriptions: "Fixes ENG-123" or "Linear: ENG-123"
• Magic words: fixes, closes, resolves

Polling Alternative

GraphQL API for queries:

• Query issues, comments, projects
• Filter by updatedAt for incremental sync

Tasks

• Implement LinearPoller in polling/linear.py
• Add Linear webhook handler
• Auto-link PRs to Linear issues via branch name
• Sync PR status → Linear issue status
• Comment on Linear when PR is merged

Use Cases

1. Auto-Transition: Move Linear issue to "In Review" when PR opens
2. PR Links: Auto-add Linear issue link to PR description
3. Status Sync: Close Linear issue when PR merges
4. Comment Sync: Mirror PR review comments to Linear