Jira Integration

1---2name: jira-integration3description: Use this skill when retrieving Jira tickets, analyzing requirements, updating ticket status, adding comments, or transitioning issues. Provides Jira API patterns via MCP or direct REST calls.4origin: ECC5---6 7# Jira Integration Skill8 9Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both **MCP-based** (recommended) and **direct REST API** approaches.10 11## When to Activate12 13- Fetching a Jira ticket to understand requirements14- Extracting testable acceptance criteria from a ticket15- Adding progress comments to a Jira issue16- Transitioning a ticket status (To Do → In Progress → Done)17- Linking merge requests or branches to a Jira issue18- Searching for issues by JQL query19 20## Prerequisites21 22### Option A: MCP Server (Recommended)23 24Install the `mcp-atlassian` MCP server. This exposes Jira tools directly to your AI agent.25 26**Requirements:**27- Python 3.10+28- `uvx` (from `uv`), installed via your package manager or the official `uv` installation documentation29 30**Add to your MCP config** (e.g., `~/.claude.json` → `mcpServers`):31 32```json33{34  "jira": {35    "command": "uvx",36    "args": ["mcp-atlassian==0.21.0"],37    "env": {38      "JIRA_URL": "https://YOUR_ORG.atlassian.net",39      "JIRA_EMAIL": "your.email@example.com",40      "JIRA_API_TOKEN": "your-api-token"41    },42    "description": "Jira issue tracking — search, create, update, comment, transition"43  }44}45```46 47> **Security:** Never hardcode secrets. Prefer setting `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` in your system environment (or a secrets manager). Only use the MCP `env` block for local, uncommitted config files.48 49**To get a Jira API token:**501. Go to <https://id.atlassian.com/manage-profile/security/api-tokens>512. Click **Create API token**523. Copy the token — store it in your environment, never in source code53 54### Option B: Direct REST API55 56If MCP is not available, use the Jira REST API v3 directly via `curl` or a helper script.57 58**Required environment variables:**59 60| Variable | Description |61|----------|-------------|62| `JIRA_URL` | Your Jira instance URL (e.g., `https://yourorg.atlassian.net`) |63| `JIRA_EMAIL` | Your Atlassian account email |64| `JIRA_API_TOKEN` | API token from id.atlassian.com |65 66Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo.67 68## MCP Tools Reference69 70When the `mcp-atlassian` MCP server is configured, these tools are available:71 72| Tool | Purpose | Example |73|------|---------|---------|74| `jira_search` | JQL queries | `project = PROJ AND status = "In Progress"` |75| `jira_get_issue` | Fetch full issue details by key | `PROJ-1234` |76| `jira_create_issue` | Create issues (Task, Bug, Story, Epic) | New bug report |77| `jira_update_issue` | Update fields (summary, description, assignee) | Change assignee |78| `jira_transition_issue` | Change status | Move to "In Review" |79| `jira_add_comment` | Add comments | Progress update |80| `jira_get_sprint_issues` | List issues in a sprint | Active sprint review |81| `jira_create_issue_link` | Link issues (Blocks, Relates to) | Dependency tracking |82| `jira_get_issue_development_info` | See linked PRs, branches, commits | Dev context |83 84> **Tip:** Always call `jira_get_transitions` before transitioning — transition IDs vary per project workflow.85 86## Direct REST API Reference87 88### Fetch a Ticket89 90```bash91curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \92  -H "Content-Type: application/json" \93  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{94    key: .key,95    summary: .fields.summary,96    status: .fields.status.name,97    priority: .fields.priority.name,98    type: .fields.issuetype.name,99    assignee: .fields.assignee.displayName,100    labels: .fields.labels,101    description: .fields.description102  }'103```104 105### Fetch Comments106 107```bash108curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \109  -H "Content-Type: application/json" \110  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {111    author: .author.displayName,112    created: .created[:10],113    body: .body114  }'115```116 117### Add a Comment118 119```bash120curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \121  -H "Content-Type: application/json" \122  -d '{123    "body": {124      "version": 1,125      "type": "doc",126      "content": [{127        "type": "paragraph",128        "content": [{"type": "text", "text": "Your comment here"}]129      }]130    }131  }' \132  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"133```134 135### Transition a Ticket136 137```bash138# 1. Get available transitions139curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \140  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'141 142# 2. Execute transition (replace TRANSITION_ID)143curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \144  -H "Content-Type: application/json" \145  -d '{"transition": {"id": "TRANSITION_ID"}}' \146  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"147```148 149### Search with JQL150 151```bash152curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \153  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \154  "$JIRA_URL/rest/api/3/search"155```156 157## Analyzing a Ticket158 159When retrieving a ticket for development or test automation, extract:160 161### 1. Testable Requirements162- **Functional requirements** — What the feature does163- **Acceptance criteria** — Conditions that must be met164- **Testable behaviors** — Specific actions and expected outcomes165- **User roles** — Who uses this feature and their permissions166- **Data requirements** — What data is needed167- **Integration points** — APIs, services, or systems involved168 169### 2. Test Types Needed170- **Unit tests** — Individual functions and utilities171- **Integration tests** — API endpoints and service interactions172- **E2E tests** — User-facing UI flows173- **API tests** — Endpoint contracts and error handling174 175### 3. Edge Cases & Error Scenarios176- Invalid inputs (empty, too long, special characters)177- Unauthorized access178- Network failures or timeouts179- Concurrent users or race conditions180- Boundary conditions181- Missing or null data182- State transitions (back navigation, refresh, etc.)183 184### 4. Structured Analysis Output185 186```187Ticket: PROJ-1234188Summary: [ticket title]189Status: [current status]190Priority: [High/Medium/Low]191Test Types: Unit, Integration, E2E192 193Requirements:1941. [requirement 1]1952. [requirement 2]196 197Acceptance Criteria:198- [ ] [criterion 1]199- [ ] [criterion 2]200 201Test Scenarios:202- Happy Path: [description]203- Error Case: [description]204- Edge Case: [description]205 206Test Data Needed:207- [data item 1]208- [data item 2]209 210Dependencies:211- [dependency 1]212- [dependency 2]213```214 215## Updating Tickets216 217### When to Update218 219| Workflow Step | Jira Update |220|---|---|221| Start work | Transition to "In Progress" |222| Tests written | Comment with test coverage summary |223| Branch created | Comment with branch name |224| PR/MR created | Comment with link, link issue |225| Tests passing | Comment with results summary |226| PR/MR merged | Transition to "Done" or "In Review" |227 228### Comment Templates229 230**Starting Work:**231```232Starting implementation for this ticket.233Branch: feat/PROJ-1234-feature-name234```235 236**Tests Implemented:**237```238Automated tests implemented:239 240Unit Tests:241- [test file 1] — [what it covers]242- [test file 2] — [what it covers]243 244Integration Tests:245- [test file] — [endpoints/flows covered]246 247All tests passing locally. Coverage: XX%248```249 250**PR Created:**251```252Pull request created:253[PR Title](https://github.com/org/repo/pull/XXX)254 255Ready for review.256```257 258**Work Complete:**259```260Implementation complete.261 262PR merged: [link]263Test results: All passing (X/Y)264Coverage: XX%265```266 267## Security Guidelines268 269- **Never hardcode** Jira API tokens in source code or skill files270- **Always use** environment variables or a secrets manager271- **Add `.env`** to `.gitignore` in every project272- **Rotate tokens** immediately if exposed in git history273- **Use least-privilege** API tokens scoped to required projects274- **Validate** that credentials are set before making API calls — fail fast with a clear message275 276## Troubleshooting277 278| Error | Cause | Fix |279|---|---|---|280| `401 Unauthorized` | Invalid or expired API token | Regenerate at id.atlassian.com |281| `403 Forbidden` | Token lacks project permissions | Check token scopes and project access |282| `404 Not Found` | Wrong ticket key or base URL | Verify `JIRA_URL` and ticket key |283| `spawn uvx ENOENT` | IDE cannot find `uvx` on PATH | Use full path (e.g., `~/.local/bin/uvx`) or set PATH in `~/.zprofile` |284| Connection timeout | Network/VPN issue | Check VPN connection and firewall rules |285 286## Best Practices287 288- Update Jira as you go, not all at once at the end289- Keep comments concise but informative290- Link rather than copy — point to PRs, test reports, and dashboards291- Use @mentions if you need input from others292- Check linked issues to understand full feature scope before starting293- If acceptance criteria are vague, ask for clarification before writing code