# QA Linear Integration

> Linear integration for creating issues, managing projects/cycles, and tracking QA workflows via GraphQL API or Linear MCP.

- Skill: `azanir/qa-linear-integration` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add azanir/qa-linear-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azanir/qa-linear-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: azanir (https://skillmd.com/u/azanir)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/azanir/qa-linear-integration

---


# 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:

1. **Input** — Bug report from test failure (title, expected/actual, steps, severity, component)
2. **Map** — Use `references/field-mapping.md` to map to Linear fields
3. **Create** — `issueCreate` with `teamId`, `title`, `description`, `priority`, `labels`
4. **Link** — Add "blocks" or "relates to" for related issues when applicable

### qa-task-creator

When creating tasks for Linear:

1. **Input** — Task from coverage gap, spec finding, or bug fix request
2. **Map** — Map task type to Linear issue type (Story, Task)
3. **Create** — `issueCreate` with project, cycle, labels
4. **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

1. **Auth** — Load `LINEAR_API_KEY` from `.env`
2. **Resolve IDs** — Query teams, projects, cycles to get IDs (or use user-provided)
3. **Map fields** — Apply `references/field-mapping.md` for QA → Linear
4. **Execute** — Run GraphQL mutation (issueCreate, issueUpdate)
5. **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

- [ ] `LINEAR_API_KEY` loaded from `.env`; never hardcoded
- [ ] Field mapping applied per `references/field-mapping.md`
- [ ] Issue includes title, description, and appropriate labels/priority
- [ ] Team ID (or project) specified for issue creation
- [ ] GraphQL errors handled; user-friendly message on failure
- [ ] Issue identifier and URL returned to user
- [ ] Relations (blocks, relates to) set when linking to bugs/tasks

## 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` |