— name: jira-integration description: 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. origin: ECC — # Jira Integration Skill Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both **MCP-based** (recommended) and **direct REST API** approaches. ## When to Activate – Fetching a Jira ticket to understand requirements – Extracting testable acceptance criteria from a ticket – Adding progress comments to a Jira issue – Transitioning a ticket status (To Do → In Progress → Done) – Linking merge requests or branches to a Jira issue – Searching for issues by JQL query ## Prerequisites ### Option A: MCP Server (Recommended) Install the `mcp-atlassian` MCP server. This exposes Jira tools directly to your AI agent. **Requirements:** – Python 3.10+ – `uvx` (from `uv`), installed via your package manager or the official `uv` installation documentation **Add to your MCP config** (e.g., `~/.claude.json` → `mcpServers`): “`json { "jira": { "command": "uvx", "args": ["mcp-atlassian==0.21.0"], "env": { "JIRA_URL": "https://YOUR_ORG.atlassian.net", "JIRA_EMAIL": "[email protected]", "JIRA_API_TOKEN": "your-api-token" }, "description": "Jira issue tracking — search, create, update, comment, transition" } } “` > **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. **To get a Jira API token:** 1. Go to <https://id.atlassian.com/manage-profile/security/api-tokens> 2. Click **Create API token** 3. Copy the token — store it in your environment, never in source code ### Option B: Direct REST API If MCP is not available, use the Jira REST API v3 directly via `curl` or a helper script. **Required environment variables:** | Variable | Description | |———-|————-| | `JIRA_URL` | Your Jira instance URL (e.g., `https://yourorg.atlassian.net`) | | `JIRA_EMAIL` | Your Atlassian account email | | `JIRA_API_TOKEN` | API token from id.atlassian.com | Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo. ## MCP Tools Reference When the `mcp-atlassian` MCP server is configured, these tools are available: | Tool | Purpose | Example | |——|———|———| | `jira_search` | JQL queries | `project = PROJ AND status = "In Progress"` | | `jira_get_issue` | Fetch full issue details by key | `PROJ-1234` | | `jira_create_issue` | Create issues (Task, Bug, Story, Epic) | New bug report | | `jira_update_issue` | Update fields (summary, description, assignee) | Change assignee | | `jira_transition_issue` | Change status | Move to "In Review" | | `jira_add_comment` | Add comments | Progress update | | `jira_get_sprint_issues` | List issues in a sprint | Active sprint review | | `jira_create_issue_link` | Link issues (Blocks, Relates to) | Dependency tracking | | `jira_get_issue_development_info` | See linked PRs, branches, commits | Dev context | > **Tip:** Always call `jira_get_transitions` before transitioning — transition IDs vary per project workflow. ## Direct REST API Reference ### Fetch a Ticket “`bash curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ -H "Content-Type: application/json" \ "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{ key: .key, summary: .fields.summary, status: .fields.status.name, priority: .fields.priority.name, type: .fields.issuetype.name, assignee: .fields.assignee.displayName, labels: .fields.labels, description: .fields.description }' “` ### Fetch Comments “`bash curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ -H "Content-Type: application/json" \ "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | { author: .author.displayName, created: .created[:10], body: .body }' “` ### Add a Comment “`bash curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "body": { "version": 1, "type": "doc", "content": [{ "type": "paragraph", "content": [{"type": "text", "text": "Your comment here"}] }] } }' \ "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment" “` ### Transition a Ticket “`bash # 1. Get available transitions curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}' # 2. Execute transition (replace TRANSITION_ID) curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"transition": {"id": "TRANSITION_ID"}}' \ "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" “` ### Search with JQL “`bash curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ –data-urlencode "jql=project = PROJ AND status = 'In Progress'" \ "$JIRA_URL/rest/api/3/search" “` ## Analyzing a Ticket When retrieving a ticket for development or test automation, extract: ### 1. Testable Requirements – **Functional requirements** — What the feature does – **Acceptance criteria** — Conditions that must be met – **Testable behaviors** — Specific actions and expected outcomes – **User roles** — Who uses this feature and their permissions – **Data requirements** — What data is needed – **Integration points** — APIs, services, or systems involved ### 2. Test Types Needed – **Unit tests** — Individual functions and utilities – **Integration tests** — API endpoints and service interactions – **E2E tests** — User-facing UI flows – **API tests** — Endpoint contracts and error handling ### 3. Edge Cases & Error Scenarios – Invalid inputs (empty, too long, special characters) – Unauthorized access – Network failures or timeouts – Concurrent users or race conditions – Boundary conditions – Missing or null data – State transitions (back navigation, refresh, etc.) ### 4. Structured Analysis Output “` Ticket: PROJ-1234 Summary: [ticket title] Status: [current status] Priority: [High/Medium/Low] Test Types: Unit, Integration, E2E Requirements: 1. [requirement 1] 2. [requirement 2] Acceptance Criteria: – [ ] [criterion 1] – [ ] [criterion 2] Test Scenarios: – Happy Path: [description] – Error Case: [description] – Edge Case: [description] Test Data Needed: – [data item 1] – [data item 2] Dependencies: – [dependency 1] – [dependency 2] “` ## Updating Tickets ### When to Update | Workflow Step | Jira Update | |—|—| | Start work | Transition to "In Progress" | | Tests written | Comment with test coverage summary | | Branch created | Comment with branch name | | PR/MR created | Comment with link, link issue | | Tests passing | Comment with results summary | | PR/MR merged | Transition to "Done" or "In Review" | ### Comment Templates **Starting Work:** “` Starting implementation for this ticket. Branch: feat/PROJ-1234-feature-name “` **Tests Implemented:** “` Automated tests implemented: Unit Tests: – [test file 1] — [what it covers] – [test file 2] — [what it covers] Integration Tests: – [test file] — [endpoints/flows covered] All tests passing locally. Coverage: XX% “` **PR Created:** “` Pull request created: [PR Title](https://github.com/org/repo/pull/XXX) Ready for review. “` **Work Complete:** “` Implementation complete. PR merged: [link] Test results: All passing (X/Y) Coverage: XX% “` ## Security Guidelines – **Never hardcode** Jira API tokens in source code or skill files – **Always use** environment variables or a secrets manager – **Add `.env`** to `.gitignore` in every project – **Rotate tokens** immediately if exposed in git history – **Use least-privilege** API tokens scoped to required projects – **Validate** that credentials are set before making API calls — fail fast with a clear message ## Troubleshooting | Error | Cause | Fix | |—|—|—| | `401 Unauthorized` | Invalid or expired API token | Regenerate at id.atlassian.com | | `403 Forbidden` | Token lacks project permissions | Check token scopes and project access | | `404 Not Found` | Wrong ticket key or base URL | Verify `JIRA_URL` and ticket key | | `spawn uvx ENOENT` | IDE cannot find `uvx` on PATH | Use full path (e.g., `~/.local/bin/uvx`) or set PATH in `~/.zprofile` | | Connection timeout | Network/VPN issue | Check VPN connection and firewall rules | ## Best Practices – Update Jira as you go, not all at once at the end – Keep comments concise but informative – Link rather than copy — point to PRs, test reports, and dashboards – Use @mentions if you need input from others – Check linked issues to understand full feature scope before starting – If acceptance criteria are vague, ask for clarification before writing code