QA Jira Integration
Purpose
Integrate QA workflow with Jira for issue tracking and project management. Create and update issues, manage epics and sprints, link issues to requirements and test cases, and sync with Xray/Zephyr for test management. Use Jira REST API or Atlassian MCP when available.
Features
| Feature |
Description |
| Create/update issues |
Bug, Story, Task, Sub-task with full field mapping |
| Manage epics and sprints |
Create epics, add issues to sprints, manage backlog |
| Link issues |
Link to requirements, test cases, parent issues |
| Xray/Zephyr integration |
Sync test cases, test executions, traceability |
| JQL queries |
Search and report on issues by project, status, assignee |
| Transition management |
Move issues through workflow states (To Do → In Progress → Done) |
Authentication
| Variable |
Description |
JIRA_BASE_URL |
Jira instance URL (e.g., https://your-domain.atlassian.net) |
JIRA_API_TOKEN |
API token from Atlassian account settings |
JIRA_EMAIL |
Email for the Atlassian account (used with API token) |
Basic Auth: Authorization: Basic base64(email:api_token)
See references/api-patterns.md for request examples.
Key API Patterns
| Operation |
Method |
Endpoint |
| Create issue |
POST |
/rest/api/3/issue |
| Search (JQL) |
GET |
/rest/api/3/search?jql=... |
| Get issue |
GET |
/rest/api/3/issue/{key} |
| Update issue |
PUT |
/rest/api/3/issue/{key} |
| Transition |
POST |
/rest/api/3/issue/{key}/transitions |
| Link issues |
POST |
/rest/api/3/issueLink |
| Add comment |
POST |
/rest/api/3/issue/{key}/comment |
| Add attachment |
POST |
/rest/api/3/issue/{key}/attachments |
Integration with qa-bug-ticket-creator
When qa-bug-ticket-creator produces a bug report:
- Map fields — Use
references/field-mapping.md to map bug report fields to Jira issue fields
- Create Jira Bug — POST to
/rest/api/3/issue with issuetype: { name: "Bug" }
- Link to test — If test case key exists, create issue link (e.g., "tests" or "blocks")
- Optional — Invoke qa-task-creator for linked fix task; create as Jira Task/Sub-task under same project
Integration with qa-task-creator
When qa-task-creator produces a task:
- Map fields — Map task type to Jira issuetype (Story, Task, Sub-task)
- Create Jira issue — POST with appropriate project key and issuetype
- Link to parent — If task references a bug, use
parent for Sub-task or issue link for Task
- Sprint assignment — Add to sprint via
fields.customfield_XXXX (sprint field ID varies by instance)
Trigger Phrases
- "Create Jira issue from [bug report / task]"
- "File bug in Jira for [test failure]"
- "Add issue to sprint [name]"
- "Search Jira for [JQL]"
- "Transition [PROJ-123] to In Progress"
- "Link [PROJ-123] to test case [PROJ-456]"
- "Sync test results to Xray"
Workflow
- Auth — Load
JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN from .env
- Map — Use
references/field-mapping.md for QA → Jira field mapping
- Create/Update — Call REST API or Atlassian MCP
- Link — Create issue links, add to epic/sprint as needed
- Report — Use JQL for dashboards and status reports
Scope
Can do (autonomous):
- Create Bug, Story, Task, Sub-task via REST API
- Search issues with JQL
- Transition issues through workflow
- Link issues (parent-child, blocks, relates to)
- Add comments and attachments
- Map QA bug/task output to Jira fields per
references/field-mapping.md
- Integrate with qa-bug-ticket-creator and qa-task-creator for issue creation
Cannot do (requires confirmation):
- Create issues in projects without configured access
- Override user-specified assignee or sprint
- Delete or bulk-modify issues
Will not do (out of scope):
- Modify Jira project configuration or workflows
- Create custom fields (admin-only)
- Execute tests or modify application code
Quality Checklist
Troubleshooting
| Symptom |
Likely Cause |
Fix |
| 401 Unauthorized |
Invalid token or email |
Regenerate API token; verify JIRA_EMAIL matches token owner |
| 404 on create |
Wrong project key or endpoint |
Verify JIRA_BASE_URL; check project key exists |
| 400 Bad Request |
Invalid field value |
Check references/field-mapping.md; verify custom field IDs |
| Transition fails |
Invalid transition ID |
GET /rest/api/3/issue/{key}/transitions to list valid transitions |
| Xray sync fails |
Xray not installed or wrong project |
Verify Xray app; use Xray-specific endpoints per references/xray-integration.md |
| Field not found |
Custom field ID wrong |
Use GET /rest/api/3/field to list field IDs |
Reference Files
| Topic |
File |
| Jira REST API patterns |
references/api-patterns.md |
| QA → Jira field mapping |
references/field-mapping.md |
| Xray/Zephyr integration |
references/xray-integration.md |
1---2name: qa-jira-integration3description: Jira integration for creating issues, managing epics/sprints, syncing with Xray/Zephyr test management, and tracking QA workflows via REST API or Atlassian MCP.4---56# QA Jira Integration78## Purpose910Integrate QA workflow with Jira for issue tracking and project management. Create and update issues, manage epics and sprints, link issues to requirements and test cases, and sync with Xray/Zephyr for test management. Use Jira REST API or Atlassian MCP when available.1112## Features1314| Feature | Description |15| ------- | ----------- |16| **Create/update issues** | Bug, Story, Task, Sub-task with full field mapping |17| **Manage epics and sprints** | Create epics, add issues to sprints, manage backlog |18| **Link issues** | Link to requirements, test cases, parent issues |19| **Xray/Zephyr integration** | Sync test cases, test executions, traceability |20| **JQL queries** | Search and report on issues by project, status, assignee |21| **Transition management** | Move issues through workflow states (To Do → In Progress → Done) |2223## Authentication2425| Variable | Description |26| -------- | ----------- |27| `JIRA_BASE_URL` | Jira instance URL (e.g., `https://your-domain.atlassian.net`) |28| `JIRA_API_TOKEN` | API token from [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) |29| `JIRA_EMAIL` | Email for the Atlassian account (used with API token) |3031**Basic Auth:** `Authorization: Basic base64(email:api_token)`3233See `references/api-patterns.md` for request examples.3435## Key API Patterns3637| Operation | Method | Endpoint |38| --------- | ------ | -------- |39| Create issue | POST | `/rest/api/3/issue` |40| Search (JQL) | GET | `/rest/api/3/search?jql=...` |41| Get issue | GET | `/rest/api/3/issue/{key}` |42| Update issue | PUT | `/rest/api/3/issue/{key}` |43| Transition | POST | `/rest/api/3/issue/{key}/transitions` |44| Link issues | POST | `/rest/api/3/issueLink` |45| Add comment | POST | `/rest/api/3/issue/{key}/comment` |46| Add attachment | POST | `/rest/api/3/issue/{key}/attachments` |4748## Integration with qa-bug-ticket-creator4950When qa-bug-ticket-creator produces a bug report:51521. **Map fields** — Use `references/field-mapping.md` to map bug report fields to Jira issue fields532. **Create Jira Bug** — POST to `/rest/api/3/issue` with `issuetype: { name: "Bug" }`543. **Link to test** — If test case key exists, create issue link (e.g., "tests" or "blocks")554. **Optional** — Invoke qa-task-creator for linked fix task; create as Jira Task/Sub-task under same project5657## Integration with qa-task-creator5859When qa-task-creator produces a task:60611. **Map fields** — Map task type to Jira issuetype (Story, Task, Sub-task)622. **Create Jira issue** — POST with appropriate project key and issuetype633. **Link to parent** — If task references a bug, use `parent` for Sub-task or issue link for Task644. **Sprint assignment** — Add to sprint via `fields.customfield_XXXX` (sprint field ID varies by instance)6566## Trigger Phrases6768- "Create Jira issue from [bug report / task]"69- "File bug in Jira for [test failure]"70- "Add issue to sprint [name]"71- "Search Jira for [JQL]"72- "Transition [PROJ-123] to In Progress"73- "Link [PROJ-123] to test case [PROJ-456]"74- "Sync test results to Xray"7576## Workflow77781. **Auth** — Load `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` from `.env`792. **Map** — Use `references/field-mapping.md` for QA → Jira field mapping803. **Create/Update** — Call REST API or Atlassian MCP814. **Link** — Create issue links, add to epic/sprint as needed825. **Report** — Use JQL for dashboards and status reports8384## Scope8586**Can do (autonomous):**87- Create Bug, Story, Task, Sub-task via REST API88- Search issues with JQL89- Transition issues through workflow90- Link issues (parent-child, blocks, relates to)91- Add comments and attachments92- Map QA bug/task output to Jira fields per `references/field-mapping.md`93- Integrate with qa-bug-ticket-creator and qa-task-creator for issue creation9495**Cannot do (requires confirmation):**96- Create issues in projects without configured access97- Override user-specified assignee or sprint98- Delete or bulk-modify issues99100**Will not do (out of scope):**101- Modify Jira project configuration or workflows102- Create custom fields (admin-only)103- Execute tests or modify application code104105## Quality Checklist106107- [ ] Auth uses env vars; no hardcoded credentials108- [ ] Field mapping follows `references/field-mapping.md`109- [ ] Issue types and project keys validated before create110- [ ] JQL queries are safe (no injection; use parameterization where supported)111- [ ] Links to qa-bug-ticket-creator / qa-task-creator output preserved112- [ ] Xray/Zephyr operations follow `references/xray-integration.md` when used113114## Troubleshooting115116| Symptom | Likely Cause | Fix |117| ------- | ------------ | --- |118| 401 Unauthorized | Invalid token or email | Regenerate API token; verify JIRA_EMAIL matches token owner |119| 404 on create | Wrong project key or endpoint | Verify JIRA_BASE_URL; check project key exists |120| 400 Bad Request | Invalid field value | Check `references/field-mapping.md`; verify custom field IDs |121| Transition fails | Invalid transition ID | GET `/rest/api/3/issue/{key}/transitions` to list valid transitions |122| Xray sync fails | Xray not installed or wrong project | Verify Xray app; use Xray-specific endpoints per `references/xray-integration.md` |123| Field not found | Custom field ID wrong | Use GET `/rest/api/3/field` to list field IDs |124125## Reference Files126127| Topic | File |128| ----- | ---- |129| Jira REST API patterns | `references/api-patterns.md` |130| QA → Jira field mapping | `references/field-mapping.md` |131| Xray/Zephyr integration | `references/xray-integration.md` |
azanir