Skip to content

feat(source): read and search Linear issues through the issue endpoints - #35666

Merged
bolichen97 merged 2 commits into
mainfrom
feat/source-issues-linear
Nov 12, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/source-issues-linear

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: App pages can read a Linear issue and list or search one Linear team's issues through the same endpoints they already use for GitHub, GitLab and Jira.

POST /api/source/issues serves GitHub and GitLab and answers provider_not_supported for Linear. POST /api/source/issue cannot read a Linear issue at all, so the app-SDK issue components (useIssues, IssueList, IssueCard) have nothing to show for teams that track work in Linear.

Why it matters

Linear is one of the issue trackers the issue components are meant to cover. Without it, a team on Linear gets an error where other teams get their issue list.

Not a goal

  • Writing to Linear (create, edit, comment, transition). This is read-only.
  • Jira search, which is a separate PR; Jira still answers provider_not_supported on /api/source/issues.
  • OAuth or any sign-in flow. The key is a personal API key the operator stores in the vault.
  • A dashboard surface. This is API only, as the rest of issue search is today.

What changed (motivation → approach → change)

Linear has no CLI, so unlike GitHub and GitLab the gateway calls Linear's GraphQL API itself, authenticated with a personal API key.

  • New owner source_providers/linear.py. It reads the key from Crew's vault as LINEAR_API_KEY on each request (vault only, never .env, so it never enters the process environment a child could inherit). The key goes only in the Authorization header and is never logged or returned. A missing key answers a fixed "add a Linear API key" error before any network call; every other error is the module's own fixed text, never Linear's.
  • Constant queries, values as variables. Every GraphQL document is a constant; request values travel only as GraphQL variables. The shared filters (state, assignee including me, labels, text, sort, paging) map onto an IssueFilter.
  • Team scope cannot be widened. The search filter is always {"and": [<team clause>, ...]}, and raw (a Linear IssueFilter JSON object) is validated and placed inside that and. Any row whose team is not the requested team is dropped anyway.
  • Paging. The shared numeric page contract is kept by walking Linear's cursor pages, capped at the same 1,000-result window GitHub search uses; the last page inside the window asks only for the rows left in it.
  • Single issue. A Linear issue URL on /api/source/issue resolves to one ref (links.py, which splits the URL path with PurePosixPath like its repository-URL parser and refuses a path with an empty or . segment) and is normalized to the shared issue shape. An issue whose own URL is in another workspace than the link's is refused. A bare-key form ({provider: "linear", key}) was dropped per the First Principles review: no caller has a key without a URL, and every search row carries its url.
  • Install, not import. cache and issue_search are listed before linear in the owner import order, so they cannot import it. Instead linear installs itself on import through two small hooks, cache.install_issue_reader and issue_search.install_provider; the handler lists linear in _OWNED_NAMES so it is imported and covered by the import-order checks. Single-issue reads go through cache's existing redaction, byte cap and cache, and search excerpts through cache.search_issues, the same as the other providers.
  • issue_search.py changes only by removing linear from _PLANNED_PROVIDERS and adding install_provider, to keep the overlap with the parallel Jira search PR small. plugins.py reserves linear as a built-in provider id.
  • No regex in the new code. No Sensitive Change Review watched file is touched.
  • Docs: docs/app-kit/api-reference.md (the issue-search and issue-read API reference), the request type comments in website/src/types/index.sources.ts and the Issue search row in docs/feature-map/README.md now name Linear.

Backwards compatibility

Compatible: Linear requests that answered provider_not_supported now get served; every request that works today is unchanged.

Removes nothing: the diff only adds a provider. A source-provider plugin can no longer register the id linear, which is now built in, the same as jira.

Tests

test/test_source_issues_linear.py, against fake Linear GraphQL responses through the real routes:

  • A missing key on the search route and the issue read answers 503 asking to add LINEAR_API_KEY, before any call. When Linear's own error text repeats the key, it reaches neither the responses, the logs nor the audit record; the key is sent only as the header. A key with whitespace is refused unsent.
  • Provider errors map to fixed messages; an unknown issue says so.
  • An issue URL reads the issue in the shared shape; canceled maps to closed as not planned; more comments than the cap mark the section partial; an issue in another workspace is refused.
  • URL normalization, and refusal of other Linear URLs (wrong segments, ports, keys, and paths with an empty or . segment).
  • Structured filters become variables under the team clause; a display name with spaces is searched as one name; default sort; summary shape; empty results.
  • A raw filter that tries to reach another team (a top-level or over other team keys) stays ANDed under the requested team, and rows from another team or with no team are dropped. Invalid scopes, a host and malformed raw filters (non-object JSON, an empty object, plain text instead of JSON, field names that are not identifiers, NaN or infinite numbers, control characters, over-deep nesting) are refused before any call.
  • Paging: a later page walks the earlier cursor boundaries, a page past the end is empty, paging stops at the window, and the last page inside the window asks only for the rows the window still holds.
  • Secrets in an issue and in a search excerpt come back redacted.

test/test_source_issue_search.py: the planned-provider case now covers only jira.

Manual verification

N/A — no live Linear workspace is wired to the test gateway; the fake GraphQL responses cover the request and response shapes, and the routes run for real in the tests.

Screenshots / video

Why no screenshot: the only frontend change is doc comments in website/src/types/index.sources.ts, which renders nothing.

Checklist

  • At most two commits, with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners November 12, 2026 00:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b3c4df4dce9365e5f29a7154206be0acc1f801c3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b3c4df4

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b3c4df4dce9365e5f29a7154206be0acc1f801c3 false-positive: <reason, 20 to 500 characters>

@kyleseaman
kyleseaman force-pushed the feat/source-issues-linear branch from 9f6cdce to 2f4dcf1 Compare November 12, 2026 01:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of b3c4df4dce9365e5f29a7154206be0acc1f801c3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The diff only adds a Linear backend behind the existing issue API and updates type comments, so no user-visible control changes and no screenshot is needed.

[UX-REVIEWED] b3c4df4

Description read

[DESCRIPTION-READ] e002fe7192478580233dc9bb43fe494c42ffd810faa7e76864aebfd58599992e

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b3c4df4dce9365e5f29a7154206be0acc1f801c3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level blocker: the design adds a provider behind the existing redaction, cache and team-scoped filter, and takes away only a plugin id that is now built in.

Notes

  • This adds a third way to dispatch a provider (an install-on-import registry), next to the if/elif chain in cache._fetch_issue_uncached and the plugin registry. The tests prove the GraphQL documents only against fake responses, so check the field names (issue(id:) taking a key, organization { urlKey }) against a live workspace once one is available.

[DESIGN-REVIEWED] b3c4df4

Description read

[DESCRIPTION-READ] 4d2de0443b973dec52eaea961dd7f75fc9711a3af44e19b3dce9b57c8da545b3

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b3c4df4dce9365e5f29a7154206be0acc1f801c3 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: every item serves the frozen Goal. The two install hooks and the now-empty planned-provider branch are notes.

Notes

  • Item 7 — one consumer, generalized: _INSTALLED_ISSUE_READERS and install_provider are mutable registries whose only entry is linear (grepped install_issue_reader\|install_provider(: 1 caller each, both in linear.py). Jira already solves the same import-order problem without a registry: jira.py sits before cache, cache calls jira._fetch_jira_issue by name, and _PROVIDERS["jira"] is a literal entry. Subtraction: delete both hooks, move linear ahead of cache, and make it a literal elif plus a _PROVIDERS entry, the same way Jira is wired.
  • Item 8 — zero consumers: _PLANNED_PROVIDERS is now frozenset(), so the provider_not_supported branch in parse_issue_query can no longer be reached. The test only reaches it by patching in "asana" (# Every named provider is served today, so this checks the branch with a stand-in). Subtraction: delete _PLANNED_PROVIDERS, its branch and the stand-in test.

What this change ships

Inventory (8 items) — 6 justified

Intent: let app pages read one Linear issue, and list or search one Linear team's issues, through the existing issue endpoints. ADDITION.

  1. /api/source/issues serves Linear team search instead of provider_not_supported — justified
  2. /api/source/issue reads a linear.app issue URL, refusing one from another workspace — justified
  3. Requests read LINEAR_API_KEY from the vault; a missing key answers 503 with setup text — justified
  4. raw accepts a Linear IssueFilter JSON object, always ANDed under the team — justified
  5. A page number is walked over Linear's cursors, capped at 1,000 results — justified
  6. Plugins can no longer register the provider id linear — justified
  7. New install hooks in cache and issue_search — one consumer, generalized
  8. The provider_not_supported branch now has no provider — zero consumers, undeclared

[FIRST-PRINCIPLES-REVIEWED] b3c4df4

Description read

[DESCRIPTION-READ] 04973915b62f6fa4df96804a1b8042bf2281ba32b6dbecc1d1dfc2c32004d66a

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b3c4df4dce9365e5f29a7154206be0acc1f801c3 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b3c4df4

Verdict parsed from the review's SHA-scoped output markers for commit b3c4df4dce9365e5f29a7154206be0acc1f801c3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b3c4df4dce9365e5f29a7154206be0acc1f801c3 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

KiroCrewCaptain commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 1297 lines, more than the 400 it may approve on its own.

The PR adds read-only Linear issue read and search behind the existing owner-only endpoints, with the API key read from the vault on each request and sent only as a header. All provider errors are fixed text. Every search filter is ANDed under the requested team, and rows from other teams are dropped. Single-issue reads go through cache's existing redaction, byte cap and cache. The new parse_source_url branch can't affect pull-request callers (they reject issue refs), the visibility code (it filters by provider) or the chip scanner (Linear's '/issue/' path doesn't match its markers). The import-order and copy-only-types facade tests still hold. The paging window and per-page limits are consistent and tested. The tests are thorough and run the real routes against a fake Linear API. Only description drift and simplification notes remain.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit b3c4df4dce · 1297 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/source-issues-linear branch from 2f4dcf1 to e89f6f1 Compare November 12, 2026 02:17
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/source-issues-linear branch from e89f6f1 to 41d6ecc Compare November 12, 2026 10:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 12, 2026
bolichen97
bolichen97 previously approved these changes Nov 12, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. I read every product file in the diff (linear.py, links.py, cache.py, issue_search.py, plugins.py, the handler's import-order entry, index.sources.ts, the docs) and skimmed the tests.

  • Owner auth is unchanged. Neither api_issue_search nor the single-issue handler changes. Linear is installed as one more IssueProvider and one more cache issue reader, so both reads sit behind the same owner-session check, with app tokens still refused.
  • The credential comes only from the existing secret store. LINEAR_API_KEY is read per request from SecretVault in a worker thread, never from .env or the process environment. It is sent only as the Authorization header, to the fixed https://api.linear.app/graphql, with allow_redirects=False and the capped read. A missing or malformed key fails with fixed text before any call.
  • No key or query in logs. The only log line is a debug when the vault read itself fails. Every error is the module's own fixed text, never Linear's, which could echo submitted values.
  • User input travels only as GraphQL variables. All three documents (_ISSUE_QUERY, _SEARCH_QUERY, _PAGE_QUERY) are constants, and the filter, sort, cursor and id go in variables.
  • Team scope can't be widened. search_filter always returns {"and": [{"team": {"key": {"eq": <TEAM>}}}, ...]}. A raw IssueFilter is parsed and bounded (letters-only keys, depth 8, no NaN or Infinity, no control characters) and placed inside that and. _summary still drops any row whose team isn't the requested one, and URLs are built from the validated workspace and team. The single-issue read refuses an issue whose own URL is in another workspace.
  • No regex. The team key, workspace, issue key and URL path checks are charset and PurePosixPath code. links.py only gains import string; its existing re import is unchanged.
  • On main Linear answers provider_not_supported and /api/source/issue can't read it, so this adds a capability and tightens nothing existing.

Heads-up, non-blocking: #35659 (Jira search) edits the same _PLANNED_PROVIDERS line, setting it to {"linear"}, and the same doc rows, while this PR sets it to {"jira"}. Whichever merges second will need a rebase, and the line should end up frozenset() with both providers in the docs.

@bolichen97
bolichen97 enabled auto-merge (squash) November 12, 2026 12:07
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026
@kyleseaman
kyleseaman force-pushed the feat/source-issues-linear branch from 41d6ecc to b3c4df4 Compare November 12, 2026 14:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

A maintainer approved this design on an earlier head. A later push (the rebase over #35659 and the URL path fix) dismissed that review, so the PR now waits for a maintainer approval on this head.

This review found no blocking issue on b3c4df4. PR Readiness is green on this head, and there are no open change requests. What the review checked on this head:

  • All outbound calls go to the fixed Linear GraphQL endpoint with redirects off and a capped response read.
  • LINEAR_API_KEY comes only from the secret vault, is sent only in the Authorization header, and never appears in a log or an error.
  • Both endpoints still sit behind the existing owner-only check.
  • Every GraphQL document is a constant, and user input travels only as variables.
  • The search filter always wraps the team clause in an and. A raw IssueFilter is bounded (letters-only keys, depth cap, no NaN or Infinity).
  • Rows from another team are dropped, and URLs are built from the validated workspace and team.

Security: the PR adds a new secret and new parsing of external input. The risk is contained because the key never leaves the Authorization header, error text is the module's own fixed text, the team scope cannot be widened through raw, and the single-issue read refuses an issue whose own URL points at another workspace.

Done well: Linear plugs into the existing cache issue reader, not a parallel path. It gets the shared redaction, byte cap and in-flight sharing without new code.

Optional:

  • The body is stale against the diff. It says Jira still answers provider_not_supported and that the planned-provider test covers jira, but feat(source): Jira issue search (JQL) for POST /api/source/issues #35659 has merged and the test now uses an asana stand-in. The useIssues / IssueList / IssueCard components it cites land in feat(app-sdk): issue list components (useIssues, IssueList, IssueCard) #34732, not on main. A PR comment can correct the frozen sections.
  • linear.py fetch_search always answers "Check the raw IssueFilter field names" when Linear refuses a search, even when the request had no raw. Picking the message by whether query.raw is set would point the operator at the right cause.
  • plugins.py now reserves the linear provider id, but the frontend BUILTIN_PROVIDER_IDS set in website/src/utils/pullRequestLinks.ts does not. Adding it there keeps the two layers in agreement.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-approving after the rebase onto #35659. I compared this head's diff with the one I approved (41d6ecc), and the only differences are the merge with Jira search:

  • _PLANNED_PROVIDERS is now frozenset(), since both Jira and Linear are served, as suggested.
  • The API reference, feature-map row, module docstring and index.sources.ts comments name all four providers.
  • test_planned_provider_answers_provider_not_supported keeps its branch covered with a stand-in id (asana) patched into _PLANNED_PROVIDERS.

linear.py, links.py, cache.py, plugins.py and the Linear tests are unchanged from the head I approved, so the earlier review stands: owner-only routes, the vault-only LINEAR_API_KEY, constant GraphQL with values as variables, team scope ANDed in, no regex.

@bolichen97
bolichen97 merged commit e30537e into main Nov 12, 2026
101 checks passed
@bolichen97
bolichen97 deleted the feat/source-issues-linear branch November 12, 2026 17:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants