Linear Integration

Linear Integration

Connect Linear to search issues, projects, and roadmaps across your workspace.

What You Can Query

Content Type	Description
Issues	Tasks, bugs, features
Projects	Initiatives, epics
Comments	Discussion threads
Cycles	Sprint/iteration content
Roadmaps	Planning content

Connecting Linear

1. Log into TeamLoop at app.teamloop.io
2. Navigate to Settings > Integrations
3. Click Connect next to Linear
4. Authorize TeamLoop to access your workspace
5. Select which teams to include

Permissions

TeamLoop requests read-only access to:

• Issues and comments
• Projects and milestones
• Team metadata
• User information

We never modify your Linear workspace.

Example Queries

Search Issues

teamloop_query:
  query: "authentication bug"
  sources: "linear"

Find Project Context

teamloop_query:
  query: "mobile app redesign"
  sources: "linear"

Search Roadmap Items

teamloop_query:
  query: "Q1 2025 roadmap priorities"
  sources: "linear"

Automatic Change Tracking

TeamLoop automatically tracks Linear issue changes:

Issue Timeline

When you query an issue, TeamLoop fetches its history:

• Status changes (Backlog → In Progress → Done)
• Priority changes
• Assignee changes
• Label changes
• Estimate changes

These become CHANGE entities:

CHANGE: "ENG-123: Status changed to In Progress"
  └── PART_OF → DOCUMENT: "ENG-123: Implement OAuth flow"

CHANGE: "ENG-123: Priority changed to High"
  └── PART_OF → DOCUMENT: "ENG-123: Implement OAuth flow"

Workflow Visibility

Track how work progresses:

teamloop_timeline:
  entity_id: "uuid-of-linear-issue"

Shows:

• When work started
• Status transitions
• Blockers and unblocks
• Assignment changes

Entity Extraction

Linear content maps to TeamLoop entity types:

Linear Content	TeamLoop Entity
Issue	DOCUMENT
Project	PROJECT
Comment	DOCUMENT
Status change	CHANGE
Assignee	PERSON

Example Extraction

From a Linear issue:

{
  "entities": [
    {
      "type": "DOCUMENT",
      "name": "ENG-456: Migrate to PostgreSQL",
      "description": "Move user service from MySQL to PostgreSQL",
      "source_url": "https://linear.app/team/issue/ENG-456",
      "source_integration": "linear",
      "source_external_id": "ENG-456",
      "event_date": "2024-05-10"
    },
    {
      "type": "PROJECT",
      "name": "Database Migration",
      "description": "Q2 initiative to modernize data layer",
      "status": "active"
    },
    {
      "type": "DECISION",
      "name": "Choose PostgreSQL over MySQL",
      "rationale": "Need JSONB support for flexible schemas",
      "event_date": "2024-05-12"
    }
  ],
  "relationships": [
    {
      "source_name": "ENG-456: Migrate to PostgreSQL",
      "source_type": "DOCUMENT",
      "target_name": "Database Migration",
      "target_type": "PROJECT",
      "relationship_type": "PART_OF"
    }
  ]
}

Best Practices

1. Use Projects for Context

Linear projects provide valuable context:

teamloop_query:
  query: "project:auth-migration"
  sources: "linear"

2. Extract Decisions from Issues

Many Linear issues contain implicit decisions:

{
  "type": "DECISION",
  "name": "Use React Query for data fetching",
  "description": "Decided in ENG-789",
  "source_url": "https://linear.app/team/issue/ENG-789"
}

3. Track Status Changes

Use temporal queries to understand work patterns:

teamloop_evolution:
  query: "authentication issues"
  from_date: "2024-01-01"
  to_date: "2024-03-31"

4. Link to GitHub

Many Linear issues link to PRs. TeamLoop can track both:

teamloop_query:
  query: "ENG-456 authentication"
  sources: "linear,github"

Temporal Queries with Linear

Point-in-Time

What was the project status on a date:

teamloop_query:
  query: "auth project"
  sources: "linear"
  mode: "as_of"
  as_of: "2024-06-01"

Sprint/Cycle History

Track how a cycle progressed:

teamloop_evolution:
  query: "cycle:2024-W45"
  from_date: "2024-11-04"
  to_date: "2024-11-08"

Compare Sprints

teamloop_compare:
  query: "sprint velocity"
  date_a: "2024-10-01"
  date_b: "2024-11-01"

Troubleshooting

No Results

• Verify Linear integration is connected
• Check team access permissions
• Ensure issues aren’t in private teams
• Try broader search terms

Missing Issues

• Check if issues are in connected teams
• Verify your Linear role has access
• Re-authorize if team membership changed

Stale Data

Linear data is fetched fresh and cached:

• Cache TTL: 7 days
• Re-query for fresh data
• Status changes may take a moment to reflect

Search Tips

By Team

teamloop_query:
  query: "team:engineering authentication"
  sources: "linear"

By Status

teamloop_query:
  query: "status:In Progress authentication"
  sources: "linear"

By Priority

teamloop_query:
  query: "priority:urgent security"
  sources: "linear"

By Label

teamloop_query:
  query: "label:bug label:critical"
  sources: "linear"

Security

• OAuth tokens are encrypted at rest
• Only accesses teams you authorize
• You can revoke from Linear settings
• TeamLoop never writes to Linear

Rate Limits

TeamLoop respects Linear’s API limits:

• Optimized queries to minimize calls
• Cached results reduce API usage
• Graceful handling of rate limit responses

Next Steps

• GitHub Integration - Connect GitHub
• Notion Integration - Connect Notion
• Query Playground - Learn query modes