[Phase 5.5] GitHub Issues import: repository connection (PAT auth)

[frankbria]

Goal

Let users connect a GitHub repository to their CodeFRAME workspace using a Personal Access Token so that issues can be imported.

Background

Many developers already have a backlog in GitHub Issues. Requiring them to re-enter every issue into a PRD is an adoption barrier. Connection is the prerequisite for the browse and import steps.

Scope

Settings UI (new "Integrations" tab on the Settings page):

• "Connect GitHub Repository" section:
  • Text field for GitHub PAT (Personal Access Token)
  • Text field for repo in owner/repo format
  • [Connect] button — calls POST /api/v2/integrations/github/connect with PAT + repo
  • On success: show repo name + owner avatar, [Disconnect] button
  • On failure: clear error message (invalid token, repo not found, no issues:read scope)
• Disconnect flow: revokes stored token, clears repo

Backend:

• POST /api/v2/integrations/github/connect: validate PAT against GitHub API, verify issues:read scope, store encrypted
• DELETE /api/v2/integrations/github/disconnect: clear stored credentials
• GET /api/v2/integrations/github/status: returns { connected: bool, repo: "owner/repo" }
• Store PAT encrypted (same pattern as API key storage in [Phase 5.1] Settings page: API key management #555)

Out of scope

• OAuth app flow (PAT is sufficient for v1)
• Multiple repos per workspace

Acceptance criteria

• Can connect with a valid PAT and repo
• Invalid PAT or missing scope shows a clear error
• Disconnect clears the stored credential
• PAT never returned in plaintext
• 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 backend is FastAPI with SQLite via a Database facade delegating to typed repositories (e.g., APIKeyRepository). Encryption uses Fernet from cryptography (already a dependency via codeframe/core/credentials.py). The CredentialManager / CredentialStore already handles GitHub PAT storage under CredentialProvider.GIT_GITHUB. The frontend is Next.js 19 + React 19 with axios (via web-ui/src/lib/api.ts) and swr for data fetching, Tailwind CSS, and @radix-ui/react-tabs already installed.

Approach

Reuse the existing CredentialManager (Fernet-encrypted, keyring-backed) for PAT storage — no new encryption code needed. Add a new github_integration_v2.py router under codeframe/ui/routers/, a github_integrations table in the schema for per-user repo metadata, and a new Settings page with an "Integrations" tab in the Next.js app. This keeps the pattern consistent with existing v2 routers and the api.ts client.

---

Implementation Steps

1. Database: Add github_integrations table

In file:codeframe/persistence/schema_manager.py, add a new _create_github_integrations_table method called from create_schema(). The table stores per-user integration metadata (not the PAT itself — that lives in CredentialStore):

github_integrations (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id     INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  repo        TEXT NOT NULL,          -- "owner/repo"
  owner_login TEXT,                   -- from GitHub API validation
  owner_avatar_url TEXT,              -- from GitHub API validation
  connected_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id)
)

Also add a migration in _apply_migrations using _add_column_if_not_exists pattern (or a CREATE TABLE IF NOT EXISTS guard) so existing databases are upgraded safely.

---

2. Repository: GitHubIntegrationRepository

Create file:codeframe/persistence/repositories/github_integration_repository.py following the pattern of file:codeframe/persistence/repositories/api_key_repository.py and BaseRepository. Implement:

• upsert(user_id, repo, owner_login, owner_avatar_url) — insert or replace the single row for this user
• get_by_user(user_id) → Optional[Dict] — returns {repo, owner_login, owner_avatar_url, connected_at}
• delete_by_user(user_id) — removes the row

---

3. Wire repository into Database

In file:codeframe/persistence/database.py:

• Import GitHubIntegrationRepository
• Add self.github_integrations: Optional[GitHubIntegrationRepository] = None in __init__
• Instantiate it in _initialize_repositories() alongside the other repositories

---

4. Backend: GitHub validation service

Create file:codeframe/core/github_connect_service.py. This service:

• Accepts a PAT and owner/repo string
• Calls GET https://api.github.com/repos/{owner}/{repo} using httpx (already used in file:codeframe/git/github_integration.py) with Authorization: Bearer {pat}
• Checks the response X-OAuth-Scopes header (or x-accepted-oauth-scopes) for repo or public_repo scope that implies issues read access; alternatively call GET /repos/{owner}/{repo}/issues?per_page=1 to verify issues access
• On success returns {owner_login, owner_avatar_url, repo_full_name}
• Raises typed exceptions: InvalidTokenError, RepoNotFoundError, InsufficientScopeError

Use httpx.AsyncClient consistent with GitHubIntegration._make_request.

---

5. Backend: github_integrations_v2 router

Create file:codeframe/ui/routers/github_integrations_v2.py following the pattern of file:codeframe/ui/routers/blockers_v2.py:

Pydantic models:

• ConnectRequest(BaseModel): pat: str, repo: str (validated as owner/repo format)
• ConnectResponse(BaseModel): connected: bool, repo: str, owner_login: str, owner_avatar_url: str
• StatusResponse(BaseModel): connected: bool, repo: Optional[str], owner_login: Optional[str], owner_avatar_url: Optional[str]

Endpoints (prefix /api/v2/integrations/github, tags ["integrations"]):

Method	Path	Description
POST	/connect	Validate PAT, store encrypted, upsert repo metadata
DELETE	/disconnect	Delete stored PAT + repo row
GET	/status	Return connection status

POST /connect logic:

1. Get user_id from require_auth dependency (same as api_key_router.py)
2. Validate owner/repo format
3. Call GitHubConnectService.validate(pat, repo) — raises typed errors mapped to 400/401/403
4. Store PAT via CredentialManager.set_credential(CredentialProvider.GIT_GITHUB, pat, metadata={"user_id": user_id, "repo": repo}) — note: since CredentialManager is file/keyring-scoped (not per-user in DB), store the PAT in the github_integrations table encrypted using Fernet directly (same derive_encryption_key + Fernet from credentials.py), keeping the PAT never returned in plaintext
5. Upsert repo metadata via db.github_integrations.upsert(...)
6. Return ConnectResponse

PAT storage decision: Since CredentialManager is machine-scoped (not per-user), store the encrypted PAT directly in the github_integrations table as a pat_encrypted TEXT column. Use derive_encryption_key from file:codeframe/core/credentials.py to get the Fernet key, encrypt the PAT, and store the ciphertext. This is consistent with the "same pattern as API key storage in #555" intent while being DB-backed and per-user.

Add pat_encrypted TEXT to the github_integrations table definition in step 1.

DELETE /disconnect logic:

1. Get user_id from auth
2. Call db.github_integrations.delete_by_user(user_id)
3. Return 204 No Content

GET /status logic:

1. Get user_id from auth
2. Fetch row from db.github_integrations.get_by_user(user_id)
3. Return StatusResponse(connected=row is not None, repo=..., ...)

---

6. Register the new router in server.py

In file:codeframe/ui/server.py:

• Import github_integrations_v2 from codeframe.ui.routers
• Add app.include_router(github_integrations_v2.router) alongside the other v2 routers
• Add "integrations" tag entry to OPENAPI_TAGS

---

7. Frontend: integrations API client methods

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

• connect(pat: string, repo: string): Promise<ConnectResponse> — POST /api/v2/integrations/github/connect
• disconnect(): Promise<void> — DELETE /api/v2/integrations/github/disconnect
• getStatus(): Promise<StatusResponse> — GET /api/v2/integrations/github/status

Add corresponding TypeScript interfaces to file:web-ui/src/types/index.ts (or a new file:web-ui/src/types/integrations.ts):

GitHubConnectResponse { connected, repo, owner_login, owner_avatar_url }
GitHubStatusResponse  { connected, repo?, owner_login?, owner_avatar_url? }

---

8. Frontend: Settings page with Integrations tab

Create the Settings page at file:web-ui/src/app/settings/page.tsx as a 'use client' Next.js page.

Use @radix-ui/react-tabs (already in package.json) for the tab structure. Start with two tabs: General (placeholder) and Integrations.

Create file:web-ui/src/components/settings/GitHubIntegrationCard.tsx:

Wireframe:
┌─────────────────────────────────────────────────────┐
│  Connect GitHub Repository                          │
│                                                     │
│  Personal Access Token                              │
│  [••••••••••••••••••••••••••••••••]                 │
│                                                     │
│  Repository (owner/repo)                            │
│  [acme-corp/my-app                ]                 │
│                                                     │
│  [Connect]                                          │
│                                                     │
│  ⚠ Invalid token or missing issues:read scope       │
└─────────────────────────────────────────────────────┘

Connected state:
┌─────────────────────────────────────────────────────┐
│  ✓ Connected to GitHub                              │
│                                                     │
│  [avatar] acme-corp/my-app                          │
│                                                     │
│  [Disconnect]                                       │
└─────────────────────────────────────────────────────┘

Component behavior:

• On mount, call integrationsApi.getStatus() via useSWR to determine initial connected/disconnected state
• Disconnected state: Show PAT input (type="password"), repo input, and [Connect] button
• On [Connect] click: call integrationsApi.connect(pat, repo), show loading state on button, on success switch to connected state, on error display the error message below the form (map backend error codes to user-friendly strings: "Invalid token", "Repository not found", "Missing issues:read scope")
• Connected state: Show owner avatar (<img> with owner_avatar_url), repo name, and [Disconnect] button
• On [Disconnect] click: call integrationsApi.disconnect(), on success switch to disconnected state
• PAT is never displayed after submission

Create file:web-ui/src/components/settings/index.ts to export the card.

Settings page structure (file:web-ui/src/app/settings/page.tsx):

• Use Tabs, TabsList, TabsTrigger, TabsContent from @radix-ui/react-tabs
• Tab "General": placeholder content
• Tab "Integrations": render <GitHubIntegrationCard />

---

9. Add Settings link to sidebar

In file:web-ui/src/components/layout/AppSidebar.tsx:

• Import a settings icon from @hugeicons/react (e.g., Settings01Icon)
• Add a Settings nav item to NAV_ITEMS: { href: '/settings', label: 'Settings', icon: Settings01Icon, enabled: true }
• Position it at the bottom of the nav (use mt-auto or place after the main nav items)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The backend is **FastAPI** with SQLite via a `Database` facade delegating to typed repositories (e.g., `APIKeyRepository`). Encryption uses **Fernet** from `cryptography` (already a dependency via `codeframe/core/credentials.py`). The `CredentialManager` / `CredentialStore` already handles GitHub PAT storage under `CredentialProvider.GIT_GITHUB`. The frontend is **Next.js 19 + React 19** with `axios` (via `web-ui/src/lib/api.ts`) and `swr` for data fetching, Tailwind CSS, and `@radix-ui/react-tabs` already installed.

## Approach

Reuse the existing `CredentialManager` (Fernet-encrypted, keyring-backed) for PAT storage — no new encryption code needed. Add a new `github_integration_v2.py` router under `codeframe/ui/routers/`, a `github_integrations` table in the schema for per-user repo metadata, and a new Settings page with an "Integrations" tab in the Next.js app. This keeps the pattern consistent with existing v2 routers and the `api.ts` client.

---

## Implementation Steps

### 1. Database: Add `github_integrations` table

In `file:codeframe/persistence/schema_manager.py`, add a new `_create_github_integrations_table` method called from `create_schema()`. The table stores per-user integration metadata (not the PAT itself — that lives in `CredentialStore`):

```
github_integrations (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id     INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  repo        TEXT NOT NULL,          -- "owner/repo"
  owner_login TEXT,                   -- from GitHub API validation
  owner_avatar_url TEXT,              -- from GitHub API validation
  connected_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id)
)
```

Also add a migration in `_apply_migrations` using `_add_column_if_not_exists` pattern (or a `CREATE TABLE IF NOT EXISTS` guard) so existing databases are upgraded safely.

---

### 2. Repository: `GitHubIntegrationRepository`

Create `file:codeframe/persistence/repositories/github_integration_repository.py` following the pattern of `file:codeframe/persistence/repositories/api_key_repository.py` and `BaseRepository`. Implement:

- `upsert(user_id, repo, owner_login, owner_avatar_url)` — insert or replace the single row for this user
- `get_by_user(user_id)` → `Optional[Dict]` — returns `{repo, owner_login, owner_avatar_url, connected_at}`
- `delete_by_user(user_id)` — removes the row

---

### 3. Wire repository into `Database`

In `file:codeframe/persistence/database.py`:
- Import `GitHubIntegrationRepository`
- Add `self.github_integrations: Optional[GitHubIntegrationRepository] = None` in `__init__`
- Instantiate it in `_initialize_repositories()` alongside the other repositories

---

### 4. Backend: GitHub validation service

Create `file:codeframe/core/github_connect_service.py`. This service:

- Accepts a PAT and `owner/repo` string
- Calls `GET https://api.github.com/repos/{owner}/{repo}` using `httpx` (already used in `file:codeframe/git/github_integration.py`) with `Authorization: Bearer {pat}`
- Checks the response `X-OAuth-Scopes` header (or `x-accepted-oauth-scopes`) for `repo` or `public_repo` scope that implies issues read access; alternatively call `GET /repos/{owner}/{repo}/issues?per_page=1` to verify issues access
- On success returns `{owner_login, owner_avatar_url, repo_full_name}`
- Raises typed exceptions: `InvalidTokenError`, `RepoNotFoundError`, `InsufficientScopeError`

Use `httpx.AsyncClient` consistent with `GitHubIntegration._make_request`.

---

### 5. Backend: `github_integrations_v2` router

Create `file:codeframe/ui/routers/github_integrations_v2.py` following the pattern of `file:codeframe/ui/routers/blockers_v2.py`:

**Pydantic models:**
- `ConnectRequest(BaseModel)`: `pat: str`, `repo: str` (validated as `owner/repo` format)
- `ConnectResponse(BaseModel)`: `connected: bool`, `repo: str`, `owner_login: str`, `owner_avatar_url: str`
- `StatusResponse(BaseModel)`: `connected: bool`, `repo: Optional[str]`, `owner_login: Optional[str]`, `owner_avatar_url: Optional[str]`

**Endpoints** (prefix `/api/v2/integrations/github`, tags `["integrations"]`):

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/connect` | Validate PAT, store encrypted, upsert repo metadata |
| `DELETE` | `/disconnect` | Delete stored PAT + repo row |
| `GET` | `/status` | Return connection status |

**`POST /connect` logic:**
1. Get `user_id` from `require_auth` dependency (same as `api_key_router.py`)
2. Validate `owner/repo` format
3. Call `GitHubConnectService.validate(pat, repo)` — raises typed errors mapped to 400/401/403
4. Store PAT via `CredentialManager.set_credential(CredentialProvider.GIT_GITHUB, pat, metadata={"user_id": user_id, "repo": repo})` — note: since `CredentialManager` is file/keyring-scoped (not per-user in DB), store the PAT in the `github_integrations` table encrypted using Fernet directly (same `derive_encryption_key` + `Fernet` from `credentials.py`), keeping the PAT never returned in plaintext
5. Upsert repo metadata via `db.github_integrations.upsert(...)`
6. Return `ConnectResponse`

> **PAT storage decision:** Since `CredentialManager` is machine-scoped (not per-user), store the encrypted PAT directly in the `github_integrations` table as a `pat_encrypted TEXT` column. Use `derive_encryption_key` from `file:codeframe/core/credentials.py` to get the Fernet key, encrypt the PAT, and store the ciphertext. This is consistent with the "same pattern as API key storage in #555" intent while being DB-backed and per-user.

Add `pat_encrypted TEXT` to the `github_integrations` table definition in step 1.

**`DELETE /disconnect` logic:**
1. Get `user_id` from auth
2. Call `db.github_integrations.delete_by_user(user_id)`
3. Return `204 No Content`

**`GET /status` logic:**
1. Get `user_id` from auth
2. Fetch row from `db.github_integrations.get_by_user(user_id)`
3. Return `StatusResponse(connected=row is not None, repo=..., ...)`

---

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

In `file:codeframe/ui/server.py`:
- Import `github_integrations_v2` from `codeframe.ui.routers`
- Add `app.include_router(github_integrations_v2.router)` alongside the other v2 routers
- Add `"integrations"` tag entry to `OPENAPI_TAGS`

---

### 7. Frontend: `integrations` API client methods

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

- `connect(pat: string, repo: string): Promise<ConnectResponse>` — `POST /api/v2/integrations/github/connect`
- `disconnect(): Promise<void>` — `DELETE /api/v2/integrations/github/disconnect`
- `getStatus(): Promise<StatusResponse>` — `GET /api/v2/integrations/github/status`

Add corresponding TypeScript interfaces to `file:web-ui/src/types/index.ts` (or a new `file:web-ui/src/types/integrations.ts`):
```
GitHubConnectResponse { connected, repo, owner_login, owner_avatar_url }
GitHubStatusResponse  { connected, repo?, owner_login?, owner_avatar_url? }
```

---

### 8. Frontend: Settings page with Integrations tab

**Create the Settings page** at `file:web-ui/src/app/settings/page.tsx` as a `'use client'` Next.js page.

Use `@radix-ui/react-tabs` (already in `package.json`) for the tab structure. Start with two tabs: **General** (placeholder) and **Integrations**.

**Create** `file:web-ui/src/components/settings/GitHubIntegrationCard.tsx`:

```
Wireframe:
┌─────────────────────────────────────────────────────┐
│  Connect GitHub Repository                          │
│                                                     │
│  Personal Access Token                              │
│  [••••••••••••••••••••••••••••••••]                 │
│                                                     │
│  Repository (owner/repo)                            │
│  [acme-corp/my-app                ]                 │
│                                                     │
│  [Connect]                                          │
│                                                     │
│  ⚠ Invalid token or missing issues:read scope       │
└─────────────────────────────────────────────────────┘

Connected state:
┌─────────────────────────────────────────────────────┐
│  ✓ Connected to GitHub                              │
│                                                     │
│  [avatar] acme-corp/my-app                          │
│                                                     │
│  [Disconnect]                                       │
└─────────────────────────────────────────────────────┘
```

Component behavior:
- On mount, call `integrationsApi.getStatus()` via `useSWR` to determine initial connected/disconnected state
- **Disconnected state:** Show PAT input (`type="password"`), repo input, and [Connect] button
- On [Connect] click: call `integrationsApi.connect(pat, repo)`, show loading state on button, on success switch to connected state, on error display the error message below the form (map backend error codes to user-friendly strings: "Invalid token", "Repository not found", "Missing issues:read scope")
- **Connected state:** Show owner avatar (`<img>` with `owner_avatar_url`), repo name, and [Disconnect] button
- On [Disconnect] click: call `integrationsApi.disconnect()`, on success switch to disconnected state
- PAT is never displayed after submission

**Create** `file:web-ui/src/components/settings/index.ts` to export the card.

**Settings page structure** (`file:web-ui/src/app/settings/page.tsx`):
- Use `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` from `@radix-ui/react-tabs`
- Tab "General": placeholder content
- Tab "Integrations": render `<GitHubIntegrationCard />`

---

### 9. Add Settings link to sidebar

In `file:web-ui/src/components/layout/AppSidebar.tsx`:
- Import a settings icon from `@hugeicons/react` (e.g., `Settings01Icon`)
- Add a Settings nav item to `NAV_ITEMS`: `{ href: '/settings', label: 'Settings', icon: Settings01Icon, enabled: true }`
- Position it at the bottom of the nav (use `mt-auto` or place after the main nav items)

---

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.