Linear Adapter

The Linear adapter connects Sortie to Linear over a single GraphQL endpoint, POST https://api.linear.app/graphql. It is registered under kind "linear", fetches issues with Relay cursor pagination, and normalizes responses to the domain Issue and Comment types. Linear is a GraphQL API and reports application errors inside HTTP 200 bodies, so the adapter classifies a response by its top-level errors array before the HTTP status, unlike the REST trackers. The canonical API documentation is Linear Developers: GraphQL.

See also: WORKFLOW.md configuration for the full tracker schema, how to connect Sortie to Linear for setup instructions, error reference for all tracker error kinds, environment variables for $VAR expansion behavior.

Configuration

The adapter reads its configuration from the tracker section of the WORKFLOW.md front matter. Two fields are required; the rest have defaults.

The adapter does not define an in_progress_state key. Dispatch-time transitions are a Jira and GitHub feature; the Linear config validation has no in_progress_state arm.

State names are compared case-insensitively at startup and resolved to the team’s canonical casing. active_states and terminal_states must not overlap, and handoff_state must appear in neither list. See state model.

tracker:
  kind: linear
  api_key: $SORTIE_LINEAR_API_KEY
  project: ENG
  query_filter: '{"labels": {"some": {"name": {"eq": "agent-ready"}}}}'
  active_states:
    - Backlog
    - Todo
    - In Progress
  handoff_state: In Review
  terminal_states:
    - Done
    - Canceled
    - Duplicate

api_key accepts $VAR indirection.

Authentication

The adapter authenticates with a Linear personal API key. The key is sent verbatim in the Authorization header with no Bearer prefix:

Authorization: <api_key>

The missing-prefix detail is the most common Linear integration bug. A Bearer-prefixed key returns HTTP 400 with a body message instructing the caller to remove the prefix. The adapter sends the key exactly as configured, so the value must be the bare key with no scheme and no surrounding whitespace.

Personal keys carry the lin_api_ prefix. Linear participates in GitHub secret scanning: a key committed to a public GitHub repository is detected and automatically revoked. A leaked key is dead.

Fixed headers on every request:

The HTTP client has a 30-second per-request timeout. Context cancellation propagates; a cancelled context aborts the in-flight request.

Construction-time validation

The constructor runs the viewer query to classify the key before the first poll cycle. A valid key returns the acting user on HTTP 200. An invalid, missing, or revoked key returns HTTP 401 with the body message Authentication required, not authenticated, mapped to tracker_auth_error, which blocks construction.

OAuth

OAuth 2.0 is not supported. The orchestrator runs as a single headless principal, and the 24-hour OAuth access-token expiry would require a token-refresh subsystem that personal API keys make unnecessary.

State model

Every Linear workflow state carries a workspace-immutable type category. There are seven values.

States are team-scoped. Two teams can each have an “In Progress” state with different UUIDs. A team can have several states of the same type (for example, “In Review” and “QA” are both started).

Name-based mapping

The adapter maps issues by configured state name, not by type. domain.Issue.State is issue.state.name with original casing preserved. The type category does not drive selection; it serves a startup tripwire that emits a WARN when a configured active_states entry resolves to a completed, canceled, or duplicate state, or a terminal_states entry resolves to a non-terminal state.

Canonical-casing preflight

Linear’s state.name.in filter is case-sensitive. At construction the adapter fetches the team’s states once, matches each configured name case-insensitively, and caches the team’s exact casing. Fetch queries send the canonical names. A configured name that no state on the team matches fails construction with tracker_payload_error (state "<name>" not found in team "<key>"); an unknown team key fails the same way (unknown team key "<key>").

Default mapping

A new Linear team ships with six states and no triage. The verified default mapping for that layout:

active_states: [Backlog, Todo, In Progress]
terminal_states: [Done, Canceled, Duplicate]
handoff_state: In Review   # operator-added started state; not a default

Identifiers and team scoping

Linear exposes three identifier-like values per issue.

The domain ID maps to issue.id; the domain Identifier maps to issue.identifier. The issue(id:) query accepts either the UUID or the human identifier. The adapter passes the form it holds and never constructs one form from the other.

tracker.project selects the Linear team key, not a Linear project. Workflow states are team-scoped, so the state model is well-defined only relative to one team. The team key is also the identifier prefix, which mirrors the Jira adapter where project is the issue-key prefix. Linear projects are cross-team containers that do not own states or identifiers. The team filter is team: { key: { eq: "<key>" } }; no team UUID resolution is needed for reads.

Field mapping

The adapter normalizes Linear GraphQL responses to domain.Issue fields.

Candidates are sorted client-side by normalized priority ascending, then by creation time ascending. Issues with no priority sort last. The server sort hint is not trusted.

The nested labels and inverseRelations connections are capped at the first 25 nodes and are not paginated. An issue that exceeds the cap emits a WARN (nested connection truncated); the dropped nodes remain observable rather than silent.

Comment normalization

Linear returns comments newest-first. The adapter re-sorts them ascending by creation time before returning.

Blocker extraction

BlockedBy is derived from the issue’s inverseRelations. When issue A blocks issue B, the relation appears in B’s inverseRelations as { type: "blocks", issue: A }. For each node whose type equals "blocks" (compared case-insensitively after trimming), a BlockerRef is produced:

Query filter

tracker.query_filter is a raw Linear IssueFilter written as a JSON object. The adapter merges it with the team and state constraints it sets internally; Linear ANDs sibling IssueFilter fields, so the result selects issues in the configured team, in the configured states, and matching the fragment.

# Issues carrying a label named "agent-ready"
query_filter: '{"labels": {"some": {"name": {"eq": "agent-ready"}}}}'

# Issues assigned to the API key's own user
query_filter: '{"assignee": {"isMe": {"eq": true}}}'

team and state are reserved keys. The adapter sets them from tracker.project and the configured state lists. A fragment containing either top-level key is rejected at construction with tracker_payload_error (tracker.query_filter must not contain a reserved key "team"; team is checked before state). A fragment that is not valid JSON, or is not a JSON object, is rejected the same way. The adapter does not validate field names; an unknown IssueFilter field surfaces on the first poll as a Linear argument-validation error.

The filter applies to FetchCandidateIssues and FetchIssuesByStates. It does not apply to the ID-based and identifier-based state lookups (FetchIssueStatesByIDs, FetchIssueStatesByIdentifiers), which use id and number connection filters; those issues already passed filtering at dispatch time.

Pagination

Linear uses Relay-style cursor connections. Every connection exposes pageInfo { hasNextPage endCursor }. The adapter requests with after: null, then after: endCursor, until hasNextPage is false.

When a connection reports hasNextPage: true but an empty or absent endCursor, the adapter returns tracker_missing_end_cursor rather than treating pagination as complete. Silent truncation would be a data-loss bug.

Rate limiting

Linear enforces a request budget and a complexity budget per API key.

• Request budget: dynamic. Linear scales it by the number of paid seats in the workspace, so it is read from response headers and never hardcoded. A live single-seat workspace returned a limit of 2,500 against a documented 5,000.
• Complexity budget: 3,000,000 points per hour, with a 10,000-point single-query cap. The production candidate query measures about 95 points.

Linear returns these headers on every response. Reset values are epoch milliseconds.

The adapter inspects x-ratelimit-requests-remaining, x-ratelimit-requests-reset, and Retry-After. It emits a WARN (rate limit exhausted) naming the reset time when x-ratelimit-requests-remaining reaches 0. It does not throttle client-side. A rate-limited response arrives as HTTP 400 (or 429) with the body code RATELIMITED, mapped to tracker_api_error and retried with exponential backoff.

Error model

A Linear response is an error when its body carries a non-empty top-level errors array, even on HTTP 200, or when the HTTP layer itself fails. The adapter parses the body errors array first and falls back to the HTTP status only when no errors array is present. Classification keys on extensions.type; extensions.code is diagnostic only, with one exception for the rate-limit signal.

There is no dedicated not-found type or code. An error whose message begins with entity not found (case-insensitive) maps to tracker_not_found. This check runs first, before any type-based rule, because a missing entity arrives under the generic invalid input type.

Body-level classification

HTTP-status fallback

Applied when a non-2xx response carries no errors array.

A transport failure (DNS, TCP, TLS, timeout, or body-read failure) maps to tracker_transport_error. The error message carries the first error’s userPresentableMessage, falling back to its message, so operators see Linear’s own wording.

For the full error taxonomy and operator guidance, see the error reference.

Adapter registration

The adapter registers itself under kind "linear" via an init function in internal/tracker/linear. Registration metadata declares:

The orchestrator’s preflight validation uses RequiresProject and RequiresAPIKey to produce specific error messages before adapter construction. ValidateTrackerConfig runs the Linear-specific offline checks (team-key format, SORTIE_LINEAR_API_KEY hint, empty or whitespace state names, state overlap, and handoff_state collisions) without making network calls.

Key differences from the Jira and GitHub adapters

See the Jira adapter reference and the GitHub adapter reference.

Related pages

• How to connect Sortie to Linear - setup instructions with authentication, state mapping, and verification
• WORKFLOW.md configuration reference - full schema for the tracker section and all other configuration
• Error reference - all tracker error kinds with retry behavior and operator actions
• Environment variables reference - $VAR expansion modes and agent passthrough variables
• Prometheus metrics reference - sortie_tracker_requests_total and related counters
• How to write a prompt template - using .issue fields (populated by this adapter) in templates
• State machine reference - orchestration states, candidate eligibility, and how tracker state drives dispatch
• How to use the file adapter for local testing - test prompts and hooks without Linear API credentials
• Dashboard reference - live monitoring of issues fetched by this adapter