Repository navigation
feat(source): read and search Linear issues through the issue endpoints - #35666
Conversation
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
9f6cdce to
2f4dcf1
Compare
UX Review (Opus 5.5) — ✅ PASSUX-level review of 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 |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of 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
[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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of 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
What this change shipsInventory (8 items) — 6 justifiedIntent: let app pages read one Linear issue, and list or search one Linear team's issues, through the existing issue endpoints. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] b3c4df4 Description read[DESCRIPTION-READ] 04973915b62f6fa4df96804a1b8042bf2281ba32b6dbecc1d1dfc2c32004d66a That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: A person should decideWhy: 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 |
2f4dcf1 to
e89f6f1
Compare
e89f6f1 to
41d6ecc
Compare
bolichen97
left a comment
There was a problem hiding this comment.
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_searchnor the single-issue handler changes. Linear is installed as one moreIssueProviderand one morecacheissue 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_KEYis read per request fromSecretVaultin a worker thread, never from.envor the process environment. It is sent only as theAuthorizationheader, to the fixedhttps://api.linear.app/graphql, withallow_redirects=Falseand 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
debugwhen 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 invariables. - Team scope can't be widened.
search_filteralways returns{"and": [{"team": {"key": {"eq": <TEAM>}}}, ...]}. A rawIssueFilteris parsed and bounded (letters-only keys, depth 8, no NaN or Infinity, no control characters) and placed inside thatand._summarystill 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
PurePosixPathcode.links.pyonly gainsimport string; its existingreimport is unchanged. - On main Linear answers
provider_not_supportedand/api/source/issuecan'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.
41d6ecc to
b3c4df4
Compare
|
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:
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 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:
|
bolichen97
left a comment
There was a problem hiding this comment.
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_PROVIDERSis nowfrozenset(), since both Jira and Linear are served, as suggested.- The API reference, feature-map row, module docstring and
index.sources.tscomments name all four providers. test_planned_provider_answers_provider_not_supportedkeeps 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.
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/issuesserves GitHub and GitLab and answersprovider_not_supportedfor Linear.POST /api/source/issuecannot 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
provider_not_supportedon/api/source/issues.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.
source_providers/linear.py. It reads the key from Crew's vault asLINEAR_API_KEYon each request (vault only, never.env, so it never enters the process environment a child could inherit). The key goes only in theAuthorizationheader 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.me, labels, text, sort, paging) map onto anIssueFilter.{"and": [<team clause>, ...]}, andraw(a LinearIssueFilterJSON object) is validated and placed inside thatand. Any row whose team is not the requested team is dropped anyway.pagecontract 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./api/source/issueresolves to one ref (links.py, which splits the URL path withPurePosixPathlike 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 itsurl.cacheandissue_searchare listed beforelinearin the owner import order, so they cannot import it. Insteadlinearinstalls itself on import through two small hooks,cache.install_issue_readerandissue_search.install_provider; the handler listslinearin_OWNED_NAMESso it is imported and covered by the import-order checks. Single-issue reads go throughcache's existing redaction, byte cap and cache, and search excerpts throughcache.search_issues, the same as the other providers.issue_search.pychanges only by removinglinearfrom_PLANNED_PROVIDERSand addinginstall_provider, to keep the overlap with the parallel Jira search PR small.plugins.pyreserveslinearas a built-in provider id.docs/app-kit/api-reference.md(the issue-search and issue-read API reference), the request type comments inwebsite/src/types/index.sources.tsand the Issue search row indocs/feature-map/README.mdnow name Linear.Backwards compatibility
Compatible: Linear requests that answered
provider_not_supportednow 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 asjira.Tests
test/test_source_issues_linear.py, against fake Linear GraphQL responses through the real routes: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..segment).orover other team keys) stays ANDed under the requested team, and rows from another team or with no team are dropped. Invalid scopes, ahostand 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.test/test_source_issue_search.py: the planned-provider case now covers onlyjira.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
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.