feat:add Jira Cloud API support #348
Conversation
panyamkeerthana
force-pushed
the
panyamkeerthana/jira_api_support
branch
from
e56e34f to
b5076e3
Compare
implemented support for Jira Cloud REST API v3 while maintaining backward compatibility with Jira Server v2. - added Basic Auth (email:token) support for Jira Cloud v3 - added JIRA_EMAIL env var requirement for v3 - added _text_to_adf() and _adf_to_text() helper functions for ADF <-> plain text conversion - stored original ADF in JiraComment.adf for roundtrip preservation - converted descriptions and comments automatically based on API version - added adftotxt library for ADF parsing - fixed pagination: use nextPageToken for v3, startAt for v2 - user lookup: v3 uses 'query' parameter and v2 uses 'username' parameter
panyamkeerthana
force-pushed
the
panyamkeerthana/jira_api_support
branch
from
b5076e3 to
00f09b6
Compare
added test_jira_cloud_uat.py script that validates all Jira API operations - test cases covering authentication, ADF conversion - tests for CRUD operations, comments, attachments, labels, status changes - validate JQL search and jotnar tag functionality
owtaylor
left a comment
owtaylor
left a comment
There was a problem hiding this comment.
Nice work - it's good to understand what's involved. Clearly the big thing here is ADF - there's no obvious simple approach that's going to work well with that. I've proposd two "complicated" solutions - one for the ADF => text part, and one for the text => ADF part. (They should be largely AI implementable.)
Beyond that, the complexity that isn't explored here is converting the baseline tests code to parse and edit at the ADF level.
Probably there we'd want to treat this as test driven development - write (offline) tests for the existing format_issue_comment() / load_from_issue(), then make sure the tests still work using ADF comments.
|
|
||
|
|
||
| @cache | ||
| def jira_api_version() -> str: |
There was a problem hiding this comment.
A minor problem with this API is that it would be easy to write if jira_api_version() == 3 - the fact that it's str not isn't represented in the type system, maybe add an extra function for checks like:
jira_api_version_is(ver: Literal[2] | Literal[3]) -> bool
| requires-python = ">=3.13,<3.14" | ||
| # we are installing bee 0.1.55 in containers now | ||
| dependencies = [ | ||
| "adftotxt>=0.0.18", |
There was a problem hiding this comment.
This looks like something we don't want to use:
- No public repository I can find
- Not updated in years
- Only 150 lines of code
Doing some research, a different approach to rendering would be to use:
API - where you can basically define your own JSON structure for the response using "JIRA expressions" API, with either a JQL query or a issue ID as the input. It would basically mean entirely different code paths for get_issue / get_current_issues / get_issue_by_jotnar_tag for the two APIs, but that's not necessarily a bad thing, especially since the v2 API will be dropped entirely eventually.
The way this works in slightly more detail is that the ADF fields have a .plainText accessor in JIRA issues, that renders the result markdown-style. (Not sure how it handles complicated stuff like tables or panels, but presumably is identical to what using the v2 API on JIRA cloud gives you.)
| CommentSpec = None | str | dict[str, Any] | tuple[str | dict[str, Any], CommentVisibility] | ||
|
|
||
|
|
||
| def _text_to_adf(text: str) -> dict[str, Any]: |
There was a problem hiding this comment.
Hmm, we need the model able to express formatting - links, lists, etc - so we need something more featureful than this. Looking around, I don't think there are any satisfactory Python libraries for doing this. The alternatives I know of are:
- Use the v2/ jira api for adding comments and creating bugs, which has implicit wikimarkup => ADF conversion
- Use a javascript library like @atlaskit/editor-wikimarkup-transformer from Atlassian, and then somehow fit tha into our application
I think I'm somewhat more in favor of the second approach, though it feels like a rather ridiculous amount of complexity (though not much code). The basic way it would work would be:
- Create a node.js web server that takes a post to /convert?input=wikimarkup&output=adf
- Add that as another service within compose.yaml / as another pod in our openshift config
Nice thing is that once we don't care about v2 any more, we could have the models write markdown rather than wikimarkup - Gemini isn't as good at writing the wiki markup as it is at writing markdown.
A question then would be would we want to use the same local service to convert ADF => wikimarkup. I tend to think not as long as the jira expressions / .plainText approach works. There's some definite complexity in efficienctly feeding a bunch of retrieved descriptions and comments through the local service.
| if jira_api_version() == "3": | ||
| body_content = comment_value | ||
| else: | ||
| body_content = _adf_to_text(comment_value) |
There was a problem hiding this comment.
I don't think we want to support posting ADF comments to v2 server - it doesn't seem useful to me
2 participants
implemented support for Jira Cloud REST API v3 while maintaining backward compatibility with Jira Server v2 and added UAT test script (scripts/test_jira_cloud_uat.py).