[Phase 5.5] GitHub Issues import: issue browser and multi-select UI

[frankbria]

Goal

Build the issue browser UI that lets users browse and select GitHub issues from a connected repo before importing.

Background

Follows the GitHub connection issue (#563). With a repo connected, users need to browse open issues and pick which ones to bring into CodeFRAME.

Scope

Tasks page — new "Import from GitHub" entry point:

• [Import Issues] button on the Tasks page (shown only when a GitHub repo is connected)
• Opens a full-screen modal or slide-over with:
  • Issue list: title, labels, assignee, age — paginated 25 at a time
  • Search / filter: by text (title search via GitHub API), by label, by assignee
  • Multi-select checkboxes with a "select all on page" checkbox
  • Selected count badge (e.g., "3 selected")
  • [Import Selected] button — disabled when 0 selected (triggers import flow in [Phase 5.5] GitHub Issues import: execute import and task traceability #565)
  • [Cancel] button

Backend:

• GET /api/v2/integrations/github/issues?page=1&per_page=25&search=...&label=... — proxies to GitHub API using stored PAT, returns simplified issue objects
• Cache responses for 60 seconds to avoid rate-limit issues

Out of scope

• Closed issues
• Issues from repos the user hasn't connected

Acceptance criteria

• Issue list renders with pagination
• Search and label filter work
• Multi-select state persists across pages
• [Import Selected] enabled only when ≥ 1 issue selected
• npm test pass

[coderabbitai]

🔗 Related PRs

#214 - feat(planning): Add TaskReview component for task approval workflow [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!

[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 active frontend is web-ui/ (Next.js 16, React 19, Tailwind, @radix-ui/react-dialog, @radix-ui/react-checkbox, swr, axios). The Tasks page renders TaskBoardView which already has a full Dialog + multi-select pattern to follow. The backend is FastAPI with httpx for GitHub calls; the existing GitHubIntegration class in file:codeframe/git/github_integration.py handles authenticated GitHub API calls. GitHub config is read from GITHUB_TOKEN / GITHUB_REPO env vars via get_global_config(). No in-process cache layer exists yet.

Approach

Add a new integrations_v2.py router that proxies GitHub Issues to the frontend, with a simple TTL dict-based cache (60 s). On the frontend, add a GitHubIssueImportModal component mounted inside TaskBoardView, with an Import from GitHub button that is conditionally shown when the repo is connected. Multi-select state is kept in a Set<number> in the modal's local state and persists across page changes via a useRef-backed map.

---

Implementation Steps

1. Backend — GitHubIssueResponse dataclass and list helper

In file:codeframe/git/github_integration.py, add a GitHubIssueResponse dataclass alongside the existing PRDetails:

• Fields: number: int, title: str, labels: list[str], assignee: str | None, created_at: datetime, html_url: str
• Add an async method list_issues on GitHubIntegration that calls GET /repos/{owner}/{repo}/issues with query params state=open, page, per_page, labels (optional), and a q search term forwarded as the GitHub q param via the search API or title-filter client-side. Return list[GitHubIssueResponse] plus a total_count hint from the Link response header.

Note on search: GitHub's REST Issues list endpoint does not support free-text search. Use GET /search/issues?q={search}+repo:{owner}/{repo}+is:open when a search term is present, and fall back to the plain list endpoint otherwise. Parse the total_count field from the search response.

---

2. Backend — integrations_v2.py router

Create file:codeframe/ui/routers/integrations_v2.py:

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

Pydantic models:

• GitHubIssueItem — mirrors GitHubIssueResponse fields, with created_at as ISO string
• GitHubIssuesResponse — { issues: list[GitHubIssueItem], total: int, page: int, per_page: int }
• GitHubConnectionStatus — { connected: bool, repo: str | None }

In-process cache: A module-level dict[str, tuple[float, Any]] keyed by the full query string, with a 60-second TTL. Wrap cache reads/writes in a helper _get_cached / _set_cached.

Endpoints:

Method	Path	Description
GET	/api/v2/integrations/github/status	Returns GitHubConnectionStatus — checks if GITHUB_TOKEN + GITHUB_REPO are set
GET	/api/v2/integrations/github/issues	Proxies to GitHub, returns GitHubIssuesResponse

Query params for the issues endpoint: page: int = 1, per_page: int = 25, search: str = "", label: str = "".

Reuse _get_github_client() pattern from file:codeframe/ui/routers/pr_v2.py. Apply @rate_limit_standard() and Depends(get_v2_workspace) consistently with other v2 routers.

---

3. Register the new router in server.py

In file:codeframe/ui/server.py, import integrations_v2 and add:

app.include_router(integrations_v2.router)  # /api/v2/integrations/github

---

4. Frontend — types

In file:web-ui/src/types/index.ts, add:

export interface GitHubIssue {
  number: number;
  title: string;
  labels: string[];
  assignee: string | null;
  created_at: string;
  html_url: string;
}

export interface GitHubIssuesResponse {
  issues: GitHubIssue[];
  total: number;
  page: number;
  per_page: number;
}

export interface GitHubConnectionStatus {
  connected: boolean;
  repo: string | null;
}

---

5. Frontend — API client methods

In file:web-ui/src/lib/api.ts, add an integrationsApi export:

• getGitHubStatus(workspacePath) → GET /api/v2/integrations/github/status
• getGitHubIssues(workspacePath, params: { page, perPage, search, label }) → GET /api/v2/integrations/github/issues

Follow the same axios + workspace_path query-param pattern used by tasksApi, blockersApi, etc.

---

6. Frontend — GitHubIssueImportModal component

Create file:web-ui/src/components/tasks/GitHubIssueImportModal.tsx.

Props:

interface GitHubIssueImportModalProps {
  open: boolean;
  workspacePath: string;
  onClose: () => void;
  onImport: (selectedIssues: GitHubIssue[]) => void;
}

Internal state:

• page: number — current page (1-indexed)
• search: string — debounced text input
• labelFilter: string — label filter input
• selectedIds: Set<number> — persists across page changes
• isLoading, error

Data fetching: Use useSWR with a key that includes page, search, labelFilter. The fetcher calls integrationsApi.getGitHubIssues(...).

Layout (full-screen Dialog):

┌─────────────────────────────────────────────────────────────────┐
│  Import Issues from GitHub  ·  owner/repo          [✕ Close]   │
├─────────────────────────────────────────────────────────────────┤
│  [🔍 Search by title...]   [Label: ________]                   │
├─────────────────────────────────────────────────────────────────┤
│  [☐ Select all on page]                  3 selected            │
│  ─────────────────────────────────────────────────────────────  │
│  [☐] #42  Fix login bug          bug, auth   @alice   3d ago   │
│  [☑] #41  Add dark mode          ui          @bob    1w ago    │
│  [☐] #39  Improve perf           perf        —       2w ago    │
│  ...                                                            │
├─────────────────────────────────────────────────────────────────┤
│  ← Prev   Page 1 of 4   Next →    [Cancel]  [Import Selected ▶]│
└─────────────────────────────────────────────────────────────────┘

Key behaviours:

• Use @radix-ui/react-dialog (Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter) — already in web-ui/package.json
• Use @radix-ui/react-checkbox for row checkboxes and the "select all on page" checkbox — already in web-ui/package.json
• "Select all on page" checkbox is indeterminate when some (not all) page items are selected — use the Radix checked="indeterminate" prop
• Selected count badge: "{n} selected" shown in the toolbar; hidden when 0
• [Import Selected] button is disabled when selectedIds.size === 0
• Search input is debounced 300 ms before triggering a new SWR fetch (use useState + useEffect with a setTimeout)
• Age column: use date-fns formatDistanceToNow (already in web-ui/package.json)
• Loading state: skeleton rows (same animate-pulse pattern as TaskBoardView)
• Error state: inline destructive banner

---

7. Frontend — wire the button into TaskBoardView

In file:web-ui/src/components/tasks/TaskBoardView.tsx:

1. Fetch GitHub connection status with useSWR:

   const { data: ghStatus } = useSWR(
     `/api/v2/integrations/github/status?path=${workspacePath}`,
     () => integrationsApi.getGitHubStatus(workspacePath)
   );

2. Add importModalOpen: boolean state.
3. In the header row (next to the existing title), conditionally render an Import from GitHub Button (variant outline) when ghStatus?.connected === true.
4. Mount <GitHubIssueImportModal> at the bottom of the JSX, passing open={importModalOpen}, onClose, and onImport.

The onImport callback (which triggers the actual import flow described in issue #565) can be a no-op stub for now — the ticket explicitly marks the import flow as out-of-scope.

---

8. Data flow diagram

sequenceDiagram
    participant UI as TaskBoardView
    participant Modal as GitHubIssueImportModal
    participant API as integrationsApi
    participant BE as integrations_v2.py
    participant GH as GitHub REST API

    UI->>API: getGitHubStatus(workspacePath)
    API->>BE: GET /api/v2/integrations/github/status
    BE-->>API: { connected: true, repo: "owner/repo" }
    API-->>UI: ghStatus

    Note over UI: Shows "Import from GitHub" button

    UI->>Modal: open=true
    Modal->>API: getGitHubIssues(workspacePath, {page:1})
    API->>BE: GET /api/v2/integrations/github/issues?page=1&per_page=25
    BE->>GH: GET /repos/owner/repo/issues?state=open&page=1&per_page=25
    GH-->>BE: issues[]
    BE-->>API: GitHubIssuesResponse (cached 60s)
    API-->>Modal: issues[]

    Note over Modal: User selects issues, clicks Import Selected
    Modal->>UI: onImport(selectedIssues)

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The active frontend is `web-ui/` (Next.js 16, React 19, Tailwind, `@radix-ui/react-dialog`, `@radix-ui/react-checkbox`, `swr`, `axios`). The Tasks page renders `TaskBoardView` which already has a full Dialog + multi-select pattern to follow. The backend is FastAPI with `httpx` for GitHub calls; the existing `GitHubIntegration` class in `file:codeframe/git/github_integration.py` handles authenticated GitHub API calls. GitHub config is read from `GITHUB_TOKEN` / `GITHUB_REPO` env vars via `get_global_config()`. No in-process cache layer exists yet.

## Approach

Add a new `integrations_v2.py` router that proxies GitHub Issues to the frontend, with a simple TTL dict-based cache (60 s). On the frontend, add a `GitHubIssueImportModal` component mounted inside `TaskBoardView`, with an **Import from GitHub** button that is conditionally shown when the repo is connected. Multi-select state is kept in a `Set<number>` in the modal's local state and persists across page changes via a `useRef`-backed map.

---

## Implementation Steps

### 1. Backend — `GitHubIssueResponse` dataclass and list helper

In `file:codeframe/git/github_integration.py`, add a `GitHubIssueResponse` dataclass alongside the existing `PRDetails`:

- Fields: `number: int`, `title: str`, `labels: list[str]`, `assignee: str | None`, `created_at: datetime`, `html_url: str`
- Add an async method `list_issues` on `GitHubIntegration` that calls `GET /repos/{owner}/{repo}/issues` with query params `state=open`, `page`, `per_page`, `labels` (optional), and a `q` search term forwarded as the GitHub `q` param via the search API or title-filter client-side. Return `list[GitHubIssueResponse]` plus a `total_count` hint from the `Link` response header.

> **Note on search**: GitHub's REST Issues list endpoint does not support free-text search. Use `GET /search/issues?q={search}+repo:{owner}/{repo}+is:open` when a search term is present, and fall back to the plain list endpoint otherwise. Parse the `total_count` field from the search response.

---

### 2. Backend — `integrations_v2.py` router

Create `file:codeframe/ui/routers/integrations_v2.py`:

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

**Pydantic models:**

- `GitHubIssueItem` — mirrors `GitHubIssueResponse` fields, with `created_at` as ISO string
- `GitHubIssuesResponse` — `{ issues: list[GitHubIssueItem], total: int, page: int, per_page: int }`
- `GitHubConnectionStatus` — `{ connected: bool, repo: str | None }`

**In-process cache:** A module-level `dict[str, tuple[float, Any]]` keyed by the full query string, with a 60-second TTL. Wrap cache reads/writes in a helper `_get_cached` / `_set_cached`.

**Endpoints:**

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v2/integrations/github/status` | Returns `GitHubConnectionStatus` — checks if `GITHUB_TOKEN` + `GITHUB_REPO` are set |
| `GET` | `/api/v2/integrations/github/issues` | Proxies to GitHub, returns `GitHubIssuesResponse` |

Query params for the issues endpoint: `page: int = 1`, `per_page: int = 25`, `search: str = ""`, `label: str = ""`.

Reuse `_get_github_client()` pattern from `file:codeframe/ui/routers/pr_v2.py`. Apply `@rate_limit_standard()` and `Depends(get_v2_workspace)` consistently with other v2 routers.

---

### 3. Register the new router in `server.py`

In `file:codeframe/ui/server.py`, import `integrations_v2` and add:

```python
app.include_router(integrations_v2.router)  # /api/v2/integrations/github
```

---

### 4. Frontend — types

In `file:web-ui/src/types/index.ts`, add:

```ts
export interface GitHubIssue {
  number: number;
  title: string;
  labels: string[];
  assignee: string | null;
  created_at: string;
  html_url: string;
}

export interface GitHubIssuesResponse {
  issues: GitHubIssue[];
  total: number;
  page: number;
  per_page: number;
}

export interface GitHubConnectionStatus {
  connected: boolean;
  repo: string | null;
}
```

---

### 5. Frontend — API client methods

In `file:web-ui/src/lib/api.ts`, add an `integrationsApi` export:

- `getGitHubStatus(workspacePath)` → `GET /api/v2/integrations/github/status`
- `getGitHubIssues(workspacePath, params: { page, perPage, search, label })` → `GET /api/v2/integrations/github/issues`

Follow the same `axios` + `workspace_path` query-param pattern used by `tasksApi`, `blockersApi`, etc.

---

### 6. Frontend — `GitHubIssueImportModal` component

Create `file:web-ui/src/components/tasks/GitHubIssueImportModal.tsx`.

**Props:**
```ts
interface GitHubIssueImportModalProps {
  open: boolean;
  workspacePath: string;
  onClose: () => void;
  onImport: (selectedIssues: GitHubIssue[]) => void;
}
```

**Internal state:**
- `page: number` — current page (1-indexed)
- `search: string` — debounced text input
- `labelFilter: string` — label filter input
- `selectedIds: Set<number>` — persists across page changes
- `isLoading`, `error`

**Data fetching:** Use `useSWR` with a key that includes `page`, `search`, `labelFilter`. The fetcher calls `integrationsApi.getGitHubIssues(...)`.

**Layout (full-screen Dialog):**

```
┌─────────────────────────────────────────────────────────────────┐
│  Import Issues from GitHub  ·  owner/repo          [✕ Close]   │
├─────────────────────────────────────────────────────────────────┤
│  [🔍 Search by title...]   [Label: ________]                   │
├─────────────────────────────────────────────────────────────────┤
│  [☐ Select all on page]                  3 selected            │
│  ─────────────────────────────────────────────────────────────  │
│  [☐] #42  Fix login bug          bug, auth   @alice   3d ago   │
│  [☑] #41  Add dark mode          ui          @bob    1w ago    │
│  [☐] #39  Improve perf           perf        —       2w ago    │
│  ...                                                            │
├─────────────────────────────────────────────────────────────────┤
│  ← Prev   Page 1 of 4   Next →    [Cancel]  [Import Selected ▶]│
└─────────────────────────────────────────────────────────────────┘
```

**Key behaviours:**
- Use `@radix-ui/react-dialog` (`Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogFooter`) — already in `web-ui/package.json`
- Use `@radix-ui/react-checkbox` for row checkboxes and the "select all on page" checkbox — already in `web-ui/package.json`
- "Select all on page" checkbox is indeterminate when some (not all) page items are selected — use the Radix `checked="indeterminate"` prop
- Selected count badge: `"{n} selected"` shown in the toolbar; hidden when 0
- **[Import Selected]** button is `disabled` when `selectedIds.size === 0`
- Search input is debounced 300 ms before triggering a new SWR fetch (use `useState` + `useEffect` with a `setTimeout`)
- Age column: use `date-fns` `formatDistanceToNow` (already in `web-ui/package.json`)
- Loading state: skeleton rows (same `animate-pulse` pattern as `TaskBoardView`)
- Error state: inline destructive banner

---

### 7. Frontend — wire the button into `TaskBoardView`

In `file:web-ui/src/components/tasks/TaskBoardView.tsx`:

1. Fetch GitHub connection status with `useSWR`:
   ```ts
   const { data: ghStatus } = useSWR(
     `/api/v2/integrations/github/status?path=${workspacePath}`,
     () => integrationsApi.getGitHubStatus(workspacePath)
   );
   ```
2. Add `importModalOpen: boolean` state.
3. In the header row (next to the existing title), conditionally render an **Import from GitHub** `Button` (variant `outline`) when `ghStatus?.connected === true`.
4. Mount `<GitHubIssueImportModal>` at the bottom of the JSX, passing `open={importModalOpen}`, `onClose`, and `onImport`.

The `onImport` callback (which triggers the actual import flow described in issue #565) can be a no-op stub for now — the ticket explicitly marks the import flow as out-of-scope.

---

### 8. Data flow diagram

```mermaid
sequenceDiagram
    participant UI as TaskBoardView
    participant Modal as GitHubIssueImportModal
    participant API as integrationsApi
    participant BE as integrations_v2.py
    participant GH as GitHub REST API

    UI->>API: getGitHubStatus(workspacePath)
    API->>BE: GET /api/v2/integrations/github/status
    BE-->>API: { connected: true, repo: "owner/repo" }
    API-->>UI: ghStatus

    Note over UI: Shows "Import from GitHub" button

    UI->>Modal: open=true
    Modal->>API: getGitHubIssues(workspacePath, {page:1})
    API->>BE: GET /api/v2/integrations/github/issues?page=1&per_page=25
    BE->>GH: GET /repos/owner/repo/issues?state=open&page=1&per_page=25
    GH-->>BE: issues[]
    BE-->>API: GitHubIssuesResponse (cached 60s)
    API-->>Modal: issues[]

    Note over Modal: User selects issues, clicks Import Selected
    Modal->>UI: onImport(selectedIssues)
```

---

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.