QA Linear Integration
Purpose
Integrate QA workflow with Linear for issue tracking and project management. Create and update issues, manage projects and cycles, and sync with qa-bug-ticket-creator and qa-task-creator for end-to-end QA traceability.
Features
| Feature |
Description |
| Create/update issues |
Bug, Story, Task via GraphQL mutations |
| Projects and cycles |
Assign issues to projects; add to cycles (sprints) |
| Labels and priority |
Map severity/priority to Linear labels and priority |
| Issue relations |
Blocks, relates to, duplicates |
| Team assignment |
Assign issues to teams |
| GraphQL API |
Full GraphQL for queries and mutations |
Authentication
Store in .env (never hardcode):
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
- Header:
Authorization: Bearer {LINEAR_API_KEY}
- Linear uses API keys; no Basic Auth. Create keys at Linear → Settings → API.
Key API Patterns
| Operation |
GraphQL |
| Create issue |
mutation { issueCreate(input: {...}) { issue { id identifier url } } } |
| Update issue |
mutation { issueUpdate(id: "...", input: {...}) { issue { ... } } } |
| Query issues |
query { issues(filter: {...}) { nodes { id identifier title state { name } } } } |
| Projects |
query { projects { nodes { id name } } } |
| Teams |
query { teams { nodes { id name key } } } |
| Cycles |
query { cycles(filter: { teamId: { eq: "..." } }) { nodes { id name } } } |
See references/api-patterns.md for full GraphQL examples.
Integration with QA Skills
qa-bug-ticket-creator
When creating a bug report for Linear:
- Input — Bug report from test failure (title, expected/actual, steps, severity, component)
- Map — Use
references/field-mapping.md to map to Linear fields
- Create —
issueCreate with teamId, title, description, priority, labels
- Link — Add "blocks" or "relates to" for related issues when applicable
qa-task-creator
When creating tasks for Linear:
- Input — Task from coverage gap, spec finding, or bug fix request
- Map — Map task type to Linear issue type (Story, Task)
- Create —
issueCreate with project, cycle, labels
- Link — Use
parentId for sub-tasks; "blocks" for fix tasks referencing bugs
Trigger Phrases
- "Create Linear issue for [bug/task description]"
- "Add bug to Linear from test failure"
- "Create Linear story for [feature]"
- "Sync QA tasks to Linear"
- "Linear issue from qa-bug-ticket-creator output"
- "Add to Linear cycle [name]"
- "Query Linear issues by [filter]"
Workflow
- Auth — Load
LINEAR_API_KEY from .env
- Resolve IDs — Query teams, projects, cycles to get IDs (or use user-provided)
- Map fields — Apply
references/field-mapping.md for QA → Linear
- Execute — Run GraphQL mutation (issueCreate, issueUpdate)
- Output — Return issue identifier (e.g.,
BUG-123), URL, and summary
Scope
Can do (autonomous):
- Create and update Linear issues via GraphQL
- Map QA bug/task fields to Linear fields
- Query issues, projects, teams, cycles
- Add labels, priority, project, cycle
- Create issue relations (blocks, relates to)
- Work with qa-bug-ticket-creator and qa-task-creator outputs
Cannot do (requires confirmation):
- Create issues in workspaces without API access
- Assign to specific users without mapping
- Delete or archive issues
- Modify workspace settings
Will not do (out of scope):
- Modify production or test code
- Execute tests or deployments
- Manage Linear workspace billing or admin
Quality Checklist
Troubleshooting
| Symptom |
Likely Cause |
Fix |
| 401 Unauthorized |
Invalid or missing API key |
Verify LINEAR_API_KEY in .env; regenerate if needed |
| Team not found |
Wrong team ID or key |
Query teams { nodes { id key } }; use correct ID |
| Invalid input |
Required field missing |
Check references/field-mapping.md; ensure teamId and title present |
| Cycle not found |
Cycle doesn't exist or wrong team |
Query cycles for team; use active cycle ID |
| GraphQL errors |
Malformed mutation/query |
Validate query syntax; check Linear API docs |
| Label not applied |
Label doesn't exist in workspace |
Create label in Linear or use existing label name |
| Relation fails |
Invalid issue ID |
Verify target issue exists; use correct id (UUID) |
Reference Files
| Topic |
File |
| GraphQL API patterns |
references/api-patterns.md |
| QA → Linear field mapping |
references/field-mapping.md |
1---2name: qa-linear-integration3description: Linear integration for creating issues, managing projects/cycles, and tracking QA workflows via GraphQL API or Linear MCP.4---56# QA Linear Integration78## Purpose910Integrate QA workflow with Linear for issue tracking and project management. Create and update issues, manage projects and cycles, and sync with qa-bug-ticket-creator and qa-task-creator for end-to-end QA traceability.1112## Features1314| Feature | Description |15| ------- | ----------- |16| **Create/update issues** | Bug, Story, Task via GraphQL mutations |17| **Projects and cycles** | Assign issues to projects; add to cycles (sprints) |18| **Labels and priority** | Map severity/priority to Linear labels and priority |19| **Issue relations** | Blocks, relates to, duplicates |20| **Team assignment** | Assign issues to teams |21| **GraphQL API** | Full GraphQL for queries and mutations |2223## Authentication2425Store in `.env` (never hardcode):2627```28LINEAR_API_KEY=lin_api_xxxxxxxxxxxx29```3031- **Header:** `Authorization: Bearer {LINEAR_API_KEY}`32- Linear uses API keys; no Basic Auth. Create keys at Linear → Settings → API.3334## Key API Patterns3536| Operation | GraphQL |37| --------- | ------- |38| Create issue | `mutation { issueCreate(input: {...}) { issue { id identifier url } } }` |39| Update issue | `mutation { issueUpdate(id: "...", input: {...}) { issue { ... } } }` |40| Query issues | `query { issues(filter: {...}) { nodes { id identifier title state { name } } } }` |41| Projects | `query { projects { nodes { id name } } }` |42| Teams | `query { teams { nodes { id name key } } }` |43| Cycles | `query { cycles(filter: { teamId: { eq: "..." } }) { nodes { id name } } }` |4445See `references/api-patterns.md` for full GraphQL examples.4647## Integration with QA Skills4849### qa-bug-ticket-creator5051When creating a bug report for Linear:52531. **Input** — Bug report from test failure (title, expected/actual, steps, severity, component)542. **Map** — Use `references/field-mapping.md` to map to Linear fields553. **Create** — `issueCreate` with `teamId`, `title`, `description`, `priority`, `labels`564. **Link** — Add "blocks" or "relates to" for related issues when applicable5758### qa-task-creator5960When creating tasks for Linear:61621. **Input** — Task from coverage gap, spec finding, or bug fix request632. **Map** — Map task type to Linear issue type (Story, Task)643. **Create** — `issueCreate` with project, cycle, labels654. **Link** — Use `parentId` for sub-tasks; "blocks" for fix tasks referencing bugs6667## Trigger Phrases6869- "Create Linear issue for [bug/task description]"70- "Add bug to Linear from test failure"71- "Create Linear story for [feature]"72- "Sync QA tasks to Linear"73- "Linear issue from qa-bug-ticket-creator output"74- "Add to Linear cycle [name]"75- "Query Linear issues by [filter]"7677## Workflow78791. **Auth** — Load `LINEAR_API_KEY` from `.env`802. **Resolve IDs** — Query teams, projects, cycles to get IDs (or use user-provided)813. **Map fields** — Apply `references/field-mapping.md` for QA → Linear824. **Execute** — Run GraphQL mutation (issueCreate, issueUpdate)835. **Output** — Return issue identifier (e.g., `BUG-123`), URL, and summary8485## Scope8687**Can do (autonomous):**88- Create and update Linear issues via GraphQL89- Map QA bug/task fields to Linear fields90- Query issues, projects, teams, cycles91- Add labels, priority, project, cycle92- Create issue relations (blocks, relates to)93- Work with qa-bug-ticket-creator and qa-task-creator outputs9495**Cannot do (requires confirmation):**96- Create issues in workspaces without API access97- Assign to specific users without mapping98- Delete or archive issues99- Modify workspace settings100101**Will not do (out of scope):**102- Modify production or test code103- Execute tests or deployments104- Manage Linear workspace billing or admin105106## Quality Checklist107108- [ ] `LINEAR_API_KEY` loaded from `.env`; never hardcoded109- [ ] Field mapping applied per `references/field-mapping.md`110- [ ] Issue includes title, description, and appropriate labels/priority111- [ ] Team ID (or project) specified for issue creation112- [ ] GraphQL errors handled; user-friendly message on failure113- [ ] Issue identifier and URL returned to user114- [ ] Relations (blocks, relates to) set when linking to bugs/tasks115116## Troubleshooting117118| Symptom | Likely Cause | Fix |119| ------- | ------------ | --- |120| 401 Unauthorized | Invalid or missing API key | Verify `LINEAR_API_KEY` in `.env`; regenerate if needed |121| Team not found | Wrong team ID or key | Query `teams { nodes { id key } }`; use correct ID |122| Invalid input | Required field missing | Check `references/field-mapping.md`; ensure `teamId` and `title` present |123| Cycle not found | Cycle doesn't exist or wrong team | Query cycles for team; use active cycle ID |124| GraphQL errors | Malformed mutation/query | Validate query syntax; check Linear API docs |125| Label not applied | Label doesn't exist in workspace | Create label in Linear or use existing label name |126| Relation fails | Invalid issue ID | Verify target issue exists; use correct `id` (UUID) |127128## Reference Files129130| Topic | File |131| ----- | ---- |132| GraphQL API patterns | `references/api-patterns.md` |133| QA → Linear field mapping | `references/field-mapping.md` |
azanir