Integrating ClickHouse with Linear

The Linear registry item copies a small API reader and raw ClickHouse tables into a chkit project.

Install

bunx chkit add linear
bunx chkit check
bunx chkit generate --name add_linear
bunx chkit migrate --apply
bunx chkit ingest run --tag provider:linear

Set LINEAR_API_KEY in the runtime environment before the ingestion run. Edit the GraphQL query in src/integrations/linear/index.ts to select the fields needed by the project.

Keep each stream ID and destination tied to one workspace. The reader does not resolve the token’s workspace identity; switching workspaces requires a new stream ID and destination so the previous watermark cannot skip history. Reconcile older observations after adding requested fields.

Resource	Default ClickHouse table	Records synced	API reference
Issues (`issues`)	`linear_issues_raw`	Archived and active issues updated inside a timestamp window, with all accessible comment pages.	`POST/graphql`

Sync behavior

Issues use server-side bounded updatedAt windows, Relay cursors, five minutes of overlap, and explicit archive inclusion. All accessible comment pages are fetched before their issue is published. The timestamp checkpoint advances only after the whole window and destination writes succeed, including an empty window; failed windows replay from their lower bound. Linear pagination and date filtering document the selection controls.

Deleted issues remain stored. Comment-only changes are not assumed to update the parent issue timestamp; use periodic reconciliation or a durable webhook companion to refresh old discussions. The API does not provide an atomic snapshot guarantee.

bunx chkit ingest run --tag provider:linear --backfill reconcile-2026-10-04 --from 1970-01-01
bunx chkit ingest status --tag provider:linear --json

Historical replay reads current issue observations, not historical versions. Use a new backfill ID for each full reconciliation. The raw tables preserve provider fields and require ClickHouse 25.3 or later. See the installed README for configuration and registry installation.

Test the reader

bunx chkit add linear --with-tests
bun test src/integrations/linear/tests/basic.test.ts

Changelog

Version 0.2.0

Sync issues through overlapping updated-time windows, explicitly including archived issues.
Collect all accessible comment pages and advance the watermark only after the complete window reaches the destination.
Replay failed windows safely and include fixtures for bounded queries, pagination, empty windows, and destination failures.

Version 0.1.0

Introduce raw GraphQL issue ingestion.