Skip to content

feat(source): Jira issue search (JQL) for POST /api/source/issues - #35659

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

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

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app page can list and search one Jira project's issues through POST /api/source/issues, the same way it already can for a GitHub repository or GitLab project.

The issue search route from #34742 names Jira as a planned provider and answers jira with 400 provider_not_supported. The app SDK's useIssues / IssueList / IssueCard components therefore cannot show Jira issues, though the gateway already reads single Jira issues for the Issues panel.

Why it matters

Teams that track work in Jira (Cloud or Server/Data Center) get nothing from the reusable issue components until the search route serves Jira. Without it an app would have to call Jira itself with its own credentials, outside the gateway's host allowlist, permission check and redaction.

Not a goal

  • Linear search (still answers provider_not_supported).
  • Jira Server/Data Center served under a context path such as /jira (the search builds https://<host>/rest/...; noted as a shortcut: in jira.py).
  • New Jira auth, config keys or a sign-in flow: the search uses the existing dashboard.jira_auth token.
  • A dashboard surface for issue search, and any write to Jira.

What changed (motivation → approach → change)

Goal → reuse the single-issue Jira reader and the route's existing contract → add a third IssueProvider.

  • Auth and HTTP reuse (jira.py). The header building and the capped, no-redirect GET in _fetch_jira_issue are split into _jira_request_headers and _jira_get_json, and the new search_jira_issues calls both. Cloud searches /rest/api/3/search/jql, Server/DC /rest/api/2/search. The single-issue read keeps its URLs and messages.
  • Scope cannot be widened (issue_search.py). The JQL always starts with the gateway's own project = "<KEY>" clause, ANDed with every filter. Every value (person, label, text) goes in as one escaped JQL string literal; assignee: 'me' becomes currentUser(). Free text loses JQL's operator characters. raw JQL is wrapped in parentheses and refused if, outside quoted values, a parenthesis closes one it did not open, a quote or parenthesis is unbalanced, a backslash appears, or it uses ORDER BY. Rows whose key is not in the project are dropped. The host must be a *.atlassian.net site or a dashboard.jira_hosts entry. All of this is plain string code, no regex.
  • Paging. Server/DC pages with startAt and reports total; when an instance caps maxResults below limit, the gateway fills the page with follow-up requests from where the answer stopped, so the next page's startAt skips nothing. Cloud's /search/jql pages only by an opaque nextPageToken and has no total, so the gateway keeps each token server-side (30 min, 512 entries) keyed by the normalized query, and the cursor stays the same page number the other providers use. A page whose token is no longer held is reached by walking forward from the nearest held one (at most 20 pages), else 400. The endpoint and the paging use the same Cloud test (jira._jira_is_cloud).
  • Same issue shape and redaction. Rows map to the shared IssueSummary (statusCategory done → closed, priority filled, commentCount 0 because search returns no count, Cloud accountId / Server name as the login). Cloud's ADF description is rendered to one plain string by the new adf._adf_plain_lines before cache.search_issues redacts the rows, so a token or PEM key split across ADF nodes is redacted whole. That string is used as written, with no markdown strip, so literal text such as <!-- ... --> or snake__case in a code block stays in the excerpt; Server/DC's wiki text keeps the markdown strip. Redaction, the payload cap and the 30 s cache are the existing cache.search_issues path; cache.py is unchanged.
  • Docs and types. docs/app-kit/api-reference.md, the feature map row and the IssueSearchRequest comments in website/src/types/index.sources.ts now describe Jira (host required, account ID vs username, JQL limits, no total on Cloud).

No Sensitive Change Review watched file is touched.

Backwards compatibility

Compatible: a jira request that answered 400 provider_not_supported now gets results; GitHub, GitLab, Linear and the single-issue Jira read behave as before.

Removes nothing: Jira leaves the planned-provider set because it is now served; the only test change for it is the one parametrize case that asserted the old 400.

Tests

test/test_source_issue_search_jira.py (new, through the real route with fake Jira responses):

  • Cloud and Server/DC request shape: endpoint, auth header (Basic email:token vs Bearer), structured filters as one scoped JQL.
  • Injection: person, label and text values containing ", \, parentheses, OR/AND and ORDER BY stay one literal; raw JQL that could leave the project group (unbalanced or closing parens, stray quotes, backslashes, ORDER BY) is refused before any request; valid raw is ANDed inside the group.
  • Errors: invalid scope/host, missing credentials, Cloud without email, HTTP 401/403/404/5xx, invalid payloads.
  • Shape: Cloud and Server summaries, a Cloud excerpt keeping literal text a markdown strip would delete, rows from other projects dropped, empty results.
  • Paging: Cloud tokens held by the gateway, walk-forward (including exactly 20 pages past a held token), past-the-last page, too-far page refused, no next page offered when no token, an allowlisted *.atlassian.net subdomain paging as Cloud; Server against total, and a Server that caps page size still returning every issue across pages; per-page cache and refresh.
  • Redaction: a secret in summary/status/description, a token split across ADF text nodes, a PEM key across ADF paragraphs; _adf_plain_lines line breaking.

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

Local: the prepush gate passed, and the issue search test files passed 5 parallel repeats and shuffled-order serial repeats.

Manual verification

N/A — unit coverage sufficient: no live Jira site is configured on this machine, so both editions are covered with fake responses through the real route.

Related Issues

Follows #34742 (GitHub and GitLab issue search).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners November 11, 2026 23:35
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check: the change adds a backend search route plus type comments and docs, with no dashboard control or rendered surface.

[UX-REVIEWED] dda60ec

Description read

[DESCRIPTION-READ] de9e2202b18fba13175bf3fae312b484881d528855f6c63751ebd7ba4d9dd4ac

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 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: this backend-only change adds a provider under the existing route contract, and the JQL is always scoped to the project; the website change is type comments only, so no screenshots are needed.

Notes

  • The Cloud nextPageToken map (_JIRA_PAGE_TOKENS) is held in memory, per process, so a gateway restart or a second worker makes a page cursor the client already holds return 400 once it is more than 20 pages past a held token. That is reversible, but api-reference.md should say Jira Cloud cursors are short-lived and tied to one gateway process.

[DESIGN-REVIEWED] dda60ec

Description read

[DESCRIPTION-READ] e8a69bc2fd44830f828e4e673875e2c9bf88399bc75c012872dc6de20305e394

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 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of dda60ecc88585c63e74cbec5c399101549cbcb25 — 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. Two notes: this is the third check for a Cloud host, and the page walk-forward goes further than the Goal needs.

Notes

  • Item 3 — duplicate (note): _is_jira_cloud_host is the third way the code tells whether a host is Jira Cloud. The others are jira._jira_is_cloud (jira.py:174) and the inline test at links.py:407 (grepped atlassian\.net). The new one admits fewer hosts than links.py, so a URL the Issues panel reads, such as a.b.atlassian.net, is refused by the search. Subtraction: delete _is_jira_cloud_host and admit hosts with the links.py:407 rule, so one admission rule serves both routes.
  • Item 5 — oversized: if a page's token has expired, the gateway walks forward up to 20 pages to reach it (_JIRA_MAX_PAGE_WALK and its loop in _jira_known_page). The Goal only asks that a page can be listed and searched, and the 400 "start from the first page" answer already covers an expired token. Subtraction: delete the walk and answer 400 whenever the token is not held. Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (8 items) — 6 justified

Intent: let an app page list and search one Jira project's issues through the gateway's existing issue-search route. ADDITION.

  1. A jira request to POST /api/source/issues now returns issues instead of 400 provider_not_supported — justified
  2. Structured filters and raw JQL are always ANDed under the gateway's project = clause, and raw JQL that could escape it is refused — justified
  3. Any single-label *.atlassian.net host is accepted without an allowlist entry — duplicate of links.py:407 / jira._jira_is_cloud
  4. Jira Cloud page tokens are held on the gateway (30 min, 512 entries) and the browser pages by number — justified
  5. A page whose token has expired is reached by walking forward up to 20 pages — oversized
  6. Server/DC pages are filled with follow-up requests when the instance caps maxResults — justified
  7. Cloud ADF descriptions become one plain-text excerpt, so a secret split across nodes is redacted whole — justified
  8. The Jira header and GET code is split out of the single-issue reader so search can reuse it; docs and TS comments updated — justified

[FIRST-PRINCIPLES-REVIEWED] dda60ec

Description read

[DESCRIPTION-READ] 47f2506d88ad9320e5118dcb02c8292de33d76535474719d0fca1780824fc249

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 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] dda60ec

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

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

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] dda60ec

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

@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-jira branch from 3e5f1cc to dda60ec Compare November 12, 2026 10:46
@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
@KiroCrewCaptain

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 1370 lines, more than the 400 it may approve on its own.

Adds Jira (Cloud and Server/DC) as a third provider for POST /api/source/issues. Checked against the code: the JQL always starts with the gateway's project clause. Structured values go in as escaped string literals, and raw JQL is scanned the way Jira reads quotes, refused if it could close the gateway's group, and wrapped in parentheses. Rows from other projects are dropped. Credentials resolve only for hosts with a jira_auth entry, and redirects are not followed. Rows still pass through the existing cache.search_issues redaction, twice and before the excerpt cut, and Cloud page tokens are saved before redaction and never reach the browser. The jira.py refactor keeps the single-issue read's URLs, auth and error mapping, and SourceProviderError is a RuntimeError, so the new except ValueError can't swallow provider errors. Paging and the token store are bounded. The route-level tests are thorough. No regressions found on sibling providers. CI backend, E2E and one frontend test job were still pending at review time.

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 dda60ecc88 · 1370 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels 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 (issue_search.py, jira.py, adf.py, index.sources.ts, the docs) and skimmed the tests.

  • Owner auth is unchanged. The PR adds one IssueProvider entry and does not touch api_issue_search, so Jira is served behind the same owner-session check as GitHub and GitLab, and app tokens are still refused.
  • Credentials and host match main. search_jira_issues reuses _jira_request_headers, which is the single-issue reader's _get_jira_auth path (jira.py:38 on main): vault or .env per host, unchanged. The host must be *.atlassian.net (as links.py:401-407 already accepts) or a dashboard.jira_hosts entry. _jira_get_json keeps allow_redirects=False and the capped read, so the token only ever goes to that host.
  • No token or JQL in logs. No logging is added. The no-credentials message is caught and rewritten so the host isn't echoed back to the browser.
  • The JQL is a parameter, not part of the path. jira_params returns ("jql", ...) tuples and search_jira_issues encodes them with urlencode(params, quote_via=quote). The path is one of two fixed strings.
  • Scope can't be widened. The gateway's project = "<KEY>" clause comes first. Every value goes through _jql_string (backslash and quote escaped). Raw JQL is ANDed in parentheses it can't close (_jira_raw_clause tracks depth outside quotes, refuses a stray \, and refuses ORDER BY). _project_jira_issues drops any row whose key isn't <KEY>-<n>.
  • No regex. The key, host label and JQL checks are all charset and string code.
  • On main Jira answers provider_not_supported, so the raw-JQL rules narrow a new capability rather than an existing one.
  • The page-token map and the Server/DC fill loop are both bounded (512 entries, 30 min TTL, 20-page walk, and each extra request must return a row).

@bolichen97
bolichen97 merged commit dafe034 into main Nov 12, 2026
104 of 105 checks passed
@bolichen97
bolichen97 deleted the feat/source-issues-jira branch November 12, 2026 12:05
@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