feat: link tasks to github references (#1471)

2026-06-23 17:28:52 +01:00
parent 9b00a16bbe
commit 4d19fb32f1
34 changed files with 2367 additions and 120 deletions
@@ -0,0 +1,33 @@
+# Link Existing Task to GitHub References Plan
+
+## Scope
+
+Implement issue #1470 by linking GitHub references to existing tasks:
+
+- GitHub issues through task metadata and the existing GitHub issue fetch path.
+- GitHub pull requests through the existing task PR association model.
+- A shared **Link** submenu in task menus with separate **GitHub Pull Request** and **GitHub Issue** actions.
+
+## Backend
+
+- Add `PUT /api/v1/github/tasks/:taskId/issue` and `DELETE /api/v1/github/tasks/:taskId/issue`.
+- Add GitHub service methods to parse URL/number input, fetch the issue, validate repository ownership, merge or remove issue metadata, and rely on task service update publishing.
+- Reuse existing `POST /api/v1/github/task-prs` support for manual PR association.
+- Add service tests for successful link, repository mismatch, and unlink.
+
+## Frontend
+
+- Add typed GitHub API helpers for link/unlink.
+- Add responsive dialogs for GitHub issue and GitHub pull request URL/number input.
+- Replace flat issue actions with a **Link** submenu containing **GitHub Pull Request** and **GitHub Issue**.
+- Add that submenu to task card menus and sidebar task menus.
+- Reuse existing issue metadata and task PR rendering on task cards and detail/sidebar surfaces.
+- Add API helper unit tests.
+
+## Verification
+
+- `cd apps/backend && go test ./internal/github/...`
+- `cd apps && pnpm --filter @kandev/web test -- --run lib/api/domains/github-api.test.ts lib/kanban/map-task.test.ts`
+- `cd apps && pnpm --filter @kandev/web typecheck`
+- `cd apps && pnpm --filter @kandev/web lint`
+- Run format, typecheck, test, and lint before opening the PR.
@@ -47,6 +47,7 @@ Kandev's task model: documents, execution stages, labels, blocker escalation, su
 | [subtree-controls](tasks/subtree-controls.md) | shipped |
 | [blocked-task-escalation](tasks/blocked-task-escalation.md) | draft |
 | [runtime-cleanup](tasks/runtime-cleanup.md) | draft |
+| [link-existing-task-github-issue](tasks/link-existing-task-github-issue.md) | building |
 | [multi-branch](tasks/multi-branch/spec.md) | shipped |

 ## agents/ — agent governance
@@ -0,0 +1,67 @@
+---
+status: building
+created: 2026-06-23
+owner: product
+---
+
+# Link Existing Task to GitHub References
+
+## Why
+
+Users can create a task from GitHub, but they also need to attach GitHub references to a task that already exists. That breaks traceability when a task is started first and the GitHub pull request or issue is created later.
+
+## What
+
+- Any existing task can open a **Link** submenu from task menus.
+- The submenu contains **GitHub Pull Request** and **GitHub Issue** actions.
+- The actions are available from task card context/dropdown menus and sidebar task context menus.
+- The issue action accepts a GitHub issue URL. If the task has exactly one GitHub repository, an issue number such as `#1470` is also accepted.
+- The pull request action accepts a GitHub PR URL. If the task has exactly one GitHub repository, a PR number such as `#1471` is also accepted.
+- The backend fetches the issue through the configured GitHub integration and only links it when the issue belongs to a GitHub repository attached to the task.
+- The link is stored in task metadata using the existing `issue_url` and `issue_number` fields, so kanban cards and task detail surfaces render it through the existing issue indicator.
+- Pull request linking reuses the existing task PR association model and rendering.
+- A linked issue can be explicitly changed or unlinked from the same dialog.
+
+## Out of Scope
+
+- Creating GitHub issues from Kandev.
+- Creating GitHub pull requests from Kandev.
+- New issue synchronization beyond the existing metadata-backed reference.
+
+## Scenarios
+
+### Link a GitHub issue to an existing task
+
+GIVEN an existing task with a GitHub repository attached
+WHEN the user opens Link > GitHub Issue and enters an issue URL from that repository
+THEN Kandev stores the issue URL and issue number on the task without changing task state, session history, repositories, or unrelated metadata
+
+### Reject an issue from a different repository
+
+GIVEN an existing task with a GitHub repository attached
+WHEN the user attempts to link an issue from another GitHub repository
+THEN Kandev rejects the request with a clear repository mismatch error and leaves task metadata unchanged
+
+### Link a pull request to an existing task
+
+GIVEN an existing task with a GitHub repository attached
+WHEN the user opens Link > GitHub Pull Request and enters a pull request URL from that repository
+THEN Kandev creates the task pull request association using the attached repository ID so existing PR rendering surfaces can show the link
+
+### Infer a reference number for a single-repository task
+
+GIVEN an existing task with exactly one GitHub repository attached
+WHEN the user enters a bare number or hash-prefixed number in the GitHub Issue or GitHub Pull Request dialog
+THEN Kandev resolves the number against that single repository before linking the reference
+
+### Unlink an existing issue
+
+GIVEN an existing task that already has GitHub issue metadata
+WHEN the user opens Link > GitHub Issue and chooses Unlink
+THEN Kandev removes only the issue metadata keys and preserves unrelated task metadata
+
+## Success Criteria
+
+- Linking does not change task state, session history, repositories, or unrelated metadata.
+- Invalid issue references and repository mismatches return clear errors.
+- Right-click context menu, sidebar menu, and touch/dropdown menu users can reach the Link submenu.