docs: expand JIRA integration instructions #23
Conversation
WalkthroughDocumentation update to the JIRA integration section in README.md: rewrites description to emphasize live JIRA data usage, adds a step-by-step configuration guide with environment variables, notes 5-minute caching, and clarifies branch ranking behavior. No code changes. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Pre-merge checks (3 passed)✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
Thank you for improving the JIRA integration documentation! The changes make the setup process much clearer with step-by-step instructions. I've suggested a few enhancements:
- Adding security best practices for credential storage
- Including an example of the expected branch name format with JIRA issue key
- Adding cache-related details for troubleshooting
Overall, this is a good improvement to the documentation that will help users set up the JIRA integration more easily.
| 2. **Export the required environment variables** | ||
|
|
||
| ```bash | ||
| export JIRA_API_TOKEN="your-token" | ||
| export JIRA_SUBDOMAIN="acme" # for https://acme.atlassian.net |
There was a problem hiding this comment.
Consider adding a note about security best practices for storing API tokens. Environment variables in shell profiles are visible to all processes run by that user, which could be a security risk1. Consider recommending a secure credential manager or encrypted environment file as the preferred approach.
| 2. **Export the required environment variables** | |
| ```bash | |
| export JIRA_API_TOKEN="your-token" | |
| export JIRA_SUBDOMAIN="acme" # for https://acme.atlassian.net | |
| # Recommended: Use a secure credential manager or encrypted .env file | |
| # Store these credentials in an encrypted .env file, not in your shell profile | |
| export JIRA_API_TOKEN="your-token" | |
| export JIRA_SUBDOMAIN="acme" # for | |
| export JIRA_EMAIL_ADDRESS="you@example.com" |
Footnotes
-
CWE-522: Insufficiently Protected Credentials - https://cwe.mitre.org/data/definitions/522.html ↩
| ``` | ||
|
|
||
| ## JIRA Integration | ||
| The `branch:recent` command can be run with the `--jira` flag to refine the ordering of the results using live data from JIRA. When your branch names include a JIRA issue key, branches tied to active issues you've updated recently appear closer to the top. |
There was a problem hiding this comment.
Consider adding a brief example of a valid branch name format that includes a JIRA issue key to help users understand the expected format.
| export JIRA_EMAIL_ADDRESS="you@example.com" | ||
| ``` | ||
|
|
||
| Add these to your shell profile or `.env` file so `git-ninja` can authenticate with JIRA. |
There was a problem hiding this comment.
Consider mentioning the cache location and whether there's a way to clear it if needed. This information would be helpful for troubleshooting.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
138-138: Line length
Expected: 160; Actual: 256
(MD013, line-length)
🔇 Additional comments (3)
README.md (3)
140-140: Section header reads wellClear entry point for users. No changes needed.
146-147: Good step breakdownStep title is clear. Proceeding comments focus on the env block below.
156-160: Usage example looks goodCommand and flag are correct and consistent with earlier context.
| The `branch:recent` command can be run with the `--jira` flag to refine the ordering of the results using live data from JIRA. When your branch names include a JIRA issue key, branches tied to active issues you've updated recently appear closer to the top. | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Wrap long line, tighten wording, and consider Atlassian style (“Jira”)
Line 138 violates MD013 (256 chars). Also, Atlassian brands it “Jira”. Suggest wrapping and tightening copy.
-The `branch:recent` command can be run with the `--jira` flag to refine the ordering of the results using live data from JIRA. When your branch names include a JIRA issue key, branches tied to active issues you've updated recently appear closer to the top.
+The `branch:recent` command can be run with the `--jira` flag to refine ordering using live data from Jira.
+
+When branch names include a Jira issue key, branches tied to issues you updated recently appear near the top.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The `branch:recent` command can be run with the `--jira` flag to refine the ordering of the results using live data from JIRA. When your branch names include a JIRA issue key, branches tied to active issues you've updated recently appear closer to the top. | |
| The `branch:recent` command can be run with the `--jira` flag to refine ordering using live data from Jira. | |
| When branch names include a Jira issue key, branches tied to issues you updated recently appear near the top. |
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
138-138: Line length
Expected: 160; Actual: 256
(MD013, line-length)
🤖 Prompt for AI Agents
In README.md around lines 138-139, the long sentence exceeds MD013 and uses
“JIRA”; reword and wrap to shorter lines and use Atlassian’s “Jira”
capitalization. Replace the paragraph with a tighter sentence that mentions the
branch:recent command supports the --jira flag to prioritize branches whose
names include a Jira issue key so branches tied to recently updated issues
appear higher, then hard-wrap the text to a sensible line length (e.g., 80
chars) to satisfy MD013.
| 1. **Create an API token** | ||
| - Visit <https://id.atlassian.com/manage-profile/security/api-tokens>. | ||
| - Click **Create API token** and copy the generated value. | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Cloud vs Server: clarify scope
If this integration is Cloud-only, say so. If Server/DC is supported, add instructions for base URL/auth differences.
🤖 Prompt for AI Agents
In README.md around lines 142 to 145, the API token creation step doesn't state
whether the integration is Cloud-only or supports Server/DC and lacks guidance
on differing base URL and auth for Server/DC; update the documentation to
explicitly state the supported platforms (Cloud only or Cloud + Server/DC) and,
if Server/DC is supported, add a short subsection explaining the different base
URL format and any alternate authentication steps (e.g., self-hosted instance
URL, use of personal access tokens or different endpoints, and where to
configure the base URL), plus a clear note when the linked Atlassian API token
page applies only to Cloud.
| export JIRA_API_TOKEN="your-token" | ||
| export JIRA_SUBDOMAIN="acme" # for https://acme.atlassian.net | ||
| export JIRA_EMAIL_ADDRESS="you@example.com" | ||
| ``` |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Env var names: verify against code; add .env example and gitignore note
- Please verify these exact names match the code.
- Add a .env example to reduce setup friction and ensure tokens aren’t committed.
Verification script:
Proposed README additions:
export JIRA_EMAIL_ADDRESS="you@example.com"- Example
.envfile: -
- JIRA_API_TOKEN=your-token
- JIRA_SUBDOMAIN=acme
- JIRA_EMAIL_ADDRESS=you@example.com
-
- Add these to your shell profile or
.envfile sogit-ninjacan authenticate with JIRA.
And add a note to keep `.env` out of version control:
```diff
-Add these to your shell profile or `.env` file so `git-ninja` can authenticate with JIRA.
+Add these to your shell profile or `.env` file so `git-ninja` can authenticate with JIRA. Do not commit `.env`; add it to `.gitignore`.
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Confirm env var names used in code
rg -nP '\bJIRA_(API_TOKEN|SUBDOMAIN|EMAIL_ADDRESS)\b' -C2
# Find Jira flag and any cache TTL mentions
rg -nP '\b--jira\b' -C2
rg -nP '(cache|ttl).*(5 ?min|5m|300s)' --type=go -C3 || trueLength of output: 2569
Env var names verified — add .env example & .gitignore note
Verified README env names match code: JIRA_API_TOKEN, JIRA_SUBDOMAIN, JIRA_EMAIL_ADDRESS (used in lib/integrations/jira/jira.go; cmd/listRecentBranches.go; cmd/jira/issues.go).
-
Add a short Example .env to README:
JIRA_API_TOKEN=your-token
JIRA_SUBDOMAIN=acme
JIRA_EMAIL_ADDRESS=you@example.com -
Add: "Do not commit .env; add .env to .gitignore."
🤖 Prompt for AI Agents
In README.md around lines 149 to 152, update the environment variable section to
include a short Example .env block showing JIRA_API_TOKEN=your-token,
JIRA_SUBDOMAIN=acme, JIRA_EMAIL_ADDRESS=you@example.com, and add a short note
instructing not to commit .env files and to add .env to .gitignore; also create
or update the repository .gitignore to include a .env entry so developers don't
accidentally commit secrets.
| export JIRA_EMAIL_ADDRESS="you@example.com" | ||
| ``` | ||
|
|
||
| Add these to your shell profile or `.env` file so `git-ninja` can authenticate with JIRA. |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Mention local lint precondition and .env.example
PR notes show “task lint” fails if no .env* exists. Add a tip to create .env (or include a .env.example) to satisfy the precondition.
-Add these to your shell profile or `.env` file so `git-ninja` can authenticate with JIRA.
+Add these to your shell profile or `.env` file so `git-ninja` can authenticate with JIRA.
+
+Tip: if your local `task lint` requires an `.env`, you can create one:
+```bash
+touch .env
+```
+Consider adding a tracked `.env.example` with placeholder values.🤖 Prompt for AI Agents
In README.md around line 154, the instructions tell users to add JIRA auth
variables but don't mention that the repo's lint task requires a local `.env*`
to exist; update this line to add a short precondition note telling developers
to create an empty `.env` (e.g. touch .env) before running local lint or CI, and
recommend adding a tracked `.env.example` with placeholder values in the repo to
document required keys and make onboarding simpler.
| ``` | ||
|
|
||
| To enable the JIRA integration, set the `JIRA_API_TOKEN`, `JIRA_SUBDOMAIN` and `JIRA_EMAIL_ADDRESS` environment variables. | ||
| Results are cached for five minutes to avoid repeated API calls. Tickets with higher numbers that have been updated recently are ranked above older or inactive issues. |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Avoid implying numeric issue bias; confirm caching details
Rephrase to avoid “higher numbers” (issue numbers aren’t priority). Also confirm the cache TTL is exactly 5 minutes and whether it’s configurable; if configurable, document the flag/env.
-Results are cached for five minutes to avoid repeated API calls. Tickets with higher numbers that have been updated recently are ranked above older or inactive issues.
+Results are cached for 5 minutes to avoid repeated API calls.
+Recently updated issues rank higher; inactive ones rank lower.
+If cache TTL is configurable, document the flag or env var here.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Results are cached for five minutes to avoid repeated API calls. Tickets with higher numbers that have been updated recently are ranked above older or inactive issues. | |
| Results are cached for 5 minutes to avoid repeated API calls. | |
| Recently updated issues rank higher; inactive ones rank lower. | |
| If cache TTL is configurable, document the flag or env var here. |
🤖 Prompt for AI Agents
In README.md around line 162, the sentence implies a numeric bias by saying
“higher numbers” and asserts a five-minute cache TTL without stating whether
it’s configurable; change the wording to remove any suggestion that issue number
implies priority (e.g., “more recently updated tickets are ranked above older or
inactive issues”), verify the cache TTL value in the code/config, and update the
doc to state the exact TTL and whether it’s configurable; if configurable,
document the config flag or environment variable name and default value,
otherwise state the TTL is fixed at 5 minutes.
This pull request improves the documentation for the JIRA integration in the
README.mdfile, making it more detailed and user-friendly. The update provides step-by-step configuration instructions and clarifies how the--jiraflag affects branch ordering.Documentation improvements:
README.mdto include clear, step-by-step setup instructions for creating an API token, setting environment variables, and running the command with the--jiraflag.--jiraflag affects branch ordering and added information about result caching and ranking logic.Summary by CodeRabbit