[Phase 5.5] GitHub Issues import: execute import and task traceability

[frankbria]

Goal

Execute the import: convert selected GitHub issues into CodeFRAME tasks, link them back to their source, and optionally auto-close them on completion.

Background

Follows the browser UI (#564). Once issues are selected, the import creates tasks and sets up the traceability link.

Scope

Import flow:

• [Import Selected] triggers POST /api/v2/integrations/github/import with a list of GitHub issue numbers
• Backend maps each issue to a CodeFRAME task:
  • title → task title (verbatim)
  • body → task description (markdown preserved)
  • labels → task tags (best-effort mapping)
  • number + html_url stored as external_id / external_url on the task
• Shows a progress indicator during import (can be simple "Importing 3 issues..." spinner)
• On completion: shows a summary ("3 tasks created") with links to the new tasks, then closes the modal

Post-import tracking:

• Each imported task's detail modal shows an "Imported from GitHub" badge linking to the original issue
• In task detail: optional checkbox "Close GitHub issue when task is marked DONE"
  • If checked, on task → DONE: fire PATCH /api/v2/integrations/github/issues/{number}/close
  • Backend: calls GitHub API to close the issue (comment optional: "Completed via CodeFRAME")

Acceptance criteria

• Import creates tasks with correct titles and descriptions
• Imported tasks show the GitHub issue badge with correct link
• Auto-close checkbox works end-to-end
• Duplicate import protection (don't create a second task if the same issue is imported again — check external_id)
• npm test and uv run pytest pass

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase has two parallel stacks: a legacy v1 (project-based, SQLite via Database/SchemaManager) and a v2 (workspace-based, codeframe/core/tasks.py with its own SQLite schema). The v2 Task dataclass already has a github_issue_number field and the tasks table already stores it. The GitHubIntegration class in codeframe/git/github_integration.py handles async GitHub API calls (PR-focused). The frontend is Next.js 14 + React 18 + Tailwind + @radix-ui + axios/swr, with components following the pattern in BlockerBadge.tsx and PRDModal.tsx.

Approach

The work splits into four sequential layers: (1) extend the v2 tasks table with external_id/external_url/auto_close_github_issue columns, (2) add close_issue to GitHubIntegration, (3) create the github_import_v2.py router with import + close endpoints, (4) add the frontend GitHubIssueBadge component and wire the auto-close checkbox into the task detail view. This keeps the pattern consistent with pr_v2.py and tasks_v2.py.

---

Implementation Steps

1. Database Schema — Add traceability columns to the v2 tasks table

In file:codeframe/persistence/schema_manager.py, inside _apply_migrations, add three new _add_column_if_not_exists calls for the tasks table:

Column	Type	Purpose
external_id	TEXT	Stores "github:<number>" for imported issues
external_url	TEXT	Stores the GitHub issue html_url
auto_close_github_issue	INTEGER (0/1)	Whether to close the issue on DONE

Also add a unique index on (workspace_id, external_id) inside _create_indexes to support duplicate-import protection.

---

2. Extend the v2 Task dataclass and CRUD layer

file:codeframe/core/tasks.py

• Add three fields to the Task dataclass: external_id: Optional[str], external_url: Optional[str], auto_close_github_issue: bool = False.
• Extend the INSERT in create() to accept and persist these three fields.
• Extend the SELECT column list in get(), list_tasks(), and _row_to_task() to read and map them.
• Add a new function get_by_external_id(workspace, external_id) -> Optional[Task] that queries WHERE workspace_id = ? AND external_id = ? — used for duplicate-import protection.
• Add a new function update_auto_close(workspace, task_id, auto_close: bool) -> Task that updates the auto_close_github_issue column.

---

3. Extend GitHubIntegration with issue operations

file:codeframe/git/github_integration.py

Add two new async methods to GitHubIntegration:

• get_issue(issue_number: int) -> dict — GET /repos/{owner}/{repo}/issues/{number}, returns raw dict with title, body, labels, number, html_url.
• close_issue(issue_number: int, comment: Optional[str] = None) -> bool — optionally posts a comment via POST /repos/{owner}/{repo}/issues/{number}/comments, then patches state to "closed" via PATCH /repos/{owner}/{repo}/issues/{number}.

---

4. Create the GitHub import router

Create file:codeframe/ui/routers/github_import_v2.py following the exact pattern of pr_v2.py:

router = APIRouter(prefix="/api/v2/integrations/github", tags=["github-import-v2"])

Pydantic models:

• ImportRequest — issue_numbers: list[int]
• ImportedTaskSummary — task_id, issue_number, title, task_url
• ImportResponse — created: list[ImportedTaskSummary], skipped: list[int] (duplicates), total_created: int

Endpoints:

POST /api/v2/integrations/github/import

1. Instantiate GitHubIntegration (raise 400 if not configured, same as _get_github_client()).
2. For each issue_number in the request:
   • Call tasks.get_by_external_id(workspace, f"github:{issue_number}") — if found, add to skipped list and continue.
   • Call github.get_issue(issue_number) to fetch title, body, labels, html_url.
   • Map labels to tags: store them in the task description as a markdown footer **Tags:** label1, label2 (best-effort, since the v2 Task has no dedicated tags field).
   • Call tasks.create(workspace, title=..., description=..., external_id=f"github:{issue_number}", external_url=html_url).
   • Append to created list.
3. Return ImportResponse.

PATCH /api/v2/integrations/github/issues/{number}/close

1. Instantiate GitHubIntegration.
2. Call github.close_issue(number, comment="Completed via CodeFRAME").
3. Return {"success": True, "issue_number": number}.

---

5. Register the new router in the FastAPI app

Locate the main app factory (search for where pr_v2.router is included — likely codeframe/ui/app.py or equivalent). Add:

from codeframe.ui.routers import github_import_v2
app.include_router(github_import_v2.router)

---

6. Hook auto-close into the task status transition

file:codeframe/ui/routers/tasks_v2.py — in update_task, after a successful transition to TaskStatus.DONE:

1. Re-fetch the task to check auto_close_github_issue and external_id.
2. If both are set and external_id starts with "github:", extract the issue number and fire github.close_issue(number, comment="Completed via CodeFRAME") in a background task (use FastAPI BackgroundTasks already imported in the file).
3. Swallow GitHubAPIError with a warning log — the task transition must not fail if GitHub is unreachable.

Also add a PATCH /api/v2/tasks/{task_id}/github-settings endpoint (or extend UpdateTaskRequest with auto_close_github_issue: Optional[bool]) to let the frontend toggle the checkbox.

---

7. Frontend — TypeScript types

Create file:legacy/web-ui/src/types/githubImport.ts:

• GitHubImportRequest — { issue_numbers: number[] }
• ImportedTaskSummary — { task_id: string; issue_number: number; title: string }
• GitHubImportResponse — { created: ImportedTaskSummary[]; skipped: number[]; total_created: number }

Extend the existing Task type in file:legacy/web-ui/src/types/agentState.ts with optional fields: external_id?: string, external_url?: string, auto_close_github_issue?: boolean.

---

8. Frontend — API client

Add a githubImportApi object to file:legacy/web-ui/src/lib/api.ts (following the pullRequestsApi pattern, using the existing axios instance):

• importIssues(issueNumbers: number[]) → POST /api/v2/integrations/github/import
• closeIssue(issueNumber: number) → PATCH /api/v2/integrations/github/issues/{number}/close
• updateTaskGitHubSettings(taskId: string, autoClose: boolean) → PATCH /api/v2/tasks/{taskId} with { auto_close_github_issue: autoClose }

---

9. Frontend — GitHubIssueBadge component

Create file:legacy/web-ui/src/components/git/GitHubIssueBadge.tsx following the BlockerBadge.tsx pattern:

Props: { issueNumber: number; issueUrl: string }

Renders a small badge: a GitHub icon (use @hugeicons/react or an inline SVG), the text "Imported from GitHub #<number>", and wraps it in an <a href={issueUrl} target="_blank" rel="noopener noreferrer">.

---

10. Frontend — Import modal state and progress

The import modal was built in #564. Extend it (or the component that triggers import) to:

1. On "Import Selected" click: set a loading state showing "Importing N issues..." (a simple spinner using the existing Spinner.tsx component).
2. Call githubImportApi.importIssues(selectedIssueNumbers).
3. On success: show a summary message "N tasks created" with links to each new task (using task_id from the response), then close the modal after a short delay or on user dismiss.
4. On error: show an inline error message.

---

11. Frontend — Task detail: badge + auto-close checkbox

In the task detail view (wherever individual task metadata is rendered — likely inside TaskList.tsx's TaskCard or a dedicated detail modal):

1. If task.external_id?.startsWith("github:") and task.external_url, render <GitHubIssueBadge issueNumber={...} issueUrl={task.external_url} />.
2. Render a checkbox labeled "Close GitHub issue when task is marked DONE", bound to task.auto_close_github_issue.
3. On checkbox change, call githubImportApi.updateTaskGitHubSettings(task.id, checked).

---

Data flow summary

sequenceDiagram
    participant UI as Browser UI
    participant API as POST /api/v2/integrations/github/import
    participant GH as GitHub API
    participant DB as SQLite (tasks table)

    UI->>API: { issue_numbers: [12, 34] }
    loop each issue_number
        API->>DB: get_by_external_id("github:12") → None (no duplicate)
        API->>GH: GET /repos/.../issues/12
        GH-->>API: { title, body, labels, html_url }
        API->>DB: tasks.create(title, description, external_id="github:12", external_url=...)
        DB-->>API: Task
    end
    API-->>UI: { created: [...], skipped: [], total_created: 2 }

    UI->>API: PATCH /api/v2/tasks/{id} { status: "DONE" }
    API->>DB: update_status → DONE
    Note over API: auto_close_github_issue=true?
    API->>GH: PATCH /repos/.../issues/12 { state: "closed" }
    GH-->>API: 200 OK
    API-->>UI: Updated Task

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has two parallel stacks: a **legacy v1** (project-based, SQLite via `Database`/`SchemaManager`) and a **v2** (workspace-based, `codeframe/core/tasks.py` with its own SQLite schema). The v2 `Task` dataclass already has a `github_issue_number` field and the `tasks` table already stores it. The `GitHubIntegration` class in `codeframe/git/github_integration.py` handles async GitHub API calls (PR-focused). The frontend is Next.js 14 + React 18 + Tailwind + `@radix-ui` + `axios`/`swr`, with components following the pattern in `BlockerBadge.tsx` and `PRDModal.tsx`.

## Approach

The work splits into four sequential layers: (1) extend the v2 `tasks` table with `external_id`/`external_url`/`auto_close_github_issue` columns, (2) add `close_issue` to `GitHubIntegration`, (3) create the `github_import_v2.py` router with import + close endpoints, (4) add the frontend `GitHubIssueBadge` component and wire the auto-close checkbox into the task detail view. This keeps the pattern consistent with `pr_v2.py` and `tasks_v2.py`.

---

## Implementation Steps

### 1. Database Schema — Add traceability columns to the v2 `tasks` table

In `file:codeframe/persistence/schema_manager.py`, inside `_apply_migrations`, add three new `_add_column_if_not_exists` calls for the `tasks` table:

| Column | Type | Purpose |
|---|---|---|
| `external_id` | `TEXT` | Stores `"github:<number>"` for imported issues |
| `external_url` | `TEXT` | Stores the GitHub issue `html_url` |
| `auto_close_github_issue` | `INTEGER` (0/1) | Whether to close the issue on DONE |

Also add a unique index on `(workspace_id, external_id)` inside `_create_indexes` to support duplicate-import protection.

---

### 2. Extend the v2 `Task` dataclass and CRUD layer

**`file:codeframe/core/tasks.py`**

- Add three fields to the `Task` dataclass: `external_id: Optional[str]`, `external_url: Optional[str]`, `auto_close_github_issue: bool = False`.
- Extend the `INSERT` in `create()` to accept and persist these three fields.
- Extend the `SELECT` column list in `get()`, `list_tasks()`, and `_row_to_task()` to read and map them.
- Add a new function `get_by_external_id(workspace, external_id) -> Optional[Task]` that queries `WHERE workspace_id = ? AND external_id = ?` — used for duplicate-import protection.
- Add a new function `update_auto_close(workspace, task_id, auto_close: bool) -> Task` that updates the `auto_close_github_issue` column.

---

### 3. Extend `GitHubIntegration` with issue operations

**`file:codeframe/git/github_integration.py`**

Add two new async methods to `GitHubIntegration`:

- `get_issue(issue_number: int) -> dict` — `GET /repos/{owner}/{repo}/issues/{number}`, returns raw dict with `title`, `body`, `labels`, `number`, `html_url`.
- `close_issue(issue_number: int, comment: Optional[str] = None) -> bool` — optionally posts a comment via `POST /repos/{owner}/{repo}/issues/{number}/comments`, then patches state to `"closed"` via `PATCH /repos/{owner}/{repo}/issues/{number}`.

---

### 4. Create the GitHub import router

Create **`file:codeframe/ui/routers/github_import_v2.py`** following the exact pattern of `pr_v2.py`:

```
router = APIRouter(prefix="/api/v2/integrations/github", tags=["github-import-v2"])
```

**Pydantic models:**

- `ImportRequest` — `issue_numbers: list[int]`
- `ImportedTaskSummary` — `task_id`, `issue_number`, `title`, `task_url`
- `ImportResponse` — `created: list[ImportedTaskSummary]`, `skipped: list[int]` (duplicates), `total_created: int`

**Endpoints:**

#### `POST /api/v2/integrations/github/import`

1. Instantiate `GitHubIntegration` (raise 400 if not configured, same as `_get_github_client()`).
2. For each `issue_number` in the request:
   - Call `tasks.get_by_external_id(workspace, f"github:{issue_number}")` — if found, add to `skipped` list and continue.
   - Call `github.get_issue(issue_number)` to fetch `title`, `body`, `labels`, `html_url`.
   - Map `labels` to tags: store them in the task `description` as a markdown footer `**Tags:** label1, label2` (best-effort, since the v2 `Task` has no dedicated tags field).
   - Call `tasks.create(workspace, title=..., description=..., external_id=f"github:{issue_number}", external_url=html_url)`.
   - Append to `created` list.
3. Return `ImportResponse`.

#### `PATCH /api/v2/integrations/github/issues/{number}/close`

1. Instantiate `GitHubIntegration`.
2. Call `github.close_issue(number, comment="Completed via CodeFRAME")`.
3. Return `{"success": True, "issue_number": number}`.

---

### 5. Register the new router in the FastAPI app

Locate the main app factory (search for where `pr_v2.router` is included — likely `codeframe/ui/app.py` or equivalent). Add:

```python
from codeframe.ui.routers import github_import_v2
app.include_router(github_import_v2.router)
```

---

### 6. Hook auto-close into the task status transition

**`file:codeframe/ui/routers/tasks_v2.py`** — in `update_task`, after a successful transition to `TaskStatus.DONE`:

1. Re-fetch the task to check `auto_close_github_issue` and `external_id`.
2. If both are set and `external_id` starts with `"github:"`, extract the issue number and fire `github.close_issue(number, comment="Completed via CodeFRAME")` in a background task (use FastAPI `BackgroundTasks` already imported in the file).
3. Swallow `GitHubAPIError` with a warning log — the task transition must not fail if GitHub is unreachable.

Also add a `PATCH /api/v2/tasks/{task_id}/github-settings` endpoint (or extend `UpdateTaskRequest` with `auto_close_github_issue: Optional[bool]`) to let the frontend toggle the checkbox.

---

### 7. Frontend — TypeScript types

Create **`file:legacy/web-ui/src/types/githubImport.ts`**:

- `GitHubImportRequest` — `{ issue_numbers: number[] }`
- `ImportedTaskSummary` — `{ task_id: string; issue_number: number; title: string }`
- `GitHubImportResponse` — `{ created: ImportedTaskSummary[]; skipped: number[]; total_created: number }`

Extend the existing `Task` type in `file:legacy/web-ui/src/types/agentState.ts` with optional fields: `external_id?: string`, `external_url?: string`, `auto_close_github_issue?: boolean`.

---

### 8. Frontend — API client

Add a `githubImportApi` object to **`file:legacy/web-ui/src/lib/api.ts`** (following the `pullRequestsApi` pattern, using the existing `axios` instance):

- `importIssues(issueNumbers: number[])` → `POST /api/v2/integrations/github/import`
- `closeIssue(issueNumber: number)` → `PATCH /api/v2/integrations/github/issues/{number}/close`
- `updateTaskGitHubSettings(taskId: string, autoClose: boolean)` → `PATCH /api/v2/tasks/{taskId}` with `{ auto_close_github_issue: autoClose }`

---

### 9. Frontend — `GitHubIssueBadge` component

Create **`file:legacy/web-ui/src/components/git/GitHubIssueBadge.tsx`** following the `BlockerBadge.tsx` pattern:

```
Props: { issueNumber: number; issueUrl: string }
```

Renders a small badge: a GitHub icon (use `@hugeicons/react` or an inline SVG), the text `"Imported from GitHub #<number>"`, and wraps it in an `<a href={issueUrl} target="_blank" rel="noopener noreferrer">`.

---

### 10. Frontend — Import modal state and progress

The import modal was built in #564. Extend it (or the component that triggers import) to:

1. On "Import Selected" click: set a loading state showing `"Importing N issues..."` (a simple spinner using the existing `Spinner.tsx` component).
2. Call `githubImportApi.importIssues(selectedIssueNumbers)`.
3. On success: show a summary message `"N tasks created"` with links to each new task (using `task_id` from the response), then close the modal after a short delay or on user dismiss.
4. On error: show an inline error message.

---

### 11. Frontend — Task detail: badge + auto-close checkbox

In the task detail view (wherever individual task metadata is rendered — likely inside `TaskList.tsx`'s `TaskCard` or a dedicated detail modal):

1. If `task.external_id?.startsWith("github:")` and `task.external_url`, render `<GitHubIssueBadge issueNumber={...} issueUrl={task.external_url} />`.
2. Render a checkbox labeled `"Close GitHub issue when task is marked DONE"`, bound to `task.auto_close_github_issue`.
3. On checkbox change, call `githubImportApi.updateTaskGitHubSettings(task.id, checked)`.

---

### Data flow summary

```mermaid
sequenceDiagram
    participant UI as Browser UI
    participant API as POST /api/v2/integrations/github/import
    participant GH as GitHub API
    participant DB as SQLite (tasks table)

    UI->>API: { issue_numbers: [12, 34] }
    loop each issue_number
        API->>DB: get_by_external_id("github:12") → None (no duplicate)
        API->>GH: GET /repos/.../issues/12
        GH-->>API: { title, body, labels, html_url }
        API->>DB: tasks.create(title, description, external_id="github:12", external_url=...)
        DB-->>API: Task
    end
    API-->>UI: { created: [...], skipped: [], total_created: 2 }

    UI->>API: PATCH /api/v2/tasks/{id} { status: "DONE" }
    API->>DB: update_status → DONE
    Note over API: auto_close_github_issue=true?
    API->>GH: PATCH /repos/.../issues/12 { state: "closed" }
    GH-->>API: 200 OK
    API-->>UI: Updated Task
```

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#214 - feat(planning): Add TaskReview component for task approval workflow [merged]
#236 - fix(ui): complete late-joining user bug fix for TaskStats and TaskReview [merged]
#496 - feat(web-ui): link failed tasks to PROOF9 gate failure for root cause (#474) [merged]
#499 - feat(web-ui): empty state with task generation CTA on task board (#477) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!