QA ClickUp Integration
Purpose
Integrate QA workflow with ClickUp for task management. Create and manage tasks, lists, folders, and spaces; attach QA metadata via custom fields; and sync bug reports and work tasks from qa-bug-ticket-creator and qa-task-creator into ClickUp.
Primary Target
ClickUp via REST API. Base URL: https://api.clickup.com/api/v2.
Features
Task Management
| Feature |
Description |
| Create tasks |
POST to list; set name, description, assignees, status, priority |
| Update tasks |
PUT to modify existing tasks |
| Get task |
GET task by ID for status checks |
| Subtasks |
Create subtasks for test steps or breakdown |
| Checklists |
Add checklist items for acceptance criteria |
| Attachments |
Attach screenshots, logs, HAR files |
Hierarchy
| Level |
API |
Use |
| Space |
GET /api/v2/team/{team_id}/space |
QA workspace or project |
| Folder |
GET /api/v2/space/{space_id}/folder |
Feature or module grouping |
| List |
GET /api/v2/folder/{folder_id}/list |
Sprint, release, or backlog |
| Task |
POST /api/v2/list/{list_id}/task |
Individual work item |
QA Metadata
| Custom Field |
Purpose |
| Severity |
Blocker / Critical / Major / Minor / Trivial |
| Test Type |
Unit / Integration / E2E / Performance / Security |
| Coverage |
Requirement or module coverage reference |
| Environment |
OS, browser, app version |
| Component |
Affected area (auth, checkout, API) |
Relationships
- Blocking — Task A blocks Task B
- Waiting on — Task A waits on Task B
- Linked — Related tasks for traceability
Tags and Priorities
- Tags —
bug, test-coverage, flaky, docs, component tags
- Priority — Urgent (1), High (2), Normal (3), Low (4)
Authentication
| Variable |
Description |
CLICKUP_API_TOKEN |
Personal API token (starts with pk_) from .env |
Header: Authorization: <token>
Generate tokens at: ClickUp Settings → Apps → API Token.
Key API Endpoints
| Method |
Endpoint |
Use |
| POST |
/api/v2/list/{list_id}/task |
Create task |
| GET |
/api/v2/task/{task_id} |
Get task details |
| PUT |
/api/v2/task/{task_id} |
Update task |
| GET |
/api/v2/team/{team_id}/space |
List spaces |
| GET |
/api/v2/space/{space_id}/folder |
List folders |
| GET |
/api/v2/folder/{folder_id}/list |
List lists |
| POST |
/api/v2/task/{task_id}/attachment |
Add attachment |
See references/api-patterns.md for request/response examples.
Integration with QA Skills
| Skill |
Integration |
| qa-bug-ticket-creator |
Create ClickUp tasks from bug reports; map severity, component, evidence |
| qa-task-creator |
Create ClickUp tasks from coverage gaps, spec findings, fix tasks |
| qa-test-reporter |
Attach test reports as task attachments; link failures to tasks |
Handoff Flow
- Bug report → qa-bug-ticket-creator structures report → qa-clickup-integration creates task in target list
- Fix task → qa-task-creator generates task → qa-clickup-integration creates task, links to bug task
- Coverage gap → qa-coverage-analyzer output → qa-task-creator → qa-clickup-integration
Trigger Phrases
- "Create ClickUp task from [bug report / test failure]"
- "Add task to ClickUp list [name]"
- "Sync bug to ClickUp with severity and evidence"
- "Create ClickUp task from coverage gap"
- "Link fix task to bug in ClickUp"
- "Attach screenshot to ClickUp task [id]"
- "Get ClickUp task status for [id]"
Workflow
- Input — Bug report, task description, coverage gap, or user request
- Resolve target — Team ID, Space, Folder, List (from user or config)
- Map fields — Map QA fields to ClickUp task fields per
references/field-mapping.md
- Create/update — POST or PUT via REST API
- Attach — Add screenshots, logs when provided
- Link — Set blocking/waiting-on when paired with bug or fix task
Scope
Can do (autonomous):
- Create and update tasks in specified lists
- Map severity, priority, component, test type to ClickUp fields
- Add subtasks, checklists, attachments
- Set task relationships (blocking, waiting on)
- Resolve space/folder/list from user input or config
- Integrate with qa-bug-ticket-creator and qa-task-creator output
Cannot do (requires confirmation):
- Create spaces, folders, or lists (assume they exist)
- Override user-specified list or assignee
- Set custom fields without workspace configuration
Will not do (out of scope):
- Modify production or test code
- Delete tasks or archives (user responsibility)
- Create ClickUp workspaces or teams
Quality Checklist
Troubleshooting
| Symptom |
Likely Cause |
Fix |
| 401 Unauthorized |
Token missing or invalid |
Check CLICKUP_API_TOKEN in .env; regenerate if expired |
| 404 Not Found |
Invalid list_id or task_id |
Verify IDs; use GET to list spaces/folders/lists |
| 429 Rate limit |
Too many requests |
Implement backoff; batch operations |
| Custom field not applied |
Field ID wrong or not configured |
Check workspace custom fields; use correct field ID |
| Attachment fails |
File size or format |
ClickUp limits; use supported formats (png, jpg, txt, etc.) |
| Wrong list |
List ID from wrong folder |
Resolve full hierarchy: team → space → folder → list |
Reference Files
| Topic |
File |
| API patterns: tasks, lists, spaces, custom fields |
references/api-patterns.md |
| Mapping QA fields to ClickUp task fields |
references/field-mapping.md |
1---2name: qa-clickup-integration3description: ClickUp integration for creating tasks, managing lists/spaces, and tracking QA workflows via REST API.4---56# QA ClickUp Integration78## Purpose910Integrate QA workflow with ClickUp for task management. Create and manage tasks, lists, folders, and spaces; attach QA metadata via custom fields; and sync bug reports and work tasks from qa-bug-ticket-creator and qa-task-creator into ClickUp.1112## Primary Target1314**ClickUp** via REST API. Base URL: `https://api.clickup.com/api/v2`.1516## Features1718### Task Management1920| Feature | Description |21| ------- | ----------- |22| **Create tasks** | POST to list; set name, description, assignees, status, priority |23| **Update tasks** | PUT to modify existing tasks |24| **Get task** | GET task by ID for status checks |25| **Subtasks** | Create subtasks for test steps or breakdown |26| **Checklists** | Add checklist items for acceptance criteria |27| **Attachments** | Attach screenshots, logs, HAR files |2829### Hierarchy3031| Level | API | Use |32| ----- | --- | --- |33| **Space** | GET /api/v2/team/{team_id}/space | QA workspace or project |34| **Folder** | GET /api/v2/space/{space_id}/folder | Feature or module grouping |35| **List** | GET /api/v2/folder/{folder_id}/list | Sprint, release, or backlog |36| **Task** | POST /api/v2/list/{list_id}/task | Individual work item |3738### QA Metadata3940| Custom Field | Purpose |41| ------------ | ------- |42| **Severity** | Blocker / Critical / Major / Minor / Trivial |43| **Test Type** | Unit / Integration / E2E / Performance / Security |44| **Coverage** | Requirement or module coverage reference |45| **Environment** | OS, browser, app version |46| **Component** | Affected area (auth, checkout, API) |4748### Relationships4950- **Blocking** — Task A blocks Task B51- **Waiting on** — Task A waits on Task B52- **Linked** — Related tasks for traceability5354### Tags and Priorities5556- **Tags** — `bug`, `test-coverage`, `flaky`, `docs`, component tags57- **Priority** — Urgent (1), High (2), Normal (3), Low (4)5859## Authentication6061| Variable | Description |62| -------- | ----------- |63| `CLICKUP_API_TOKEN` | Personal API token (starts with `pk_`) from .env |6465**Header:** `Authorization: <token>`6667Generate tokens at: ClickUp Settings → Apps → API Token.6869## Key API Endpoints7071| Method | Endpoint | Use |72| ------ | -------- | --- |73| POST | `/api/v2/list/{list_id}/task` | Create task |74| GET | `/api/v2/task/{task_id}` | Get task details |75| PUT | `/api/v2/task/{task_id}` | Update task |76| GET | `/api/v2/team/{team_id}/space` | List spaces |77| GET | `/api/v2/space/{space_id}/folder` | List folders |78| GET | `/api/v2/folder/{folder_id}/list` | List lists |79| POST | `/api/v2/task/{task_id}/attachment` | Add attachment |8081See `references/api-patterns.md` for request/response examples.8283## Integration with QA Skills8485| Skill | Integration |86| ----- | ----------- |87| **qa-bug-ticket-creator** | Create ClickUp tasks from bug reports; map severity, component, evidence |88| **qa-task-creator** | Create ClickUp tasks from coverage gaps, spec findings, fix tasks |89| **qa-test-reporter** | Attach test reports as task attachments; link failures to tasks |9091### Handoff Flow92931. **Bug report** → qa-bug-ticket-creator structures report → qa-clickup-integration creates task in target list942. **Fix task** → qa-task-creator generates task → qa-clickup-integration creates task, links to bug task953. **Coverage gap** → qa-coverage-analyzer output → qa-task-creator → qa-clickup-integration9697## Trigger Phrases9899- "Create ClickUp task from [bug report / test failure]"100- "Add task to ClickUp list [name]"101- "Sync bug to ClickUp with severity and evidence"102- "Create ClickUp task from coverage gap"103- "Link fix task to bug in ClickUp"104- "Attach screenshot to ClickUp task [id]"105- "Get ClickUp task status for [id]"106107## Workflow1081091. **Input** — Bug report, task description, coverage gap, or user request1102. **Resolve target** — Team ID, Space, Folder, List (from user or config)1113. **Map fields** — Map QA fields to ClickUp task fields per `references/field-mapping.md`1124. **Create/update** — POST or PUT via REST API1135. **Attach** — Add screenshots, logs when provided1146. **Link** — Set blocking/waiting-on when paired with bug or fix task115116## Scope117118**Can do (autonomous):**119- Create and update tasks in specified lists120- Map severity, priority, component, test type to ClickUp fields121- Add subtasks, checklists, attachments122- Set task relationships (blocking, waiting on)123- Resolve space/folder/list from user input or config124- Integrate with qa-bug-ticket-creator and qa-task-creator output125126**Cannot do (requires confirmation):**127- Create spaces, folders, or lists (assume they exist)128- Override user-specified list or assignee129- Set custom fields without workspace configuration130131**Will not do (out of scope):**132- Modify production or test code133- Delete tasks or archives (user responsibility)134- Create ClickUp workspaces or teams135136## Quality Checklist137138- [ ] Task includes name, description, and appropriate priority139- [ ] QA metadata (severity, test type, component) mapped per field-mapping140- [ ] Attachments added when evidence provided141- [ ] No hardcoded secrets; token from .env142- [ ] List ID resolved before create; task ID validated before update143- [ ] Relationships set when linking bug to fix task144- [ ] Error handling for 401, 404, 429 (rate limit)145146## Troubleshooting147148| Symptom | Likely Cause | Fix |149| ------- | ------------ | --- |150| 401 Unauthorized | Token missing or invalid | Check `CLICKUP_API_TOKEN` in .env; regenerate if expired |151| 404 Not Found | Invalid list_id or task_id | Verify IDs; use GET to list spaces/folders/lists |152| 429 Rate limit | Too many requests | Implement backoff; batch operations |153| Custom field not applied | Field ID wrong or not configured | Check workspace custom fields; use correct field ID |154| Attachment fails | File size or format | ClickUp limits; use supported formats (png, jpg, txt, etc.) |155| Wrong list | List ID from wrong folder | Resolve full hierarchy: team → space → folder → list |156157## Reference Files158159| Topic | File |160| ----- | ---- |161| API patterns: tasks, lists, spaces, custom fields | `references/api-patterns.md` |162| Mapping QA fields to ClickUp task fields | `references/field-mapping.md` |
azanir