Linear Integration

Pilot monitors your Linear workspace for issues with a specific label and automatically implements them, creating pull requests and posting status updates back to Linear.

Setup

1. Create a Linear API Key

1. Go to Linear → Settings → API → Personal API keys
2. Click Create key
3. Copy the key — you won’t see it again

2. Find Your Team ID

Your team ID is the short prefix on your issues (e.g., APP for APP-42).

3. Configure Pilot

Add the Linear section to your config file:

# ~/.pilot/config.yaml
linear:
  enabled: true
  workspaces:
    - name: my-team
      api_key: ${LINEAR_API_KEY}
      team_id: APP
      pilot_label: pilot
      auto_assign: true

4. Create the pilot Label in Linear

In your Linear workspace, create a label called pilot (or whatever you set in pilot_label). Pilot also uses these status labels automatically:

Configuration

Multi-Workspace Setup

Pilot can monitor multiple Linear workspaces simultaneously. Each workspace has its own API key, team, and label configuration:

linear:
  enabled: true
  polling:
    enabled: true
    interval: 30s
  workspaces:
    - name: frontend
      api_key: ${LINEAR_API_KEY_FRONTEND}
      team_id: FE
      pilot_label: pilot
      project_ids:
        - "project-uuid-1"
      projects:
        - web-app
      auto_assign: true
 
    - name: backend
      api_key: ${LINEAR_API_KEY_BACKEND}
      team_id: BE
      pilot_label: pilot
      projects:
        - api-server
      auto_assign: false
      polling:
        enabled: true
        interval: 60s

Configuration Reference

Workspace Fields

Legacy Single-Workspace Config

For backward compatibility, you can use the flat configuration format:

linear:
  enabled: true
  api_key: ${LINEAR_API_KEY}
  team_id: APP
  pilot_label: pilot
  project_ids:
    - "project-uuid-1"
  auto_assign: true
  polling:
    enabled: true
    interval: 30s

This is internally converted to a single workspace named "default".

Polling

When polling is enabled, Pilot periodically queries Linear for issues matching:

• Team: matches the configured team_id
• Label: has the pilot_label (default: pilot)
• State: is in backlog, unstarted, or started

Issues are processed oldest-first (by creation date). Each workspace can override the polling interval.

Project Filtering

If project_ids is set, only issues belonging to those Linear projects are picked up. Issues without a project are skipped.

Webhooks

Pilot also supports real-time issue detection via Linear webhooks.

Setting Up Webhooks

1. Configure your webhook URL in Linear: Settings → API → Webhooks
2. Set the URL to your Pilot instance: https://your-pilot.example.com/webhooks/linear
3. Select Issues as the resource type

Supported Events

Multi-Workspace Webhook Routing

When using multiple workspaces, Pilot routes incoming webhooks to the correct workspace handler based on the team.id field in the payload. If the team ID is missing, Pilot falls back to trying each workspace handler in sequence.

Issue States and Priority

State Types

Pilot filters issues by state type during polling:

Priority Levels

Linear priorities map directly to Pilot’s priority system:

Status Notifications

Pilot posts comments on Linear issues as it works:

Project Mapping

There are two ways to map Linear projects to Pilot projects: project-level (recommended) and workspace-level (legacy).

Project-Level Mapping (Recommended)

Map each Pilot project directly to its Linear project using linear.project_id in the project config. This gives deterministic 1-to-1 mapping:

projects:
  - name: aso-generator
    path: ~/Projects/aso-generator
    github:
      owner: my-org
      repo: aso-generator
    linear:
      project_id: "linear-project-uuid-abc"
 
  - name: pilot
    path: ~/Projects/pilot
    github:
      owner: my-org
      repo: pilot
    linear:
      project_id: "linear-project-uuid-def"

When a Linear issue belongs to linear-project-uuid-abc, Pilot resolves it to the aso-generator project directly.

Workspace-Level Mapping (Legacy)

You can also map at the workspace level using project_ids and projects arrays:

workspaces:
  - name: appbooster
    team_id: APP
    project_ids:
      - "linear-project-uuid-abc"
      - "linear-project-uuid-def"
    projects:
      - aso-generator
      - pilot

If only one Pilot project is mapped, all issues from that workspace use it.

Autopilot Integration (v2.10.0)

When Pilot creates a PR from a Linear issue, the autopilot controller automatically monitors CI status and can auto-merge the PR — the same pipeline that GitHub issues get.

This is powered by the OnPRCreated callback on the Linear poller. After a successful execution produces a PR, the callback fires and hands off to autopilot for CI monitoring, status checks, and optional auto-merge. The callback only fires on successful execution — failed tasks do not trigger it.

Processed Issue Persistence (v2.10.0)

The Linear poller uses a ProcessedStore to persist which issues have already been handled. This prevents re-dispatching issues after a restart or hot upgrade.

The store is backed by SQLite (the same memory backend used by the rest of Pilot) and is enabled automatically — no configuration required.

Resolution Precedence

When an issue arrives, Pilot resolves the target project in this order:

1. Project-level linear.project_id — exact match on issue’s Linear project ID
2. Workspace-level project_ids / projects — workspace-scoped mapping
3. Generic matching — match by Linear project name or team key
4. Default project — first configured project as fallback