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 and raw destination in src/integrations/linear/sources/issues.ts to select fields and configure the table. config.ts supplies source identity and timestamp selection; pipeline.ts groups resource streams in one installation pipeline, and client.ts handles authenticated requests. The default pipeline and table exports remain in index.ts.

createLinearPipeline(config, deps) binds configuration and injectable HTTP dependencies. The example currently exposes the issues resource; add supported resource types as independent streams with their own progress. Destination schemas stay in their source modules rather than runtime configuration.

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. paginate owns retries and continuation cycle detection for each connection; all accessible comment pages are fetched before their issue is published, retaining the provider connection shape and terminal pageInfo. 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.
Use paginate for issue and comment connections, with one executor retry boundary per HTTP request and validation of provider continuations.
Separate editable source configuration, injectable HTTP client, resource reader, and pipeline wiring; test configuration binding and isolated installation checkpoints.

Version 0.1.0

Introduce raw GraphQL issue ingestion.