feat(jira): add Jira Server/Data Center support via api_version#561
Open
sergeyklay wants to merge 2 commits into
Open
feat(jira): add Jira Server/Data Center support via api_version#561sergeyklay wants to merge 2 commits into
sergeyklay wants to merge 2 commits into
Conversation
Introduces a new optional tracker config field `api_version` ("2" or
"3", default "3") that selects the Jira REST API variant at adapter
construction time.
Key changes:
- v2 uses offset-based pagination on `/rest/api/2/search` instead of
the v3 cursor-based `/rest/api/3/search/jql` endpoint
- v2 descriptions and comment bodies are raw wiki-markup strings;
v3 continues to flatten ADF to plain text
- v2 comment creation sends a raw-string body; v3 sends ADF
- A colon-free api_key authenticates as Bearer (PAT) on v2 and is
rejected on v3, which requires email:token Basic auth
- Construction-time host/version guard rejects Cloud endpoints with
api_version "2" and warns on non-Cloud endpoints with "3"
- Config layer, schema validator, and resolve map all carry the new
field through; bare YAML integers draw a type_mismatch advisory
sergeyklay
added
the
area:tracker-adapter
There was a problem hiding this comment.
Pull request overview
This PR extends the Jira tracker adapter to support Jira Server/Data Center by introducing an optional tracker.api_version configuration switch (defaulting to "3" for Cloud), and branching request paths/pagination/auth/body handling based on whether v2 or v3 is selected.
Changes:
- Add
tracker.api_versionto config/schema/docs, plumb it through CLI config resolution, and normalize/validate it at Jira adapter construction. - Implement v2-specific adapter behavior:
/rest/api/2base paths, v2 search offset pagination, v2 Bearer-vs-Basic auth selection, and v2 comment/description body handling (raw wiki-markup strings). - Add/extend tests and fixtures to cover v2 pagination, auth, payload shape, and v3 regression behavior.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| internal/tracker/jira/jira.go | Adds api_version selection, base path switching, v2 pagination/auth/comment payload branching. |
| internal/tracker/jira/normalize.go | Introduces v2 search response envelope and api-version-aware body extraction for descriptions/comments. |
| internal/tracker/jira/normalize_test.go | Updates existing normalization tests for new function signatures (apiVersion parameter). |
| internal/tracker/jira/normalize_v2_test.go | Adds focused tests for v2 body extraction and v2 normalization invariants. |
| internal/tracker/jira/jira_v2_test.go | Adds end-to-end adapter tests for v2 search pagination, auth, comment write shape, and v3 regressions. |
| internal/tracker/jira/client.go | Refactors client construction to accept a fully-formed Authorization header (Basic/Bearer). |
| internal/tracker/jira/client_test.go | Updates client tests to construct the Basic auth header explicitly. |
| internal/tracker/jira/testdata/search_v2_single_page.json | Adds v2 search fixture for a single-page offset response. |
| internal/tracker/jira/testdata/search_v2_multi_page_1.json | Adds v2 search fixture for multi-page offset pagination (page 1). |
| internal/tracker/jira/testdata/search_v2_multi_page_2.json | Adds v2 search fixture for multi-page offset pagination (page 2). |
| internal/tracker/jira/testdata/comments_v2.json | Adds v2 comment fixture with wiki-markup bodies and null author coverage. |
| internal/config/schema.go | Registers tracker.api_version as a known tracker field. |
| internal/config/schema_api_version_test.go | Adds schema validation tests ensuring api_version is recognized and type mismatches are advisory. |
| internal/config/config.go | Adds TrackerConfig.APIVersion and extracts/resolves tracker.api_version. |
| internal/config/config_api_version_test.go | Adds config parsing tests to ensure api_version is carried through and $VAR is resolved consistently. |
| cmd/sortie/resolve.go | Includes api_version in the raw tracker config map passed to adapter constructors. |
| docs/jira-adapter-notes.md | Updates adapter notes to document v2/v3 behavior, auth selection, body formats, and pagination differences. |
| docs/architecture.md | Updates the architecture/config spec to include tracker.api_version semantics and quoting guidance. |
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Comment on lines
+355
to
+358
| apiVersion := extractString(m, "api_version") | ||
| if !envKeys["tracker.api_version"] { | ||
| apiVersion = resolveEnvRef(apiVersion) | ||
| } |
Comment on lines
+249
to
+262
| host := strings.ToLower(parsed.Hostname()) | ||
| isCloud := strings.HasSuffix(host, ".atlassian.net") | ||
|
|
||
| if isCloud && apiVersion == "2" { | ||
| return &domain.TrackerError{ | ||
| Kind: domain.ErrTrackerPayload, | ||
| Message: fmt.Sprintf("tracker.api_version 2 targets Jira Server / Data Center; endpoint %s is Jira Cloud, which requires api_version 3", host), | ||
| } | ||
| } | ||
|
|
||
| if !isCloud && apiVersion == "3" { | ||
| slog.Warn("tracker.api_version 3 against non-cloud endpoint will return 404", | ||
| slog.String("host", host)) | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 Scope & Context
Type: Feat
Intent: Extend the Jira adapter to support Jira Server and Data Center in addition to Jira Cloud. A new optional
tracker.api_versionconfig field ("2"or"3", default"3") selects the REST API variant at adapter construction time, enabling users running self-hosted Jira to connect without any adapter code changes.Related Issues: #549
🧭 Reviewer Guide
Complexity: High
Entry Point
Start with
internal/tracker/jira/jira.go. This file contains all the new construction logic:normalizeAPIVersion,resolveAuth,checkHostVersion,basePath,paginatedSearchV2, andcommentPayload. The adapter struct gainsapiVersionandbasePathfields that drive every request path and body-format decision downstream.Sensitive Areas
internal/tracker/jira/jira.go: Auth header selection (resolveAuth) decides between Basic and Bearer based on the presence of a colon inapi_keyand the API version. The v2 colon-free path must produceBearer <token>and must be rejected on v3. The host/version guard (checkHostVersion) blocks Cloud endpoints combined withapi_version "2"to prevent silent failures against the wrong API surface.internal/tracker/jira/normalize.go:extractBodyswitches between ADF flattening (v3) and raw JSON-string unquoting (v2). An incorrect branch here would pass raw ADF JSON or stripped wiki markup to the prompt template.internal/config/config.goandinternal/config/schema.go: The newapi_versionfield follows the sameextractString/resolveEnvRef/ env-key-guard pattern asin_progress_state. A bare YAML integer reachesextractStringas an empty string; the adapter applies its own coercion later.api_versiondefaults to"3", preserving all existing Cloud behavior. Existing configs without the field are unaffected.