Linear Integration Guide

Complete guide to integrating MSP with Linear for seamless project management and context-aware issue tracking. Transform Linear from a task list into a knowledge-rich development hub.

Why Linear + MSP?

Linear excels at issue tracking, but lacks context. MSP bridges this gap by:

Auto-updating issues with session progress
Linking decisions to specific tasks
Tracking blockers in real-time
Generating reports from actual work done
Creating issues from session insights

Quick Setup

1. Get Your Linear API Key

# In Linear: Settings → API → Create new API key
# Set the key in MSP
msp config set linear.apiKey "lin_api_xxxxxxxxxxxxxxxx"

2. Configure Team and Project

# Find your team ID
msp linear teams list

# Set default team
msp config set linear.teamId "your-team-id"

# Find project ID
msp linear projects list

# Set default project
msp config set linear.projectId "your-project-id"

3. Test Integration

# Verify connection
msp linear test

# Should return:
# ✅ Connected to Linear
# ✅ Team: Your Team Name
# ✅ Project: Your Project Name

Core Integration Features

Session-Issue Linking

# Start session linked to Linear issue
msp start --linear "ENG-123"

# This automatically:
# - Adds session start comment
# - Updates issue status to "In Progress"
# - Links all session data to issue

Automatic Progress Updates

# Progress updates sync to Linear
msp update "Implemented user authentication" 25

# Creates Linear comment:
# 🔄 Progress Update (25%)
# Implemented user authentication
# Session: msp-2025-07-15-093042

Decision Tracking

# Decisions appear in Linear
msp decide "Using JWT for stateless auth"

# Creates Linear comment:
# 💡 Decision Made
# Using JWT for stateless auth
# View in knowledge graph: [link]

Blocker Reporting

# Blockers create Linear sub-issues
msp blocker "CORS policy preventing API calls"

# Creates:
# - Sub-issue under current issue
# - Links to session context
# - Assigns to you
# - Labels as "blocker"

Advanced Linear Workflows

Epic Management

# .msp/linear-mapping.yaml
epics:
  "User Authentication":
    linearId: "ENG-EPIC-001"
    progressField: "custom.progress"
    milestones:
      - 10: "Architecture defined"
      - 25: "Basic auth working"
      - 50: "OAuth integration"
      - 75: "Testing complete"
      - 100: "Deployed to production"

# Update epic progress
msp epic update "User Authentication" 25
# Updates custom field in Linear
# Posts milestone achievement

Smart Issue Creation

# Create issue from session context
msp linear create --from-session

# Generates issue with:
# - Title from current work
# - Description with full context
# - Labels based on session tags
# - Links to related issues
# - Assigns to session user

Bulk Operations

# Update all related issues
msp linear bulk-update --session "msp-2025-07-15" --status "Done"

# Close issues mentioned in session
msp linear close-mentioned --session "today"

# Create follow-up issues from blockers
msp linear create-from-blockers --auto-assign

Linear Labels Configuration

Recommended Label Structure

labels:
  # Session types
  msp-session: "Session tracked by MSP"
  msp-decision: "Architectural decision"
  msp-blocker: "Blocking issue"
  
  # Progress indicators
  msp-0-25: "Early stage (0-25%)"
  msp-25-50: "In development (25-50%)"
  msp-50-75: "Testing phase (50-75%)"
  msp-75-100: "Finalizing (75-100%)"
  
  # Context tags
  msp-has-context: "Full context available"
  msp-needs-context: "Context needed"

# Auto-create MSP labels
msp linear setup-labels

# Apply labels based on progress
msp linear label-by-progress

Custom Fields Integration

Setting Up Progress Field

In Linear: Settings → Custom Fields
Create field "MSP Progress" (Number type)
Configure in MSP:

msp config set linear.customFields.progress "msp-progress-field-id"

Session Metadata Fields

customFields:
  mspSessionId: "text"
  mspProgress: "number" 
  mspLastUpdate: "date"
  mspDecisionCount: "number"
  mspContextLink: "url"

Automation Rules

Linear Automations for MSP

# When issue moves to "In Progress"
trigger: 
  - status changes to "In Progress"
action:
  - Add label "msp-session"
  - Post comment: "Remember to start MSP session: msp start --linear {{issue.identifier}}"

# When issue has no updates for 2 days
trigger:
  - No activity for 48 hours
  - Has label "msp-session"
action:
  - Add label "msp-needs-context"
  - Notify assignee

MSP Automations for Linear

# Configure auto-actions
msp linear config automation

# Available automations:
# - Auto-move to "In Progress" on session start
# - Auto-close on 100% progress
# - Create planning issues for next session
# - Generate sprint reports

Reporting and Analytics

Generate Linear Reports

# Sprint progress report
msp linear report sprint --current

# Outputs:
# Sprint Progress Report
# =====================
# Issues with sessions: 15/20 (75%)
# Total progress: 1,250%
# Decisions made: 47
# Blockers resolved: 12
# Average session duration: 3.2 hours

Velocity Tracking

# Team velocity over time
msp linear velocity --weeks 12

# Generates graph showing:
# - Story points vs MSP progress
# - Decision density
# - Blocker frequency
# - Context coverage

Custom Queries

# Find issues needing context
msp linear query "status:In Progress AND -label:msp-has-context"

# Find decisions by epic
msp linear decisions --epic "Authentication"

# Export for analysis
msp linear export --format csv --include-msp-data

Templates for Linear

Issue Templates with MSP

## 🎯 Objective
[Clear description of what needs to be done]

## 🧠 MSP Context
- **Session Command**: `msp start --linear {{issue.identifier}}`
- **Expected Progress**: 0% → ___% 
- **Decision Points**: 
  - [ ] Architecture approach
  - [ ] Technology choice
  - [ ] Implementation strategy

## ✅ Acceptance Criteria
- [ ] Tests passing
- [ ] Documentation updated
- [ ] MSP session completed with summary

## 📊 Progress Tracking
<!-- Auto-updated by MSP -->
{{msp.progress}}

## 💡 Decisions
<!-- Auto-updated by MSP -->
{{msp.decisions}}

Epic Template

# {{epic.name}}

## MSP Tracking
- **Project Code**: {{msp.projectCode}}
- **Current Progress**: {{msp.progress}}%
- **Active Sessions**: {{msp.activeSessions}}

## Milestones
{{#each msp.milestones}}
- [{{#if completed}}x{{else}} {{/if}}] {{target}}%: {{description}}
{{/each}}

## Recent Decisions
{{msp.recentDecisions limit=5}}

## Active Blockers
{{msp.activeBlockers}}

Troubleshooting

Common Issues

"Linear API key invalid"

# Regenerate and update key
msp config set linear.apiKey "new-key"
# Test connection
msp linear test

"Issue not found"

# Verify issue exists and you have access
msp linear issue get "ENG-123"
# Check team/project config
msp config show linear

"Updates not appearing"

# Check webhook configuration
msp linear webhook status
# Manually sync
msp linear sync --force

Debug Mode

# Enable Linear debug logging
msp config set linear.debug true

# View Linear API calls
msp linear debug --show-requests

# Test specific integration
msp linear test --component "comments"

Best Practices

1. Session Hygiene

Always link sessions to Linear issues
Close sessions properly for accurate data
Use descriptive update messages

2. Label Consistency

# Audit label usage
msp linear audit labels

# Fix inconsistencies
msp linear fix labels --auto

3. Progress Accuracy

Update progress in small increments
Use realistic estimates
Sync at natural breakpoints

4. Context Preservation

# Before closing issue
msp context export --linear "ENG-123" --to-docs

# Preserves all context for future reference

Integration Examples

Full Workflow Example

# Monday: Start new feature
msp start --linear "ENG-456" --epic "User Dashboard"
msp update "Created dashboard component structure" 10
msp decide "Using React Query for data fetching"
msp update "Implemented basic layout" 20

# Tuesday: Continue work
msp recall --linear "ENG-456"
msp start --continue
msp blocker "API endpoint not returning user preferences"
msp update "Added loading states" 30

# Wednesday: Resolve and progress
msp resolve-blocker "Fixed with backend team"
msp update "Connected to real API" 50
msp update "Added error handling" 60

# Thursday: Testing
msp update "Unit tests complete" 75
msp update "Integration tests passing" 85
msp decide "Defer advanced features to v2"

# Friday: Ship it
msp update "Code review complete" 95
msp update "Deployed to staging" 100
msp end --summary "User dashboard feature complete"

# This creates a complete story in Linear with:
# - Full progress timeline
# - All decisions documented
# - Blocker history
# - ~15 automatic comments
# - Updated epic progress

Team Standup Generator

# Generate standup notes from MSP + Linear
msp linear standup --yesterday

# Output:
# ## Yesterday (via MSP + Linear)
# 
# **Completed:**
# - ENG-456: User Dashboard (100%)
#   - Made 2 decisions
#   - Resolved 1 blocker
#   - 8 hours tracked
# 
# **In Progress:**
# - ENG-457: API Integration (30%)
#   - Current: Implementing webhooks
# 
# **Blockers:**
# - None active
# 
# **Today's Plan:**
# - Continue ENG-457
# - Start ENG-458 if time permits

Next Steps

Set up webhook for real-time sync
Configure automations for your workflow
Train team on MSP + Linear commands
Create custom reports for stakeholders

Linear tracks what you plan to do. MSP tracks what you actually did. Together, they tell the complete story.

Linear Integration Guide

On this page