Workspace GitHub Authentication Requirements

Overview

GitHub credentials must not silently cross workspace boundaries. A local workspace may only need a human PAT or a named gh CLI account, while unattended company automation benefits from a GitHub App's short-lived, repository-scoped installation tokens. Users also need to keep work and personal automation under different GitHub Apps without operating separate Kandev deployments.

Requirements

REQ-INTEGRATIONS-GITHUB-AUTHENTICATION-001: Workspace GitHub Authentication

Intent: GitHub credentials must not silently cross workspace boundaries. A local workspace may only need a human PAT or a named gh CLI account, while unattended company automation benefits from a GitHub App's short-lived, repository-scoped installation tokens. Users also need to keep work and personal automation under different GitHub Apps without operating separate Kandev deployments.

Acceptance criteria

AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.1: Every workspace chooses exactly one automation source: PAT, a named gh CLI account, a verified GitHub App installation, or the migration-only legacy_shared source.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.2: GitHub App registration is configured from the workspace GitHub settings flow. There is no singleton GitHub App settings page and no automatically active deployment App.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.3: A workspace may select a GitHub App registration already known to the Kandev deployment, import an existing GitHub App that the user owns, or create a new GitHub App through GitHub's App Manifest flow. Import and creation guide the user through ownership, callback, webhook, permission, visibility, and installation requirements.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.4: The deployment stores a catalog of GitHub App registrations because a user may intentionally reuse one App across workspaces. Each workspace still selects and installs an App independently. Selecting an existing registration never binds another workspace automatically.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.5: Users who require independent root credentials, bot identity, revocation, or ownership create a separate registration for each trust boundary. Work and personal workspaces can therefore use different Apps.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.6: Reusing one registration shares its App private key, client secret, webhook secret, permission policy, and bot identity. Installation tokens, workspace repository scope, connection generation, broker leases, health, and personal OAuth tokens remain workspace isolated.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.7: A newly created App defaults to private, meaning GitHub permits installation only on the account that owns it. The user may explicitly choose public when the same App must be installable on other GitHub accounts or organizations. Public does not list the App in Marketplace, reveal secrets, or grant repository access without installation approval.
AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.8: PAT and named CLI automation act as the verified human account. A separate My GitHub connection is only offered when workspace automation uses a GitHub App, because App installations are not people and cannot provide authenticated-viewer semantics.

System design

The migrated technical source is split into part 1, part 2, part 3.

3.6 KiB Raw Blame History