Jira Server / Data Center support (REST v2, PAT/Basic auth, wiki markup)

[shokurov]

Summary

Makes the Jira integration work against self-hosted Jira Server / Data Center
instances (closes #494).

Previously the integration was hardcoded for Atlassian Cloud: every call used
/rest/api/3 (Data Center only ships v2), API-key auth was always
Basic email:apiToken (a DC PAT must be sent as Bearer), users were addressed
by accountId (DC uses name/key), and descriptions were written as ADF
(DC expects Jira Wiki Markup). Any self-hosted instance failed with 404/401 on
the very first probe.

What changed

• New dialect module jiraDeployment.ts — centralizes every Cloud vs
  Server/DC difference instead of scattering ternaries through the adapter:
  deployment detection (serverInfo probe + hostname heuristic fallback),
  auth-scheme resolution (Cloud Basic email:apiToken; DC Bearer PAT — even
  when an email is supplied — or Basic username:password), user refs
  (accountId vs name/key), and user-picker custom-field remapping.
• JiraAdapter: dialect-aware endpoints — v3 vs v2 paths, DC's bare-array
  GET /project vs Cloud's { values } from /project/search, classic
  /search vs enhanced /search/jql, createmeta differences for DC 9+.
  Deployment detection uses a v3 /myself probe with redirect: "manual" so a
  DC instance that 302-redirects unknown v3 paths to its login page isn't
  misread as a healthy Cloud endpoint; the resolved deployment/auth scheme is
  persisted in integration settings, so detection is a one-time event.
• Test-connection route mirrors the same detection, accepts all three
  credential shapes, probes the correct per-deployment endpoints, and persists
  the resolved deploymentType/authScheme (fill-missing-only, so a re-test
  never flips a working integration).
• Rich text on DC — new jiraWikiMarkup.ts serializes the editor's
  ADF to Jira Wiki Markup (marks, headings, lists, quotes, code blocks, tables)
  instead of stripping descriptions/comments to plain text; the ADF path is
  unchanged for Cloud.
• UI: Username/Password fields for DC Basic auth (previously the adapter
  accepted that shape but the form couldn't produce it), plus docs for both DC
  credential flows.
• i18n — the six new and four changed form strings translated across all
  15 non-source locales.

Testing

• ~1,600 lines of new unit tests: JiraAdapter dialect behavior (876), the
  test-connection route (330), deployment detection/auth resolution (213), and
  the wiki-markup serializer (179).
• Verified live against a real Jira Data Center 10.3.13 instance (PAT and
  username/password flows): connection test, JQL search, issue read, and
  rich-text round-trip (wiki markup renders bold/headings/lists/links/code via
  Jira's own renderer).
• Cloud behavior unchanged: v3 + Basic email:apiToken paths are the same code
  routed through the dialect module; existing Cloud tests pass.

Notes for reviewers

• The dialect module is deliberately dependency-free and side-effect-free so
  it can be unit-tested exhaustively; JiraAdapter and the test-connection
  route share it rather than duplicating detection.
• A companion PR splits out an unrelated zenstack generate memory fix.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement

How Has This Been Tested?

Describe the tests you ran to verify your changes:

• Unit tests
• Integration tests
• E2E tests
• Manual testing

Test Configuration:

• OS: Linux testplanit 7.0.0-22-generic Feature/api token support #22-Ubuntu SMP PREEMPT_DYNAMIC Mon May 25 15:54:34 UTC 2026 x86_64 GNU/Linux
• Browser (if applicable): MS Edge on Windows, Arc on MacOS
• Node version: v24.15.0

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published
• I have signed the CLA

Screenshots (if applicable)

[therealbrad]

@shokurov Thanks for this — the dialect module and the live DC 10.3.13 validation (PAT + Basic, rich-text round-trip) make this a much stronger footing than testing against mocks alone. A few small items before merge, all minor:

1. searchUsers: the assignable-user branch still sends the Cloud-only query= param on Data Center

In JiraAdapter.searchUsers, the general-search branch correctly switches to username= on server, but the adjacent assignable-search branch keeps query=:

if (projectKey && !isEmail) {
  // still query= on server
  endpoint = `/rest/api/${this.apiVersion}/user/assignable/search?project=${projectKey}&query=${encodeURIComponent(query)}&startAt=${startAt}&maxResults=${maxResults}`;
} else {
  // fixed
  endpoint = `/rest/api/${this.apiVersion}/user/search?${this.deployment === "server" ? "username" : "query"}=${encodeURIComponent(query)}&...`;
}

On Server/DC, /user/assignable/search filters by username (query is a Cloud-only param), so the assignee picker scoped to a project — when the term isn't an email — should return unfiltered results on DC. Since you have a live instance and I don't, could you confirm the behavior there and, if it reproduces, apply the same ternary?

const userParam = this.deployment === "server" ? "username" : "query";
endpoint = `/rest/api/${this.apiVersion}/user/assignable/search?project=${projectKey}&${userParam}=${encodeURIComponent(query)}&startAt=${startAt}&maxResults=${maxResults}`;

(If your DC version happens to accept query here too, a one-line comment noting that is enough — no code change needed.)

2. Dead branch in the v3 probe flow (cosmetic)

In both JiraAdapter.authenticate and testJiraConnection (route.ts), the probe reads:

if (v3Probe.ok) { … }
else if (!v3Probe.ok) { … }   // always true when reached
else { connection = v3Probe }  // unreachable

Since v3Probe.ok is boolean, the final else can't be hit — collapsing to a plain if/else reads clearer.

3. redirect: "manual" comment/test wording (cosmetic)

The "opaque redirect (non-OK, status 0)" comment and the status: 0 test mock describe browser fetch semantics; server-side (undici) redirect: "manual" returns the real 3xx response. The logic is correct either way (any non-ok falls through to serverInfo), so just a wording tweak on the comment/test if you touch it.

Everything else looks good to merge. One non-blocking question: I noticed the createmeta path is 9+/issuetypes/{id} only — was dropping the Jira 8.x classic-createmeta fallback intentional? Fine either way given 8.x is EOL, just want it to be a deliberate choice rather than an oversight.

[therealbrad]

https://github.com/TestPlanIt/testplanit/actions/runs/29085381733/job/86366369049 failed. Please run prettier on the branch so this passes next time.

[shokurov]

@therealbrad Thanks for the careful read — all items addressed in dd91f31 + 55ead7b.

1. Confirmed on live DC 10.3.13: query= on /user/assignable/search is silently ignored — a term matching nothing still returns the full assignable list (14 users), while username= filters correctly (2 matches for a real prefix, 0 for a nonsense term). Applied the same ternary as the general-search branch, with a comment noting the live verification, plus a unit test covering the assignable branch.

2. Dead else branches collapsed in both JiraAdapter.authenticate and testJiraConnection.

3. Reworded the redirect: "manual" comments and the test mock to describe server-side (undici) semantics — the probe sees the real 3xx response (non-OK), not a browser-style opaque status-0 response. The mock now returns status: 302.

Re createmeta: yes, dropping the 8.x classic-createmeta fallback was deliberate — Jira 8.x is EOL, and the 9+ createmeta/{key}/issuetypes/{id} path is what we validated against DC 10.3.13. Happy to add the fallback if 8.x support ever becomes a requirement.

CI: prettier run on the branch (the style: commit), format check passes locally now.

[therealbrad]

🎉 This PR is included in version 0.41.6 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀