docs-tools: migrate jira-reader from REST API v2 to v3#115
Open
bburt-rh wants to merge 3 commits intoredhat-documentation:mainfrom
Open
docs-tools: migrate jira-reader from REST API v2 to v3#115bburt-rh wants to merge 3 commits intoredhat-documentation:mainfrom
bburt-rh wants to merge 3 commits intoredhat-documentation:mainfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughJira-reader is migrated to Atlassian REST API v3 by constructing the JIRA client with Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant Skill as Jira-Reader Script
participant ClientLib as jira.Client
participant Atlassian as Jira API
User->>Skill: request issue/read
Skill->>ClientLib: JIRA(..., options={"rest_api_version":"3"}) & fetch issue
ClientLib->>Atlassian: HTTP /rest/api/3/... request
Atlassian-->>ClientLib: ADF-rich JSON response
ClientLib-->>Skill: issue data (ADF fields)
Skill->>Skill: adf_to_text(ADF) -> plain text
Skill-->>User: rendered issue data (plain text)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error)
✅ Passed checks (9 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py`:
- Around line 143-154: The REST API version is being set to v3 unconditionally
which breaks self-hosted Jira; move the options = {"rest_api_version": "3"} into
the Atlassian Cloud branch (the block that checks "atlassian.net" in server) and
pass that options when constructing JIRA with basic_auth, while for the else
branch (self-hosted/Jira Server) either omit options or set options =
{"rest_api_version": "2"} before calling JIRA(..., token_auth=token, ...);
update the use of the JIRA constructor calls (the JIRA(...) invocation in both
branches) accordingly so cloud uses v3 and server uses v2/default.
- Around line 63-64: The text-node branch in adf_to_text (the if node_type ==
"text" case) currently returns only node.get("text", "") and drops any link
marks; update it to detect marks on the node (node.get("marks", [])), find marks
where mark.get("type") == "link", extract mark["attrs"]["href"], and preserve
the URL when returning the text (for example append or embed the href alongside
node["text"] so labeled links keep their destination). Ensure this change is
made inside the adf_to_text function's node_type == "text" handling so
descriptions and comments retain ADF link hrefs.
In `@plugins/docs-tools/skills/jira-reader/SKILL.md`:
- Around line 48-80: Update the example invocations in SKILL.md to use the
CLAUDE_SKILL_DIR substitution for in-skill script calls: replace occurrences of
"python3 scripts/jira_reader.py ..." with "python3
${CLAUDE_SKILL_DIR}/scripts/jira_reader.py ..." for all examples referencing the
jira_reader.py script (including --issue, --include-comments, --jql,
--fetch-details, --graph, and custom limits). Additionally, if you want
Cursor-friendly examples, add separate repo-root-relative variants (e.g.,
"python3 plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py ...")
rather than replacing the CLAUDE_SKILL_DIR form, and ensure both forms are
clearly labeled.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: bfae16da-1d82-4064-9b9a-534d397fe0c0
📒 Files selected for processing (3)
plugins/docs-tools/.claude-plugin/plugin.jsonplugins/docs-tools/skills/jira-reader/SKILL.mdplugins/docs-tools/skills/jira-reader/scripts/jira_reader.py
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py (2)
143-154:⚠️ Potential issue | 🟠 MajorApply REST API v3 to Cloud only; keep self-hosted on default/v2.
Line 143–154 sets
rest_api_version=3for both branches, which can break Jira Server/Data Center connections.Using official Atlassian and jira-python docs: does Jira Server/Data Center support `/rest/api/3`, or should self-hosted clients use v2/default while Cloud uses v3?Suggested fix
- options = {"rest_api_version": "3"} - if "atlassian.net" in server: + options = {"rest_api_version": "3"} email = os.environ.get("JIRA_EMAIL") if not email: raise ValueError( "JIRA_EMAIL environment variable not set. " "Required for Atlassian Cloud. Add it to ~/.env" ) self.jira = JIRA(server=server, basic_auth=(email, token), options=options) else: - self.jira = JIRA(server=server, token_auth=token, options=options) + self.jira = JIRA(server=server, token_auth=token)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py` around lines 143 - 154, The code currently forces options = {"rest_api_version": "3"} for both cloud and self-hosted; change it so REST API v3 is applied only for Atlassian Cloud: when "atlassian.net" in server set options = {"rest_api_version": "3"} and use it in the JIRA(...) call for the cloud branch (where basic_auth is used), but for the else/self-hosted branch either omit rest_api_version or keep options as None/empty (so the default/v2 is used) before calling JIRA(server=server, token_auth=token, options=options); update the code around the options variable and the two self.jira assignments (the JIRA(...) calls) accordingly.
63-64:⚠️ Potential issue | 🟠 MajorPreserve hyperlink URLs from ADF
linkmarks in text nodes.Line 63–64 returns only
node["text"], so labeled links lose their destination URL in descriptions/comments.According to Atlassian Document Format documentation, are hyperlinks represented as `link` marks on `text` nodes with URL in `marks[].attrs.href`?Proposed fix
if node_type == "text": - return node.get("text", "") + text = node.get("text", "") + for mark in node.get("marks", []): + if mark.get("type") == "link": + href = mark.get("attrs", {}).get("href", "") + if href and href != text: + return f"{text} ({href})" + return text🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py` around lines 63 - 64, The text-node handler currently returns only node.get("text", "") which discards any ADF link marks; update the branch that checks node_type == "text" to inspect node.get("marks", []) for a mark with "type" == "link" and an href in mark.get("attrs", {}).get("href"), and preserve the URL (for example by returning a representation that includes both the label and href or by formatting as a markdown/explicit link) so labeled links keep their destination; adjust the logic in the function that processes text nodes (the node_type == "text" branch) to extract marks and include mark.attrs.href when present.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py`:
- Around line 13-16: Update the usage examples that currently reference the
environment variable ${CLAUDE_SKILL_DIR} (the lines showing "python3
${CLAUDE_SKILL_DIR}/scripts/jira_reader.py ...") to use a skill-relative path
instead, e.g., "python3 scripts/jira_reader.py ..." for all examples (including
the variants with --issue, --include-comments, --jql, and --graph) so same-skill
script references follow the guideline.
---
Duplicate comments:
In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py`:
- Around line 143-154: The code currently forces options = {"rest_api_version":
"3"} for both cloud and self-hosted; change it so REST API v3 is applied only
for Atlassian Cloud: when "atlassian.net" in server set options =
{"rest_api_version": "3"} and use it in the JIRA(...) call for the cloud branch
(where basic_auth is used), but for the else/self-hosted branch either omit
rest_api_version or keep options as None/empty (so the default/v2 is used)
before calling JIRA(server=server, token_auth=token, options=options); update
the code around the options variable and the two self.jira assignments (the
JIRA(...) calls) accordingly.
- Around line 63-64: The text-node handler currently returns only
node.get("text", "") which discards any ADF link marks; update the branch that
checks node_type == "text" to inspect node.get("marks", []) for a mark with
"type" == "link" and an href in mark.get("attrs", {}).get("href"), and preserve
the URL (for example by returning a representation that includes both the label
and href or by formatting as a markdown/explicit link) so labeled links keep
their destination; adjust the logic in the function that processes text nodes
(the node_type == "text" branch) to extract marks and include mark.attrs.href
when present.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: da6dc163-d864-4c5a-a06f-1e76d19cf82a
📒 Files selected for processing (2)
plugins/docs-tools/skills/jira-reader/SKILL.mdplugins/docs-tools/skills/jira-reader/scripts/jira_reader.py
✅ Files skipped from review due to trivial changes (1)
- plugins/docs-tools/skills/jira-reader/SKILL.md
bburt-rh
force-pushed
the
jira-reader-changes
branch
from
c93c65b to
f6ef2fe
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py`:
- Around line 119-121: The adf_to_text fallback currently only recurses into
content and therefore drops ADF leaf nodes like inlineCard; update adf_to_text
to detect when node.get("type") == "inlineCard" and return the smart-link URL
from node.get("attrs", {}).get("url", "") (or empty string if missing) before
falling back to iterating children, so inlineCard URLs are preserved in the
serialized output.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 478c551d-6a65-47fe-9013-ddfaa77f5c7e
📒 Files selected for processing (2)
plugins/docs-tools/skills/jira-reader/SKILL.mdplugins/docs-tools/skills/jira-reader/scripts/jira_reader.py
✅ Files skipped from review due to trivial changes (1)
- plugins/docs-tools/skills/jira-reader/SKILL.md
The jira Python library defaults to Atlassian REST API v2. Atlassian's
current version is v3 and v2 may be deprecated. This migrates the
jira-reader skill by passing options={"rest_api_version": "3"} to both
JIRA() constructor paths and adding an adf_to_text() converter for the
description and comment body fields, which v3 returns as Atlassian
Document Format (ADF) JSON instead of wiki markup.
Also fixes SKILL.md to use relative script paths per repo conventions.
Closes redhat-documentation#111
bburt-rh
force-pushed
the
jira-reader-changes
branch
from
f6ef2fe to
6a34e4e
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py (2)
119-121:⚠️ Potential issue | 🟠 MajorPreserve
inlineCardURLs before generic fallback traversal.Line 119-121 fallback currently drops ADF leaf smart links (
inlineCard) because they have nocontent; this can remove important URLs from descriptions/comments.Suggested fix
+ if node_type == "inlineCard": + return node.get("attrs", {}).get("url", "") + # doc, panel, expand, mediaSingle, etc.: recurse into children parts = [adf_to_text(child) for child in content] return "".join(parts)According to Atlassian ADF docs for `inlineCard`, is the destination URL stored in `attrs.url`, and should text serializers preserve it for plain-text output?🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py` around lines 119 - 121, The fallback traversal in adf_to_text currently iterates children and thus drops ADF leaf smart links like inlineCard because they have no content; update adf_to_text to check for node type "inlineCard" (and similar card types if present) before the generic child traversal and return node.get("attrs", {}).get("url", "") so the destination URL is preserved in the plain-text output instead of being lost.
13-16:⚠️ Potential issue | 🟡 MinorUse skill-relative paths in usage examples.
Line 13-16 still reference
${CLAUDE_SKILL_DIR}/scripts/jira_reader.pyinstead of a same-skill relative path.Suggested fix
- python3 ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --issue INFERENG-5233 - python3 ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --issue INFERENG-5233 --include-comments - python3 ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --jql "project=INFERENG AND fixVersion='3.4'" - python3 ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --graph INFERENG-5233 + python3 scripts/jira_reader.py --issue INFERENG-5233 + python3 scripts/jira_reader.py --issue INFERENG-5233 --include-comments + python3 scripts/jira_reader.py --jql "project=INFERENG AND fixVersion='3.4'" + python3 scripts/jira_reader.py --graph INFERENG-5233As per coding guidelines, "For same skill script references: use paths relative to the skill directory (e.g.,
python3 scripts/foo.py)".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py` around lines 13 - 16, The usage examples in jira_reader.py use the environment variable ${CLAUDE_SKILL_DIR} instead of skill-relative paths; update all example invocations (the four lines showing the python3 commands) to use relative paths under the same skill (e.g., "python3 scripts/jira_reader.py ...") so they follow the guideline for same-skill script references; modify the examples in the top-of-file usage block in plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py to replace "${CLAUDE_SKILL_DIR}/scripts/jira_reader.py" with the skill-relative "scripts/jira_reader.py" variants for each shown flag (--issue, --include-comments, --jql, --graph).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py`:
- Around line 119-121: The fallback traversal in adf_to_text currently iterates
children and thus drops ADF leaf smart links like inlineCard because they have
no content; update adf_to_text to check for node type "inlineCard" (and similar
card types if present) before the generic child traversal and return
node.get("attrs", {}).get("url", "") so the destination URL is preserved in the
plain-text output instead of being lost.
- Around line 13-16: The usage examples in jira_reader.py use the environment
variable ${CLAUDE_SKILL_DIR} instead of skill-relative paths; update all example
invocations (the four lines showing the python3 commands) to use relative paths
under the same skill (e.g., "python3 scripts/jira_reader.py ...") so they follow
the guideline for same-skill script references; modify the examples in the
top-of-file usage block in
plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py to replace
"${CLAUDE_SKILL_DIR}/scripts/jira_reader.py" with the skill-relative
"scripts/jira_reader.py" variants for each shown flag (--issue,
--include-comments, --jql, --graph).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 02247291-1b9f-4aaa-a6a3-6a05d78f1002
📒 Files selected for processing (4)
plugins/docs-tools/.claude-plugin/plugin.jsonplugins/docs-tools/skills/jira-reader/SKILL.mdplugins/docs-tools/skills/jira-reader/scripts/jira_reader.pyscripts/deps.json
✅ Files skipped from review due to trivial changes (2)
- plugins/docs-tools/.claude-plugin/plugin.json
- plugins/docs-tools/skills/jira-reader/SKILL.md
Add inlineCard handler to adf_to_text so smart-link URLs are preserved in plain-text output. Regenerate deps.json after rebase picked up create_mr.sh -> create_mr.py migration.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py`:
- Around line 119-120: The inlineCard branch only returns attrs.url but should
fall back to attrs.data when url is missing; update the inlineCard handling in
jira_reader.py to read attrs = node.get("attrs", {}) and return attrs.get("url")
or, if absent, inspect attrs.get("data") (handle both dict and JSON-string
forms) and extract the link field (e.g., data.get("url") or data.get("id") as
appropriate), so inlineCard nodes using JSON-LD in attrs.data are correctly
converted.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: ed4069f6-6bb7-4b17-b8e6-99bcbe5c560b
📒 Files selected for processing (1)
plugins/docs-tools/skills/jira-reader/scripts/jira_reader.py
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
1 participant
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.
Summary
options={"rest_api_version": "3"}to bothJIRA()constructor paths (Atlassian Cloud and self-hosted)adf_to_text()function to convert Atlassian Document Format (ADF) JSON to plain text fordescriptionandcomment.bodyfields, which v3 returns as ADF instead of wiki markupscripts/jira_reader.pyrelative paths instead of${CLAUDE_SKILL_DIR}Motivation
Atlassian REST API v3 is the current version. The
jiraPython library defaults to v2, which may be deprecated. See #111.What changed
jira_reader.pyoptions={"rest_api_version": "3"}to both JIRA constructors; addedadf_to_text()converter; applied converter to all 3 locations reading description/comment bodySKILL.md${CLAUDE_SKILL_DIR}refs withscripts/relative pathsplugin.jsonADF converter handles
text,hardBreak,mention,emojiparagraph,heading,blockquote,rulebulletList,orderedList,listItemcodeBlock,tablepanel,expand, etc.)Test plan
--issuereturns readable plain-text description (not raw ADF JSON)--include-commentsreturns readable comment bodies--graphdescription field is converted--jqlsummary mode still works (no description field in summaries)Closes jira-reader skill uses Atlassian REST API v2, needs migration to v3 #111
Made by Cursor
Summary by CodeRabbit
New Features
Documentation
Chores