Linear Connector

The Linear connector syncs issues, comments, and projects from your Linear workspace into CortexDB. Issues are stored as issue episodes with full status, priority, assignee, and label metadata. Comments become comment episodes threaded to their parent issue. Projects are ingested as document episodes.

Setup

1. Create a Linear API Key

1. Go to linear.app/settings/api
2. Click Create key
3. Name the key (e.g. CortexDB Sync)
4. Copy the generated API key

Alternatively, use OAuth for team-wide access:

1. Create an OAuth application in Linear settings
2. Complete the OAuth flow to obtain an access token

2. Configure the Connector

# Required
CORTEX_LINEAR_API_KEY=lin_api_your_key_here

# Optional: scope to specific teams
CORTEX_LINEAR_TEAM_IDS=team-id-1,team-id-2

# CortexDB target
CORTEX_LINEAR_TENANT_ID=my-app
CORTEX_LINEAR_NAMESPACE=linear

3. Start the Connector

# As part of CortexDB
docker run -d \
  -e CORTEX_LINEAR_API_KEY=lin_api_... \
  -e CORTEX_LINEAR_TEAM_IDS="team-id-1,team-id-2" \
  -e CORTEX_LINEAR_TENANT_ID=my-app \
  cortexdb/cortexdb:latest \
  --enable-connector linear

# As a standalone process
cortexdb-connector linear \
  --api-key lin_api_... \
  --team-ids "team-id-1,team-id-2" \
  --tenant-id my-app

What Gets Ingested

| Linear Event | Episode Type | Content | |---|---|---| | Issue created/updated | issue | Issue identifier + title + description | | Issue comment | comment | Comment body (Markdown) | | Project created/updated | document | Project name + description | | Status change | issue | Updated issue with new state metadata |

Episode Metadata

Each ingested issue includes:

{
  "type": "issue",
  "content": "[ENG-423] Migrate auth service to mTLS\n\nWe need to upgrade the auth service...",
  "source": "linear",
  "author": "alice",
  "timestamp": "2026-03-15T11:45:00Z",
  "metadata": {
    "identifier": "ENG-423",
    "state": "In Progress",
    "state_type": "started",
    "priority": 2,
    "priority_label": "High",
    "estimate": 5,
    "cycle_name": "Sprint 12",
    "cycle_number": 12,
    "project_name": "Infrastructure Hardening",
    "url": "https://linear.app/myteam/issue/ENG-423"
  }
}

Configuration

| Variable | Default | Description | |---|---|---| | CORTEX_LINEAR_API_KEY | Required | Linear API key or OAuth token | | CORTEX_LINEAR_TEAM_IDS | All teams | Comma-separated team IDs to sync | | CORTEX_LINEAR_TENANT_ID | Required | Target tenant | | CORTEX_LINEAR_NAMESPACE | linear | Target namespace | | CORTEX_LINEAR_BACKFILL_DAYS | 30 | Days of history to backfill on first run |

Backfill

On first run, the connector backfills the configured number of days of history by querying issues and projects with an updatedAt filter. Comments are fetched for every discovered issue. Subsequent runs process only items modified since the last sync.

# Backfill 90 days of history
cortexdb-connector linear --backfill-days 90

The connector uses Linear's GraphQL filter parameter with updatedAt >= cutoff for efficient incremental sync. Idempotency keys include the issue's updatedAt timestamp, so re-syncing the same issue version is safely deduplicated.