feat(github): support per-workspace GitHub App registrations (#1810)

This commit is contained in:
Carlos Florêncio
2026-07-26 10:39:08 +01:00
committed by GitHub
parent bc218dfbbe
commit 75abf779ed
347 changed files with 36471 additions and 2896 deletions
+300
View File
@@ -0,0 +1,300 @@
---
spec: docs/specs/integrations/github-authentication.md
created: 2026-07-19
amended: 2026-07-21
status: draft
---
# Implementation Plan: Workspace GitHub Authentication
## Overview
Tasks 01-10 delivered workspace PAT/CLI/App-installation routing, personal identity, renewable
executor credentials, and workspace-aware services. Tasks 11-16 delivered an unpublished singleton
GitHub App registration. This amendment replaces that singleton with a registration catalog chosen
per workspace, adds import/create/select onboarding, moves the UX out of System Settings, and makes
callbacks, webhooks, runtime clients, and personal OAuth registration-aware.
The branch is eight commits behind and nineteen commits ahead of `origin/main`. Resolve the known
merge conflict first, then rewrite the unpublished schema before building dependent runtime and UI
layers. Released `legacy_shared` migration behavior remains unchanged.
## Architecture
`github_app_registrations` is a deployment catalog, not a global active identity. Every registration
is manifest-created or imported and has an encrypted generation bundle. A workspace App connection
stores both registration ID and installation ID. Reusing a registration is explicit and shares
root App credentials; separate registrations provide independent work/personal trust boundaries.
The manifest flow preallocates a registration UUID so all generated callback and webhook URLs are
registration-specific. Import verifies an existing App before publishing it to the catalog.
Runtime clients are resolved from a registry keyed by registration ID and generation. Webhook paths
select one candidate registration and verify its HMAC before parsing or deduplicating.
## Conflict Resolution
Merge the latest `origin/main` before production edits. Resolve the current conflict as follows:
1. `apps/web/components/github/github-settings.tsx`: preserve upstream repository-scope UI behavior,
then keep workspace-keyed GitHub auth wiring. Do not preserve the singleton System Settings
handoff because Task 18 replaces it.
`apps/web/e2e/helpers/api-client.ts` and `docs/specs/INDEX.md` currently auto-merge. Confirm their
upstream additions and this branch's GitHub authentication entries are both retained after merging.
Do not resolve conflicts by checking out either side wholesale. Confirm `git ls-files -u` is empty
and run frontend typecheck before Task 12.
## Backend
### Registration Persistence
Rewrite the unpublished singleton DDL in `apps/backend/internal/github/store.go`:
- replace `github_app_registration` with plural `github_app_registrations` and the fields in the
spec;
- replace singleton flow-head state with workspace-bound flows carrying a preallocated
registration ID;
- add `app_registration_id` constraints/FKs to workspace connections, user connections, and auth
flows;
- make webhook delivery identity composite by registration;
- retain the released old-workspace `legacy_shared` seeding path, but add no migration from the
unpublished singleton tables.
Replace `deployment_app_store.go` with registration-ID repository operations. Secret IDs are
registration/generation-specific and deletion is restricted by all workspace and personal
references. Remove the unpublished `GitHubAppConfig`, `KANDEV_GITHUB_APP_*` bindings, singleton
source resolver, and configuration tests; there is no compatibility registration or fallback.
### Create And Import Protocol
Generalize `deployment_app_manifest.go` and `deployment_app_conversion_client.go` around a
preallocated registration ID. Generated webhook, redirect, setup, and OAuth callback URLs include
that ID. The manifest visibility is user-selected and private by default. Preserve exact
permission/event policy, owner-specific GitHub submission endpoints, one-hour single-use state,
public-origin validation, response bounds, and secret-safe errors.
Add an import verifier that accepts bounded credential material, builds an App JWT, verifies
`GET /app` identity/owner/slug, validates the configured callback/webhook policy as far as GitHub's
API exposes it, and atomically stores only after verification. Missing settings become actionable
diagnostics; duplicate host/App ID returns the known registration ID.
### Runtime Registry
Replace the one `DeploymentAppRuntime` generation in `service_app_auth.go`,
`deployment_app_config.go`, and backend application wiring with a concurrency-safe registry keyed
by registration ID. Loading or invalidating one registration must not swap another. Include
registration ID/generation in installation-token cache, resolver principal, credential broker, and
singleflight keys. Runtime App auth resolves only catalog records loaded from encrypted bundles.
Startup independently loads every valid catalog entry, reports invalid entries without preventing
PAT/CLI startup, reconciles orphan secret bundles, and hot-adds a successfully created/imported
registration without restarting Kandev.
### Webhook Routing
Change webhook handling to accept a route registration ID. Load exactly one webhook secret, verify
HMAC, then parse and claim `(registration_id, delivery_id)`. Installation/repository/user events may
only mutate workspace/personal rows whose registration ID and external installation/user identity
match. Registration-specific valid failures update only that registration's health.
### Workspace App Lifecycle API
Replace deployment singleton controllers/services with catalog list, manifest start/callback,
import, rename, and guarded delete endpoints. Installation start accepts registration ID; install
and personal callbacks verify the route ID against hashed flow state. A successful installation
atomically swaps workspace connection/generation and deletes incompatible personal secrets;
failure leaves current auth active.
Extend status, mocks, E2E reset, and stable error mapping. Remove `/settings/system/github-app`
callback redirects and return to `/settings/integrations/github?workspace_id=...`. Registration API
responses expose metadata, source, health, selection, and sharing warnings but no secret or
conversion code.
## Frontend
### API, Types, And State
Replace deployment singleton types/hooks with registration catalog contracts in
`apps/web/lib/types/github.ts`, `lib/api/domains/github-auth-api.ts`, and
`hooks/domains/github/`. Catalog queries are workspace-keyed. Add create-manifest, import, rename,
delete, select/install operations and stable callback-result parsing. Remove the System Settings
route, sidebar entry, page, and deployment-only hook/components.
Workspace status carries selected registration metadata. Changing active workspace clears catalog,
status, actor, health, and in-progress form state before refetch so no prior workspace identity
flashes.
### Workspace Authentication UX
Refactor `github-connection-dialog.tsx` into a method list rather than segmented tabs. PAT and CLI
keep focused forms with matched control heights. GitHub App first explains use cases and trade-offs,
then offers known registrations, **Add existing App**, and **Create new App**. Selection leads to an
explicit installation handoff; importing/creating alone never changes workspace auth.
Move owner, public URL, permission dialog, manifest submission, and callback status UI from System
Settings into workspace GitHub settings. Add the imported-App instruction/form flow with exact
copyable URLs, GitHub settings locations, required permissions/events, bounded secret inputs, and
validation. Visibility defaults private and explains public installability versus Marketplace and
repository grants. Known shared registrations disclose their shared root identity/revocation
boundary.
`Workspace automation` copy accurately distinguishes Kandev-managed automation from unmanaged
executor overrides. Permission chips become one details button/dialog. `My GitHub identity` is
connectable only for App automation; PAT/CLI show that their verified human automation identity is
also used for personal actions without presenting a selector.
### Mobile Contract
Desktop and mobile use the same catalog and forms. Mobile presents method selection and onboarding
as a single-column page/sheet with one scroll owner, safe-area spacing, 44px controls, no fixed
footer, and no horizontal overflow. Copyable URLs and long App names wrap; secret fields and primary
actions never overlap. External GitHub navigation returns to the initiating workspace route.
## Tests
- `deployment_app_store_test.go` (renamed as appropriate): multiple registrations, secret-generation
compensation, per-registration deletion restriction, restart reload, and no singleton migration.
- `store_connections_test.go` and `personal_connection_repository_test.go`: registration FK
invariants, atomic connection switch, personal token deletion, generation revocation, workspace
delete, copy exclusion, and released legacy migration.
- `deployment_app_manifest_test.go` and conversion/import tests: route-specific URLs, default private
and explicit public manifests, owner URLs, exact policy, state replay/expiry, response bounds,
duplicate import, GitHub identity mismatch, and no secret errors.
- `service_app_auth_test.go`, resolver, token-cache, and broker tests: concurrent different
registrations, intentional reuse, hot add/invalidate, registration-keyed caches, and no
cross-registration fallback.
- `webhook_service_test.go`: wrong route/signature, composite dedupe, matching registration plus
installation, health isolation, suspension/deletion/repository changes, and personal revocation.
- Controller/service tests: catalog CRUD, create/import/install callbacks, stale flow, guarded
delete, status metadata, mock/reset isolation, and secret-free JSON.
- Frontend unit tests: workspace switching, method comparison, known registration selection,
import/create validation, private/public disclosure, permissions dialog, callback outcomes,
matched control heights, and conditional personal identity.
## E2E Tests
Update the GitHub authentication suites rather than retaining System Settings registration tests:
- workspace A creates a private App and workspace B imports another App; each status and installation
remains isolated;
- two workspaces intentionally select the same known registration and show the shared-root warning
while retaining different installation/repository status;
- creation/import cancellation and invalid/replayed callbacks preserve current automation;
- switching Apps removes incompatible personal identity;
- desktop and mobile complete PAT, CLI, select, import, create, install, and permissions flows with
no clipping, overlap, or horizontal overflow.
Real GitHub staging remains necessary for one manifest conversion, imported-App verification,
installation, OAuth, and correctly signed webhook delivery.
## Public Documentation
Update `docs/public/integrations.md` and `docs/public/configuration.md` for method choice,
registration reuse versus strict isolation, import/create instructions, private/public meaning,
callback/webhook paths, and permissions/events. Delete the unpublished App environment variables and
instructions rather than documenting them as a supported path. Reconcile `docs/ARCHITECTURE.md`,
`apps/backend/AGENTS.md`, feature coverage metadata, and screenshots/terminology that still claim
one deployment App or System Settings ownership.
## Implementation Waves
Tasks 01-10 remain completed implementation history for the workspace credential foundation.
Superseded singleton Tasks 11-16 are replaced by the pending tasks below.
### Completed Workspace Credential Foundation
- [x] [Task 01: Persistence and legacy migration](task-01-persistence-migration.md) - done
- [x] [Task 02: GitHub App token primitives](task-02-app-token-primitives.md) - done
- [x] [Task 03: Workspace PAT and CLI resolver](task-03-workspace-credential-resolver.md) - done
- [x] [Task 04: App installation and personal OAuth lifecycle](task-04-app-oauth-webhooks.md) - done
- [x] [Task 05: Workspace-aware service routing](task-05-service-routing.md) - done
- [x] [Task 06: Renewable executor credentials](task-06-executor-credentials.md) - done
- [x] [Task 07: Connection API, health, and mocks](task-07-http-health-mocks.md) - done
- [x] [Task 08: Workspace and personal settings](task-08-frontend-settings.md) - done
- [x] [Task 09: Initial E2E and public docs](task-09-e2e-docs.md) - done
- [x] [Task 10: Initial QA and security](task-10-qa-security.md) - done
### Wave 0: Reconcile Main
- [x] [Task 11: Reconcile latest main](task-11-reconcile-main.md) - done
### Wave 1: Persistence Contract
- [x] [Task 12: Registration persistence](task-12-registration-persistence.md) - done
### Wave 2: Onboarding Protocol
- [x] [Task 13: Registration onboarding protocol](task-13-registration-onboarding-protocol.md) - done
### Wave 3: Registration-Aware Runtime (parallel)
- [x] [Task 14: Runtime registration resolution](task-14-runtime-registration-resolution.md) - done
- [x] [Task 15: Registration webhook routing](task-15-registration-webhook-routing.md) - done
Task 14 owns runtime clients, resolver, caches, and broker files. Task 15 owns webhook service and
delivery persistence. They share only Task 12 models and can run independently after Task 13.
### Wave 4: Backend API
- [x] [Task 16: Workspace App lifecycle API](task-16-workspace-app-lifecycle-api.md) - done
### Wave 5: Frontend Contract
- [x] [Task 17: Frontend registration client](task-17-frontend-registration-client.md) - done
### Wave 6: Workspace UX
- [x] [Task 18: Workspace authentication UX](task-18-workspace-authentication-ux.md) - done
### Wave 7: Product Proof (parallel)
- [x] [Task 19: Registration E2E coverage](task-19-registration-e2e.md) - done
- [x] [Task 20: Registration documentation](task-20-registration-documentation.md) - done
Task 19 owns Playwright fixtures/specs. Task 20 owns public and architecture documentation.
### Wave 8: Integrated Review
- [x] [Task 21: Security and QA verification](task-21-security-qa.md) - done
## Final Verification
Run formatting before lint:
```bash
rtk make -C apps/backend fmt
rtk make -C apps/backend test
rtk make -C apps/backend lint
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test
cd apps && rtk pnpm --filter @kandev/web lint
cd apps/web && rtk pnpm e2e:run tests/integrations/github-authentication.spec.ts -- --project=chromium
cd apps/web && rtk pnpm e2e:run --no-build tests/integrations/mobile-github-auth-settings.spec.ts -- --project=mobile-chrome
test -z "$(rg -l 'KANDEV_GITHUB_APP' apps docs/public || true)"
git diff --check
```
Also inspect desktop and mobile Playwright screenshots and verify document horizontal overflow is
zero. The final security pass scans logs, API responses, redirects, executor environments, process
arguments, persisted metadata, and E2E artifacts for PATs, App private keys, App client/webhook
secrets, personal tokens, refresh tokens, and live installation tokens.
## Risks
- Existing runtime construction assumes one swappable App. Any hidden singleton can route the right
workspace through the wrong key; concurrency and negative isolation tests are mandatory.
- Imported GitHub App settings cannot all be read through GitHub APIs. The guide must separate
verified identity from user-confirmed callback/webhook policy and keep capability diagnostics
visible after installation.
- A manifest conversion returns the only generated private key. Persistence failure can leave an
orphan App on GitHub, so recovery instructions must not claim Kandev can delete it.
- Reusing a registration is weaker isolation than separate Apps. The UI must state the shared root
credential and revocation boundary before installation.
- The current runtime has no authenticated admin role. Registration catalog visibility and mutation
remain acceptable only inside the documented trusted-single-user boundary.
## Approval
Awaiting approval of the amended spec, ADR, wave graph, and verification commands before Task 11
starts.
@@ -0,0 +1,49 @@
---
id: "01-persistence-migration"
title: "Persistence and legacy migration"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 01: Persistence And Legacy Migration
## Inputs
- Spec: Data Model, Persistence Guarantees, legacy/new-workspace/copy scenarios.
- ADR 0047: deployment/workspace/user ownership and the temporary legacy exception.
- Patterns: `apps/backend/internal/github/store.go`,
`internal/integrations/secretadapter`, and ADR 0027.
## Acceptance
- The four connection/auth tables and workspace ownership columns are created by a replayable,
SQLite/Postgres-compatible migration with uniqueness and state constraints.
- Migration creates `legacy_shared` only for workspaces present during upgrade, backfills task PR
and watch ownership, and fails closed on ambiguous/missing ownership.
- Workspace delete/reset removes owned connection data and secrets; workspace copy never copies
automation or personal auth.
## Files Likely Touched
- `apps/backend/internal/github/models.go`
- `apps/backend/internal/github/store.go`
- `apps/backend/internal/github/store_connections.go` (new)
- `apps/backend/internal/github/store_connections_test.go` (new)
- `apps/backend/internal/github/copy.go`
- `apps/backend/internal/github/copy_test.go`
- `apps/backend/internal/backendapp/e2e_reset.go`
## Verification
```bash
cd apps/backend && rtk go test ./internal/github -run 'TestStore.*(Connection|Legacy|WorkspaceBackfill|Copy)'
cd apps/backend && rtk go test ./internal/backendapp -run 'Test.*E2EReset.*GitHub'
```
## Output Contract
Report schema and migration behavior, secret-key ownership, tests run, files touched, blockers, and
follow-up risks. Set this task to `done` and update `plan.md` only after acceptance passes.
@@ -0,0 +1,51 @@
---
id: "02-app-token-primitives"
title: "GitHub App token primitives"
status: completed
wave: 2
depends_on: ["01-persistence-migration"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 02: GitHub App Token Primitives
## Inputs
- Spec: GitHub App Permissions, Failure Modes, and installation-token persistence guarantees.
- ADR 0047: deployment App ownership and memory-only token minting.
- Official GitHub App JWT, installation token, and permission contracts linked from the public docs
task.
## Acceptance
- Deployment App config validates all-or-none secret material, file/multiline private keys, public
callback URL safety, and exposes only a non-secret availability result.
- A token-source-neutral REST/GraphQL client supports PAT, App installation, and App user tokens
without erasing principal metadata.
- Installation tokens are minted with valid JWT claims, permission-scoped, singleflight-cached,
refreshed before expiry, and never returned after expiry.
## Files Likely Touched
- `apps/backend/internal/common/config/config.go`
- `apps/backend/internal/common/config/config_test.go`
- `apps/backend/internal/github/pat_client.go` (renamed/refactored)
- `apps/backend/internal/github/token_client.go` (new)
- `apps/backend/internal/github/app_client.go` (new)
- `apps/backend/internal/github/app_token_cache.go` (new)
- `apps/backend/internal/github/app_client_test.go` (new)
- `apps/backend/internal/github/app_token_cache_test.go` (new)
- `apps/backend/internal/backendapp/helpers.go`
## Verification
```bash
cd apps/backend && rtk go test ./internal/common/config -run 'Test.*GitHubApp'
cd apps/backend && rtk go test ./internal/github -run 'Test(AppClient|InstallationToken|TokenClient)'
```
## Output Contract
Report config contract, permission mapping, refresh margin, cache key, tests run, files touched,
blockers, and risks. Do not wire service operations in this task.
@@ -0,0 +1,51 @@
---
id: "03-workspace-credential-resolver"
title: "Workspace PAT and CLI resolver"
status: completed
wave: 2
depends_on: ["01-persistence-migration"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 03: Workspace PAT And CLI Resolver
## Inputs
- Spec: What, Identity And Routing, PAT/CLI failure modes, and first five scenarios.
- ADR 0047: explicit purpose resolution and deterministic named CLI accounts.
- Existing `factory.go`, `gh_client.go`, `service_tokens.go`, and rate/cache helpers.
## Acceptance
- Resolver requests require workspace and purpose and return a client, verified principal,
capabilities, generation, and expiry without process-global operational state.
- PAT and named CLI replacements validate first and atomically replace only the target workspace;
CLI commands select `--hostname` and `--user`, strip ambient token variables, and never switch
the host account.
- `legacy_shared` preserves current precedence only for migrated rows; disconnected/new/invalid
workspaces never fall through to it or another workspace.
## Files Likely Touched
- `apps/backend/internal/github/auth_principal.go` (new)
- `apps/backend/internal/github/auth_resolver.go` (new)
- `apps/backend/internal/github/auth_resolver_test.go` (new)
- `apps/backend/internal/github/gh_accounts.go` (new)
- `apps/backend/internal/github/gh_accounts_test.go` (new)
- `apps/backend/internal/github/factory.go`
- `apps/backend/internal/github/factory_test.go`
- `apps/backend/internal/github/gh_client.go`
- `apps/backend/internal/github/service_connections.go` (new)
- `apps/backend/internal/github/service_tokens.go`
## Verification
```bash
cd apps/backend && rtk go test ./internal/github -run 'Test(CredentialResolver|GHAccounts|WorkspaceConnection|LegacyShared)'
```
## Output Contract
Report the resolver interface, exact CLI subprocess environment, replacement/rollback behavior,
tests run, files touched, blockers, and risks. Do not migrate domain service call sites in this task.
@@ -0,0 +1,48 @@
---
id: "04-app-oauth-webhooks"
title: "App installation and personal OAuth lifecycle"
status: completed
wave: 3
depends_on: ["01-persistence-migration", "02-app-token-primitives", "03-workspace-credential-resolver"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 04: App Installation And Personal OAuth Lifecycle
## Inputs
- Spec: App/personal API contracts, both state machines, permissions, callback/webhook scenarios.
- ADR 0047: verified association, PKCE, encrypted user tokens, webhook dedupe.
- Task 01 stores and Task 02 App primitives.
## Acceptance
- Setup and personal OAuth starts create expiring, single-use, workspace/user-bound state; callbacks
reject expiry, replay, mismatch, spoofed installation, and unverified user association.
- Personal access/refresh secrets and expiry metadata update atomically, refresh before use, and
never fall back across users; revocation removes effective personal auth.
- HMAC-verified, delivery-deduplicated webhooks apply installation suspend/unsuspend/delete,
repository-access, and user-authorization transitions only to known bindings.
## Files Likely Touched
- `apps/backend/internal/github/oauth_flow.go` (new)
- `apps/backend/internal/github/oauth_flow_test.go` (new)
- `apps/backend/internal/github/app_installation_service.go` (new)
- `apps/backend/internal/github/app_installation_service_test.go` (new)
- `apps/backend/internal/github/personal_auth_service.go` (new)
- `apps/backend/internal/github/personal_auth_service_test.go` (new)
- `apps/backend/internal/github/webhook_service.go` (new)
- `apps/backend/internal/github/webhook_service_test.go` (new)
## Verification
```bash
cd apps/backend && rtk go test ./internal/github -run 'Test(OAuthFlow|AppInstallation|PersonalAuth|GitHubWebhook)'
```
## Output Contract
Report state TTLs, verification calls, refresh compensation, webhook transitions, tests run, files
touched, blockers, and risks. HTTP route wiring remains Task 07.
@@ -0,0 +1,65 @@
---
id: "05-service-routing"
title: "Workspace-aware GitHub service routing"
status: completed
wave: 4
depends_on: ["02-app-token-primitives", "03-workspace-credential-resolver", "04-app-oauth-webhooks"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 05: Workspace-Aware GitHub Service Routing
## Inputs
- Spec: Identity And Routing, repository boundary, failure modes, and background/personal scenarios.
- ADR 0047: no process-global operational client and principal-scoped cache/rate state.
- Resolver contract from Tasks 02-04.
## Acceptance
- All GitHub domain operations resolve an explicit workspace/purpose; direct production use of the
singleton `Service.client` and `Service.authMethod` is removed.
- Task, PR, issue, watch, cleanup, and CI paths derive and verify workspace ownership and fail closed
when absent or contradictory; concurrent workspaces cannot share client, cache, rate, or
singleflight state.
- Personal reads/mutations follow the specified fallback/attribution rules and enforce the
automation-visible plus configured repository intersection before provider calls.
- App-backed review watches use a persisted verified target login rather than `@me`; migrated
watches without one are disabled without a provider call.
## Files Likely Touched
- `apps/backend/internal/github/service.go`
- `apps/backend/internal/github/service_pr.go`
- `apps/backend/internal/github/service_pr_status.go`
- `apps/backend/internal/github/service_reviews.go`
- `apps/backend/internal/github/service_issues.go`
- `apps/backend/internal/github/service_accessible_repos.go`
- `apps/backend/internal/github/workspace_settings_service.go`
- `apps/backend/internal/github/service_pr_watch.go`
- `apps/backend/internal/github/service_pr_watch_batched.go`
- `apps/backend/internal/github/service_cleanup.go`
- `apps/backend/internal/github/poller.go`
- `apps/backend/internal/github/service_ci_automation.go`
- `apps/backend/internal/github/service_task_issue.go`
- `apps/backend/internal/orchestrator/event_handlers_github*.go`
- `apps/backend/internal/automation/evaluator.go`
- `apps/backend/internal/workflowsync/service.go`
- `apps/backend/internal/task/share/` GitHub Gist call sites
## Verification
```bash
cd apps/backend && rtk go test ./internal/github
cd apps/backend && rtk go test ./internal/orchestrator ./internal/automation -run 'Test.*GitHub'
cd apps/backend && rtk rg 's\.client|s\.authMethod' internal/github
```
The final search may find only constructor/test compatibility code with an explicit justification;
it must find no operational service path.
## Output Contract
Report migrated call families, ownership derivation, actor routing, cache/rate keys, tests run, files
touched, blockers, and remaining compatibility references.
@@ -0,0 +1,56 @@
---
id: "06-executor-credentials"
title: "Renewable executor GitHub credentials"
status: completed
wave: 4
depends_on: ["02-app-token-primitives", "03-workspace-credential-resolver"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 06: Renewable Executor GitHub Credentials
## Inputs
- Spec: executor routing, failure mode, persistence guarantee, and >1-hour task scenario.
- ADR 0047: task-scoped broker lease and no deployment/personal secret injection.
- Existing executor remote-auth handling and agentctl authenticated API conventions.
## Acceptance
- Git operations obtain workspace automation credentials through a task/session/repository-scoped,
hashed, expiring broker lease; every request rechecks workspace scope and credential generation.
- `agentctl git-credential` implements Git's helper protocol and refreshes App tokens on demand for
local, Docker, SSH, and remote executor paths; an isolated broker-aware `gh` shim refreshes before
each CLI invocation.
- Launch environments, command arguments, logs, and persisted metadata contain no App private key,
personal token, refresh token, or global fallback token; disconnect/revocation makes old leases
unusable.
## Files Likely Touched
- `apps/backend/internal/github/credential_broker.go` (new)
- `apps/backend/internal/github/credential_broker_test.go` (new)
- `apps/backend/internal/github/controller_credentials.go` (new)
- `apps/backend/internal/orchestrator/executor/executor_credentials.go`
- `apps/backend/internal/orchestrator/executor/executor_execute.go`
- `apps/backend/internal/orchestrator/executor/executor_credentials_test.go`
- `apps/backend/cmd/agentctl/github_credential.go` (new)
- `apps/backend/cmd/agentctl/github_credential_test.go` (new)
- `apps/backend/cmd/agentctl/github_cli_shim.go` (new)
- `apps/backend/cmd/agentctl/github_cli_shim_test.go` (new)
- `apps/backend/internal/agentctl/server/config/config.go`
- `apps/backend/internal/agent/remoteauth/catalog.go`
## Verification
```bash
cd apps/backend && rtk go test ./internal/github -run 'TestCredentialBroker'
cd apps/backend && rtk go test ./internal/orchestrator/executor -run 'Test.*GitHubCredential'
cd apps/backend && rtk go test ./cmd/agentctl -run 'TestGitHubCredential'
```
## Output Contract
Report broker transport for every executor, lease lifetime/revocation rules, helper configuration,
secret-leak assertions, tests run, files touched, blockers, and risks.
@@ -0,0 +1,55 @@
---
id: "07-http-health-mocks"
title: "Connection API, health, and mocks"
status: completed
wave: 5
depends_on: ["04-app-oauth-webhooks", "05-service-routing", "06-executor-credentials"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 07: Connection API, Health, And Mocks
## Inputs
- Spec: complete API Surface, Permissions, stable observable failures, and App capability status.
- Completed service, lifecycle, and broker contracts.
- Existing Gin controller/handler and E2E mock patterns.
## Acceptance
- Every specified status/configure/disconnect/start/callback/webhook endpoint is wired with mandatory
workspace/current-user ownership, stable error codes, safe redirects, and no secret responses.
- The old token endpoint is a workspace-required, one-release deprecated alias; health reports
workspace automation/personal capability state instead of one global boolean.
- E2E mocks independently model workspace principals, App permissions/expiry, callback state, and
webhook transitions, and reset clears all new state.
## Files Likely Touched
- `apps/backend/internal/github/controller.go`
- `apps/backend/internal/github/controller_connections.go` (new)
- `apps/backend/internal/github/controller_app.go` (new)
- `apps/backend/internal/github/controller_personal.go` (new)
- `apps/backend/internal/github/controller_webhook.go` (new)
- `apps/backend/internal/github/handlers.go`
- `apps/backend/internal/github/controller_test.go`
- `apps/backend/internal/github/mock_client.go`
- `apps/backend/internal/github/mock_controller.go`
- `apps/backend/internal/github/mock_controller_test.go`
- `apps/backend/internal/health/checks.go`
- `apps/backend/internal/health/checks_test.go`
- `apps/backend/internal/backendapp/helpers.go`
- `apps/backend/internal/backendapp/e2e_reset.go`
## Verification
```bash
cd apps/backend && rtk go test ./internal/github -run 'TestHttp|TestMock'
cd apps/backend && rtk go test ./internal/health ./internal/backendapp -run 'Test.*GitHub'
```
## Output Contract
Report final route/request/response shapes, auth/redirect handling, compatibility headers, mock
controls, tests run, files touched, blockers, and risks.
@@ -0,0 +1,53 @@
---
id: "08-frontend-settings"
title: "Workspace and personal GitHub settings"
status: completed
wave: 6
depends_on: ["07-http-health-mocks"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 08: Workspace And Personal GitHub Settings
## Inputs
- Spec: What, Identity And Routing, state machines, failure modes, and desktop/mobile scenarios.
- Task 07 API contract.
- `apps/web/AGENTS.md` and the mobile-parity skill.
## Acceptance
- GitHub status/state is keyed by workspace and refetched on workspace changes without showing a
previous workspace's actor, repositories, diagnostics, permissions, or rate limits.
- Settings expose feature-complete Workspace automation and My GitHub identity sections for legacy,
PAT, named CLI, App installation, personal connect/reconnect, capability, and actor states.
- App-only `My GitHub` gating and user-triggered mutation attribution match the spec on desktop and
mobile; all controls fit and remain keyboard/screen-reader accessible.
## Files Likely Touched
- `apps/web/lib/api/domains/github-api.ts`
- `apps/web/lib/types/github.ts`
- `apps/web/lib/state/slices/github/github-slice.ts`
- `apps/web/lib/state/slices/github/github-slice.test.ts`
- `apps/web/hooks/domains/github/use-github-status.ts`
- `apps/web/hooks/domains/github/use-github-status.test.tsx` (new)
- `apps/web/components/github/github-status.tsx`
- `apps/web/components/github/github-settings.tsx`
- `apps/web/components/integrations/integrations-menu.tsx`
- `apps/web/app/github/github-page-client.tsx`
- GitHub PR review/merge components that display the effective actor
## Verification
```bash
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test -- github
cd apps && rtk pnpm --filter @kandev/web lint
```
## Output Contract
Report states and responsive behavior implemented, accessibility checks, tests run, screenshots
inspected, files touched, blockers, and risks.
@@ -0,0 +1,59 @@
---
id: "09-e2e-docs"
title: "End-to-end coverage and public docs"
status: done
wave: 7
depends_on: ["08-frontend-settings"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 09: End-To-End Coverage And Public Docs
## Inputs
- Every spec scenario.
- Task 07 mock controls and Task 08 user interface.
- `docs/public/integrations.md`, `docs/public/configuration.md`, E2E and docs-maintainer skills.
## Acceptance
- Playwright covers cross-workspace isolation, legacy/new migration, CLI/PAT selection, App install
callback validation, App-only/personal behavior, capabilities, suspension/revocation, and
disconnect/reconnect on desktop and mobile.
- Screenshots confirm both identity sections and all status/action text fit without overlap at the
supported viewports.
- Public docs explain local and hosted setup, App permissions/events, actor semantics, migration,
callback/webhook configuration, secret files, and recovery without exposing example live secrets.
## Files Likely Touched
- `apps/web/e2e/tests/integrations/github-workspace-settings.spec.ts`
- `apps/web/e2e/tests/integrations/github-authentication.spec.ts` (new)
- `apps/web/e2e/helpers/api-client.ts`
- `docs/public/integrations.md`
- `docs/public/configuration.md`
- `apps/backend/internal/integrations/AGENTS.md` only if the shared integration pattern changes
- `apps/web/AGENTS.md` only if frontend conventions change
## Verification
```bash
cd apps/web && rtk pnpm exec playwright test --config e2e/playwright.config.ts e2e/tests/integrations/github-authentication.spec.ts --project=chromium
cd apps/web && rtk pnpm exec playwright test --config e2e/playwright.config.ts e2e/tests/integrations/mobile-github-auth-settings.spec.ts --project=mobile-chrome
```
Also validate every documented environment variable against the typed config and inspect the
captured desktop/mobile screenshots.
Completed on 2026-07-19. The desktop suite passed four scenarios and the dedicated mobile suite
passed two scenarios. Captures for App suspension, personal revocation, permission gaps, and narrow
viewport layout were inspected; controls and the fixed Config Chat action do not overlap. Public
configuration and integration docs were validated against the typed config. The organization App
installation, OAuth exchange, and webhook round trip still require a deployed staging instance
with real GitHub credentials.
## Output Contract
Report scenario coverage, screenshots inspected, documentation/config cross-check, tests run, files
touched, blockers, and any platform flows requiring a real GitHub App staging check.
@@ -0,0 +1,65 @@
---
id: "10-qa-security"
title: "Integrated QA and security verification"
status: done
wave: 7
depends_on:
["01-persistence-migration", "02-app-token-primitives", "03-workspace-credential-resolver",
"04-app-oauth-webhooks", "05-service-routing", "06-executor-credentials",
"07-http-health-mocks", "08-frontend-settings", "09-e2e-docs"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 10: Integrated QA And Security Verification
## Inputs
- Full spec, ADR 0047, completed Tasks 01-09, QA/security/code-review/verify skills.
- Final Verification and Risks sections in `plan.md`.
## Acceptance
- A conformance pass exercises every spec scenario, including concurrent isolation, token expiry,
callback replay, webhook replay, missing permissions, wrong repository, and every supported
executor credential path.
- Security review finds no cross-workspace/user fallback, confused-deputy repository expansion,
unverified callback binding, or secret exposure in APIs, logs, args, env, DB metadata, snapshots,
and generated diagnostics.
- Backend format/test/lint, frontend typecheck/test/lint, and focused desktop/mobile E2E all pass;
spec, ADR, plan, task statuses, public docs, and scoped guidance agree with shipped behavior.
## Files Likely Touched
- Focused regression tests in files owned by Tasks 01-09
- `docs/specs/integrations/github-authentication.md`
- `docs/plans/github-authentication/plan.md`
- All task frontmatter statuses
- Relevant `AGENTS.md` files only when implementation established a durable convention
## Verification
```bash
rtk make -C apps/backend fmt
rtk make -C apps/backend test
rtk make -C apps/backend lint
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test
cd apps && rtk pnpm --filter @kandev/web lint
cd apps/web && rtk pnpm exec playwright test --config e2e/playwright.config.ts e2e/tests/integrations/github-authentication.spec.ts --project=chromium
cd apps/web && rtk pnpm exec playwright test --config e2e/playwright.config.ts e2e/tests/integrations/mobile-github-auth-settings.spec.ts --project=mobile-chrome
```
Completed on 2026-07-19. Backend format, tests, lint, binaries, the Sprites-tag compile check,
frontend typecheck, lint, build, all 5,380 frontend tests, public-doc validation, and focused
desktop/mobile E2E passed. Concurrency and replay regressions cover OAuth callbacks, personal token
generation, webhook delivery and repository changes, broker leases, executor reconnect, and exact
broker readiness. The final review found no blocking cross-workspace fallback, callback binding,
repository expansion, or secret exposure issue. The only residual check is a real deployed GitHub
App installation/OAuth/webhook round trip in staging.
## Output Contract
Record every command and environment covered, security findings and fixes, residual staging checks,
files touched, and readiness. Mark the plan done and spec shipped only when all acceptance criteria
pass.
@@ -0,0 +1,47 @@
---
id: "11-reconcile-main"
title: "Reconcile latest main"
status: done
wave: 0
depends_on: []
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 11: Reconcile Latest Main
## Acceptance
1. The branch contains current `origin/main` with no unmerged paths or conflict markers.
2. Upstream repository-scope UI/API helper behavior and this branch's workspace-keyed GitHub auth
behavior are both retained.
3. Frontend typecheck and the existing GitHub connection-dialog test pass.
## Verification
```bash
test -z "$(git ls-files -u)"
git diff --check
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test -- components/github/github-connection-dialog.test.tsx
```
## Files Likely Touched
- `apps/web/components/github/github-settings.tsx`
- `apps/web/e2e/helpers/api-client.ts`
- `docs/specs/INDEX.md`
## Dependencies
None.
## Inputs
- Plan: **Conflict Resolution**.
- Use a merge of current `origin/main`; do not choose an entire side for files changed in both.
## Output Contract
Report merge commit/base, resolutions made, commands run, files touched, blockers/risks, and update
this task plus `plan.md` to done.
@@ -0,0 +1,61 @@
---
id: "12-registration-persistence"
title: "Registration persistence"
status: done
wave: 1
depends_on: ["11-reconcile-main"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 12: Registration Persistence
## Acceptance
1. The unpublished singleton tables are replaced by the plural registration, workspace-bound flow,
registration FK, and composite delivery schema from the spec without changing released
`legacy_shared` migration behavior.
2. Managed/imported registrations use independent encrypted generation bundles; the unpublished App
environment configuration, bindings, source resolver, and compatibility behavior are removed.
3. Delete/reference constraints, compensation, restart reload metadata, workspace copy/delete, and
personal generation invalidation have focused real-database tests.
## Verification
```bash
rtk go test ./internal/github -run 'Test.*(Registration|WorkspaceConnection|PersonalConnection|Legacy)'
test -z "$(rg -l 'KANDEV_GITHUB_APP' internal/common/config internal/github || true)"
```
Run from `apps/backend`.
## Files Likely Touched
- `apps/backend/internal/github/models.go`
- `apps/backend/internal/github/store.go`
- `apps/backend/internal/github/deployment_app_store.go` (rename to registration-oriented name)
- `apps/backend/internal/github/deployment_app_store_test.go` (rename with production file)
- `apps/backend/internal/github/store_connections.go`
- `apps/backend/internal/github/store_connections_test.go`
- `apps/backend/internal/github/personal_connection_repository.go`
- `apps/backend/internal/github/personal_connection_repository_test.go`
- `apps/backend/internal/github/deployment_app_config.go` (remove/replace with catalog-only resolver)
- `apps/backend/internal/github/deployment_app_config_test.go` (remove/replace)
- `apps/backend/internal/common/config/config.go`
- `apps/backend/internal/common/config/config_test.go`
## Dependencies
Task 11.
## Inputs
- Spec: **Data Model**, **Persistence Guarantees**, and removal of unpublished App configuration in
**What**.
- ADR: `docs/decisions/2026-07-21-workspace-selectable-github-app-registrations.md`.
- Preserve existing encrypted secret-store compensation patterns and released legacy seeding.
## Output Contract
Report schema/repository contract, migration assumptions, tests run, files touched, blockers/risks,
and update this task plus `plan.md` to done.
@@ -0,0 +1,53 @@
---
id: "13-registration-onboarding-protocol"
title: "Registration onboarding protocol"
status: done
wave: 2
depends_on: ["12-registration-persistence"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 13: Registration Onboarding Protocol
## Acceptance
1. Manifest construction uses a preallocated registration ID in every Kandev URL, defaults private,
supports explicit public visibility, and preserves exact permission/event policy.
2. Existing-App import verifies GitHub App identity before persistence, bounds secret inputs and
provider responses, and returns actionable secret-safe errors including duplicate registration.
3. Owner URL, origin validation, one-hour state expiry/replay, conversion failure, and import
mismatch are covered by focused tests.
## Verification
```bash
rtk go test ./internal/github -run 'Test.*(Manifest|Conversion|Import|PublicBaseURL)'
```
Run from `apps/backend`.
## Files Likely Touched
- `apps/backend/internal/github/deployment_app_manifest.go` (rename/generalize)
- `apps/backend/internal/github/deployment_app_manifest_test.go`
- `apps/backend/internal/github/deployment_app_conversion_client.go` (rename/generalize)
- `apps/backend/internal/github/deployment_app_conversion_client_test.go`
- `apps/backend/internal/github/app_client.go`
- `apps/backend/internal/github/app_client_test.go`
- `apps/backend/internal/github/app_registration_import.go` (new)
- `apps/backend/internal/github/app_registration_import_test.go` (new)
## Dependencies
Task 12.
## Inputs
- Spec: **GitHub App Policy**, registration catalog API, registration state machine, and security.
- GitHub App Manifest and App identity clients already present on the branch.
## Output Contract
Report protocol/validation behavior, tests run, files touched, blockers/risks, and update this task
plus `plan.md` to done.
@@ -0,0 +1,59 @@
---
id: "14-runtime-registration-resolution"
title: "Runtime registration resolution"
status: done
wave: 3
depends_on: ["13-registration-onboarding-protocol"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 14: Runtime Registration Resolution
## Acceptance
1. App runtime clients are independently loaded, hot-added, invalidated, and resolved by
registration ID/generation; no global active App or fallback remains.
2. Installation token cache, auth resolver, broker lease, principal, rate/singleflight keys include
registration identity where required and preserve workspace/repository isolation.
3. Concurrent different registrations, intentional reuse, restart, and one-registration failure are
covered without leaking root or personal secrets.
## Verification
```bash
rtk go test ./internal/github -run 'Test.*(AppAuth|AuthResolver|TokenCache|CredentialBroker|Registration)'
rtk go test ./internal/backendapp -run 'Test.*GitHub'
```
Run from `apps/backend`.
## Files Likely Touched
- `apps/backend/internal/github/service_app_auth.go`
- `apps/backend/internal/github/service_app_auth_test.go`
- `apps/backend/internal/github/auth_resolver.go`
- `apps/backend/internal/github/auth_resolver_test.go`
- `apps/backend/internal/github/app_token_cache.go`
- `apps/backend/internal/github/app_token_cache_test.go`
- `apps/backend/internal/github/app_credential_provider.go`
- `apps/backend/internal/github/credential_broker.go`
- `apps/backend/internal/github/credential_broker_test.go`
- `apps/backend/internal/github/auth_principal.go`
- `apps/backend/internal/backendapp/services.go`
- `apps/backend/internal/backendapp/main.go`
- `apps/backend/internal/backendapp/github_deployment_app_test.go` (rename/generalize)
## Dependencies
Task 13.
## Inputs
- Spec: **Identity And Routing**, workspace automation state machine, persistence, and security.
- Task 12 repository contracts and Task 13 verified registration objects.
## Output Contract
Report runtime registry/cache boundaries, tests run, files touched, blockers/risks, and update this
task plus `plan.md` to done.
@@ -0,0 +1,51 @@
---
id: "15-registration-webhook-routing"
title: "Registration webhook routing"
status: done
wave: 3
depends_on: ["13-registration-onboarding-protocol"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 15: Registration Webhook Routing
## Acceptance
1. The public webhook route selects one registration, validates its HMAC before parsing or claiming,
and deduplicates by registration plus delivery ID.
2. Installation, repository, suspension, deletion, and user revocation events only mutate rows that
match registration and external identity; health changes are registration-local.
3. Wrong route/signature, same delivery across Apps, unknown installation, replay, and concurrent
delivery behavior have regression tests.
## Verification
```bash
rtk go test ./internal/github -run 'Test.*Webhook'
```
Run from `apps/backend`.
## Files Likely Touched
- `apps/backend/internal/github/webhook_service.go`
- `apps/backend/internal/github/webhook_service_test.go`
- `apps/backend/internal/github/controller_auth.go`
- `apps/backend/internal/github/controller_test.go`
- `apps/backend/internal/github/store.go`
- registration repository file created by Task 12
## Dependencies
Task 13.
## Inputs
- Spec: webhook API, `github_webhook_deliveries`, security, and failure scenarios.
- Task 12 composite delivery and registration lookup contracts.
## Output Contract
Report signature/dedupe ordering, tests run, files touched, blockers/risks, and update this task plus
`plan.md` to done.
@@ -0,0 +1,63 @@
---
id: "16-workspace-app-lifecycle-api"
title: "Workspace App lifecycle API"
status: done
wave: 4
depends_on: ["14-runtime-registration-resolution", "15-registration-webhook-routing"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 16: Workspace App Lifecycle API
## Acceptance
1. Catalog list/import/create/rename/delete and workspace install/personal flows implement the spec's
registration-aware routes, stable errors, authorization, and secret-free responses.
2. App install commits registration plus installation atomically, preserves old auth on failure,
revokes old leases, and removes incompatible personal secrets on success.
3. Status, mock controller, E2E reset, callback redirects, guarded deletion, stale flows, and
handler-to-real-store paths have focused tests.
## Verification
```bash
rtk go test ./internal/github -run 'Test.*(Registration|Installation|Personal|Controller|Status)'
rtk go test ./internal/backendapp -run 'Test.*(GitHub|Reset)'
```
Run from `apps/backend`.
## Files Likely Touched
- `apps/backend/internal/github/deployment_app_registration_service.go` (rename/generalize)
- `apps/backend/internal/github/deployment_app_registration_service_test.go`
- `apps/backend/internal/github/controller_app_registration.go` (rename/generalize)
- `apps/backend/internal/github/controller_app_registration_test.go`
- `apps/backend/internal/github/controller.go`
- `apps/backend/internal/github/controller_auth.go`
- `apps/backend/internal/github/handlers.go`
- `apps/backend/internal/github/app_installation_service.go`
- `apps/backend/internal/github/app_installation_service_test.go`
- `apps/backend/internal/github/personal_auth_service.go`
- `apps/backend/internal/github/personal_auth_service_test.go`
- `apps/backend/internal/github/service_connections.go`
- `apps/backend/internal/github/workspace_settings_service.go`
- `apps/backend/internal/github/mock_controller.go`
- `apps/backend/internal/github/mock_controller_test.go`
- `apps/backend/internal/backendapp/e2e_reset.go`
- `apps/backend/internal/backendapp/e2e_reset_test.go`
## Dependencies
Tasks 14 and 15.
## Inputs
- Spec: complete **API Surface**, state machines, permissions, and failure modes.
- Runtime registry from Task 14 and webhook service from Task 15.
## Output Contract
Report endpoint/state transitions, tests run, files touched, blockers/risks, and update this task plus
`plan.md` to done.
@@ -0,0 +1,56 @@
---
id: "17-frontend-registration-client"
title: "Frontend registration client"
status: done
wave: 5
depends_on: ["16-workspace-app-lifecycle-api"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 17: Frontend Registration Client
## Acceptance
1. Frontend types/API/hooks expose workspace-keyed catalog, create/import/rename/delete/install,
status, and callback contracts with no singleton deployment types or fetches.
2. Workspace changes clear prior catalog/actor/health/form state before refetch.
3. The System GitHub App route/sidebar/page and deployment-only hook are removed without breaking
settings navigation.
## Verification
```bash
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test -- lib/api/domains/github-api.test.ts hooks/domains/github/use-github-status.test.tsx components/settings/settings-layout-client.test.tsx
```
## Files Likely Touched
- `apps/web/lib/types/github.ts`
- `apps/web/lib/api/domains/github-auth-api.ts`
- `apps/web/lib/api/domains/github-api.test.ts`
- `apps/web/hooks/domains/github/use-deployment-app-registration.ts` (remove/replace)
- `apps/web/hooks/domains/github/use-deployment-app-registration.test.tsx` (remove/replace)
- `apps/web/hooks/domains/github/use-github-status.ts`
- `apps/web/hooks/domains/github/use-github-status.test.tsx`
- `apps/web/lib/state/slices/github/types.ts`
- `apps/web/lib/state/slices/github/github-slice.ts`
- `apps/web/src/settings-routes.tsx`
- `apps/web/app/settings/system/github-app/page.tsx` (remove)
- `apps/web/components/app-sidebar/sections/settings/system-group.tsx`
## Dependencies
Task 16.
## Inputs
- Spec: registration catalog/workspace/personal API and UX state isolation.
- Task 16 response/error contracts.
- Follow `apps/web/AGENTS.md` and mobile-parity shared-logic rules.
## Output Contract
Report client/state contract, tests run, files touched, blockers/risks, and update this task plus
`plan.md` to done.
@@ -0,0 +1,60 @@
---
id: "18-workspace-authentication-ux"
title: "Workspace authentication UX"
status: done
wave: 6
depends_on: ["17-frontend-registration-client"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 18: Workspace Authentication UX
## Acceptance
1. Workspace settings provide PAT, matched-height named CLI, known App selection, guided existing-App
import, and guided manifest creation without segmented tabs or a System Settings detour.
2. Method guidance, private/public meaning, registration sharing, actor attribution, permission
dialog, and conditional personal identity match the spec and expose no secrets after submission.
3. Component tests cover all source/states and the desktop/mobile layouts meet the 44px, one-scroll,
wrapping, no-overlap contract.
## Verification
```bash
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test -- components/github/github-connection-dialog.test.tsx components/settings/system/github-app-settings.test.tsx
cd apps && rtk pnpm --filter @kandev/web lint
```
Rename/move the singleton settings tests to workspace component names as part of the task and run
their resulting paths if the old paths no longer exist.
## Files Likely Touched
- `apps/web/components/github/github-settings.tsx`
- `apps/web/components/github/github-status.tsx`
- `apps/web/components/github/github-connection-dialog.tsx`
- `apps/web/components/github/github-connection-dialog.test.tsx`
- `apps/web/components/github/github-permissions-dialog.tsx`
- `apps/web/components/settings/system/github-app-settings.tsx` (move/refactor)
- `apps/web/components/settings/system/github-app-setup-form.tsx` (move/refactor)
- `apps/web/components/settings/system/github-app-permissions-dialog.tsx` (remove/reuse shared dialog)
- `apps/web/components/settings/system/github-app-settings-model.ts` (move/refactor)
- corresponding component/model tests
- `apps/web/app/settings/integrations/github/page.tsx`
## Dependencies
Task 17.
## Inputs
- Spec: **Choosing A Method**, **UX And Mobile Contract**, and scenarios.
- Existing workspace connection dialog and settings shell patterns.
- Invoke mobile-parity and use existing icon components.
## Output Contract
Report user flows and responsive behavior, tests run, files touched, screenshots inspected,
blockers/risks, and update this task plus `plan.md` to done.
@@ -0,0 +1,51 @@
---
id: "19-registration-e2e"
title: "Registration E2E coverage"
status: done
wave: 7
depends_on: ["18-workspace-authentication-ux"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 19: Registration E2E Coverage
## Acceptance
1. Playwright proves different Apps in two workspaces, intentional known-App reuse,
create/import/install cancellation/failure, and personal cleanup on switch.
2. Old System Settings registration specs are removed or rewritten as workspace settings flows.
3. Desktop and mobile screenshots are inspected; horizontal overflow is zero and all auth actions
remain usable with 44px targets and no overlap.
## Verification
```bash
cd apps/web && rtk pnpm e2e:run tests/integrations/github-authentication.spec.ts -- --project=chromium
cd apps/web && rtk pnpm e2e:run --no-build tests/integrations/mobile-github-auth-settings.spec.ts -- --project=mobile-chrome
```
## Files Likely Touched
- `apps/web/e2e/helpers/api-client.ts`
- `apps/web/e2e/fixtures/backend.ts`
- `apps/web/e2e/tests/integrations/github-authentication.spec.ts`
- `apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts`
- `apps/web/e2e/tests/settings/github-app-registration.spec.ts` (remove/merge)
- `apps/web/e2e/tests/settings/mobile-github-app-registration.spec.ts` (remove/merge)
- `apps/web/e2e/helpers/layout-assertions.ts`
## Dependencies
Task 18.
## Inputs
- Spec scenarios and **Success Criteria**.
- Task 16 mock/reset API and Task 18 stable UI locators.
- Use the E2E and mobile-parity skills.
## Output Contract
Report scenarios, commands/results, screenshots/overflow checks, files touched, external staging
gaps, blockers/risks, and update this task plus `plan.md` to done.
@@ -0,0 +1,51 @@
---
id: "20-registration-documentation"
title: "Registration documentation"
status: done
wave: 7
depends_on: ["18-workspace-authentication-ux"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 20: Registration Documentation
## Acceptance
1. Public docs explain PAT/CLI/App choice, known/import/create paths, strict versus shared App
isolation, private/public meaning, exact callbacks/webhooks, and permissions; the unpublished App
environment variables and instructions are absent.
2. Architecture and scoped agent guidance no longer claim a singleton deployment App or System
Settings ownership.
3. Generated documentation coverage metadata is updated using the repository's supported command.
## Verification
```bash
test -z "$(rg -l 'single deployment GitHub App|one deployment App|System Settings > GitHub App|KANDEV_GITHUB_APP' docs/public docs/ARCHITECTURE.md apps/backend/AGENTS.md || true)"
git diff --check
```
## Files Likely Touched
- `docs/public/integrations.md`
- `docs/public/configuration.md`
- `docs/public/feature-status.md`
- `docs/public/coverage.json`
- `docs/ARCHITECTURE.md`
- `apps/backend/AGENTS.md`
## Dependencies
Task 18.
## Inputs
- Spec and new ADR.
- Final endpoint names and UX terminology from Tasks 16 and 18.
- Invoke docs-maintainer; use primary GitHub documentation links already present in the repo.
## Output Contract
Report documentation/metadata changes, verification run, files touched, blockers/risks, and update
this task plus `plan.md` to done.
@@ -0,0 +1,66 @@
---
id: "21-security-qa"
title: "Security and QA verification"
status: done
wave: 8
depends_on: ["19-registration-e2e", "20-registration-documentation"]
plan: "plan.md"
spec: "../../specs/integrations/github-authentication.md"
---
# Task 21: Security And QA Verification
## Acceptance
1. Independent security review finds no cross-workspace/registration resolution, pre-HMAC mutation,
callback state confusion, secret exposure, unsafe deletion, or public-origin bypass.
2. Integrated QA exercises every spec scenario and records any real-GitHub staging-only checks.
3. Formatting, backend tests/lint, frontend typecheck/tests/lint, targeted desktop/mobile E2E, and
diff checks pass in the required order.
## Verification
```bash
rtk make -C apps/backend fmt
rtk make -C apps/backend test
rtk make -C apps/backend lint
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test
cd apps && rtk pnpm --filter @kandev/web lint
cd apps/web && rtk pnpm e2e:run tests/integrations/github-authentication.spec.ts -- --project=chromium
cd apps/web && rtk pnpm e2e:run --no-build tests/integrations/mobile-github-auth-settings.spec.ts -- --project=mobile-chrome
test -z "$(rg -l 'KANDEV_GITHUB_APP' apps docs/public || true)"
git diff --check
```
## Results
- Independent review found and fixed personal-token rollback generation, App credential deletion,
runtime publication race, stale registration selection, and import secret-reset defects.
- Backend GitHub tests pass with and without the race detector: 923 tests.
- Full web tests pass: 5,724 passed and 4 skipped. CLI tests pass: 280 tests.
- Desktop and mobile GitHub authentication and App registration Playwright suites pass.
- Formatting, monorepo typecheck, script tests, full lint, conflict checks, and diff checks pass.
- Real GitHub manifest conversion, installation, webhook delivery, and OAuth callbacks remain
staging checks because they require a public HTTPS Kandev origin and GitHub-owned credentials.
## Files Likely Touched
- `docs/plans/github-authentication/task-21-security-qa.md`
- `docs/plans/github-authentication/plan.md`
- Focused production/test files only when review finds an actionable defect
## Dependencies
Tasks 19 and 20.
## Inputs
- Entire approved spec and ADR.
- All Task 11-20 output contracts.
- Use security-auditor, QA, simplify, code-review, and verify skills/subagents as applicable.
## Output Contract
Report findings ordered by severity, fixes made, all commands/results, external staging gaps, files
touched, residual risks, and update this task plus `plan.md` to done only when acceptance passes.