EPIC: GitHub Integration MVP (read-only CI status + popover + OAuth)

[kirich1409]

GitHub Integration MVP

Read-only GitHub integration for Relay: when a worktree's origin points to github.com, show a visually expressive CI status badge next to the branch name (SF Symbols + color + pulse for running). Click the badge to open a popover with workflow groups → jobs; clicking a job opens the GitHub Actions run in the browser. Authentication via standalone OAuth Web Flow + PKCE through ASWebAuthenticationSession, token stored in Keychain.

Primary JTBD

«Узнать о failing CI в моей ветке без переключения контекста из терминала».

Value Statement

Single concrete advantage over the browser / GitHub Desktop / gh CLI: learn about failing CI ~30 seconds earlier, without switching context from the editor/terminal, with visual attachment to the specific worktree row.

Product Decisions (Q1–Q8 confirmed)

Q	Decision
Q1 OAuth flow	OAuth Web Flow + PKCE via ASWebAuthenticationSession. OAuth App under org androidbroadcast.
Q2 OAuth App vs GitHub App	OAuth App for MVP (scope repo). Migration to GitHub App — when Relay backend exists.
Q3 Primary JTBD	«Know about failing CI without context switch».
Q4 Multi-account	Defer. Keychain API account-keyed, UI switcher — later.
Q5 Popover content	List of jobs with icons; click → web.
Q6 Visual polish	SF Symbols + semantic colors + pulse for running.
Q7 Multiple workflows	Worst-status aggregate; groups by workflow name.
Q8 Rate limit	No hard-cap now (single-user); tracked as future.
—	GHE — out of scope. Host hardcoded api.github.com.
—	Branches without PR: show CI of latest commit.
—	Sandbox: com.apple.security.network.client entitlement.

MVP Scope (17 tasks, 7 waves)

Wave 1

• T-1 (T-1: GitRemote value type + parser in SharedModels #215) GitRemote value type + parser in SharedModels
• T-2 (T-2: GitHubIntegration SPM package skeleton #216) GitHubIntegration SPM package skeleton

Wave 2 (parallel)

• T-3 (T-3: OAuth App registration + Client ID + entitlement #217) OAuth App registration + Client ID + entitlement
• T-4 (T-4: GitCLI.listRemotes + WorktreeFeature state.remotes (cap 20) #218) GitCLI.listRemotes + WorktreeFeature.State.remotes (cap 20)
• T-5 (T-5: GitHubClient HTTP foundation — ETag, DTO, typed errors #219) GitHubClient HTTP foundation (ETag, DTO, typed errors)
• T-6 (T-6: GitHubCredentialStore — Keychain account-keyed #220) GitHubCredentialStore — Keychain account-keyed
• T-15 (T-15: Logging infrastructure with os.Logger #221) Logging infrastructure with os.Logger

Wave 3

• T-7 (T-7: OAuth + PKCE flow + GitHubAuthService #222) OAuth + PKCE flow + GitHubAuthService
• T-14 (T-14: Error-handling UX matrix (design + code contract) #223) Error-handling UX matrix (design + code contract)

Wave 4

• T-8a (T-8a: GitHubFeature state model + basic reducer #224) GitHubFeature state model + basic reducer

Wave 5 (parallel)

• T-8b (T-8b: Polling coordinator — timers, TaskGroup, ETag, pause, backoff #225) Polling coordinator (timers, TaskGroup, ETag, pause, backoff)
• T-9 (T-9: Badge UI component — SF Symbols + color + pulse #226) Badge UI component
• T-10 (T-10: Popover UI — workflow groups → jobs → web #227) Popover UI — workflow groups → jobs → web
• T-11 (T-11: Preferences pane — Sign in/out + diagnostic copy #228) Preferences pane — Sign in/out + diagnostic copy

Wave 6

• T-12 (T-12: Wire GitHubFeature into WorktreeFeature + badge in WorktreeRowView #229) Wire GitHubFeature into WorktreeFeature + badge in WorktreeRowView

Wave 7

• T-16 (T-16: Documentation — README + CLAUDE.md + docs/architecture + testplan + CI #230) Documentation (README + CLAUDE.md + docs/architecture + testplan + CI)
• T-13 (T-13: Manual E2E QA + accessibility + security checklist #231) Manual E2E QA + accessibility + security checklist

Dependency Graph

T-1 (#215)  ────────→ T-4 (#218) ────────────┐
                               │
T-2 (#216)  ───┬───→ T-3 (#217) ───┐         │
        │    T-5 (#219) ────┼───→ T-7 (#222) ┼→ T-8a (#224) ─┬──→ T-8b (#225) ┐
        │    T-6 (#220) ────┘    ↑    │        │         │
        │    T-15 (#221)         │    │        ├──→ T-9 (#226)  │
        │                 │    │        │         ├→ T-12 (#229) → T-16 (#230) ┐
        └────→ T-14 (#223) ──────┘    │        ├──→ T-10 (#227) │              │
                               │        │         │              ├→ T-13 (#231)
                               │        └──→ T-11 (#228) ┘              

Critical path: T-2 (#216) → T-5 (#219) → T-7 (#222) → T-8a (#224) → T-8b (#225) → T-12 (#229) → T-16 (#230) → T-13 (#231) (8 steps).

Constraints

• macOS 26+, Apple Silicon only
• Swift 6 strict concurrency, Sendable at API boundaries
• TCA; reuse CloudClient/RelayRESTClient + ServerKeychainStore patterns
• Zero new external dependencies
• No backend; OAuth App (not GitHub App)
• Host hardcoded api.github.com
• MVP read-only
• Polling-only, no webhooks
• One-account MVP (API account-keyed for future)
• English UI strings only

Won't (explicit)

• Create PR (neither inline nor deep link inside app)
• Rerun / cancel workflows
• Streaming job logs
• Multi-account UI switcher
• GHE Server
• GitHub App (requires backend)
• PR review actions (approve, comment, request changes)
• Inline file diff
• Webhooks / push notifications
• Issues integration
• GraphQL optimization
• Fork PR from fork-repo

Estimate

3 weeks (2 core + 1 OAuth infra + 30% buffer).

Relationships

• Sub-issues: will be linked to T-1 (T-1: GitRemote value type + parser in SharedModels #215) … T-16 (T-16: Documentation — README + CLAUDE.md + docs/architecture + testplan + CI #230) (populated on child creation)
• Related: none

Acceptance criteria (epic-level)

• All 17 sub-issues closed with their individual acceptance criteria met
• No new external Swift dependencies added
• Zero warnings under Swift 6 strict concurrency across new code
• swiftlint lint --strict green
• xcodebuild build and xcodebuild test for Relay scheme — green
• Manual E2E QA (T-13 (T-13: Manual E2E QA + accessibility + security checklist #231)) report attached to merge PR
• Documentation updated (CLAUDE.md, docs/architecture/github-integration.md, docs/testplans/15-github-integration.md, coverage-matrix, new package README)