Add v0.3 GitHub integration release plan and tickets

2026-03-26 11:54:08 +01:00
parent 5e41dae648
commit 21d7dfe27b
10 changed files with 331106 additions and 0 deletions
@@ -0,0 +1,107 @@
+# GitHub Integration Plan
+
+## Purpose
+
+This document describes the intended first GitHub integration approach for KanbanGit release `0.3`.
+
+The goal is to add GitHub as the second supported Git provider without redesigning the provider-neutral repository, branch, and pull request flows already introduced for Gitea.
+
+## Source Material
+
+- Primary API source: `docs/gitApiDocs/api.github.com.json`
+- Primary target API: GitHub REST v3 on `https://api.github.com`
+
+## Release Direction
+
+Release `0.3` should deliver GitHub Cloud support through the existing per-user Git connection model.
+
+Key decisions:
+
+- The first GitHub auth mode is a user-managed token connection.
+- GitHub Cloud uses a fixed API base URL instead of a user-entered instance URL.
+- Connection validation should confirm repository read access.
+- Authenticated user metadata from `GET /user` is useful for display, but it should not be the only success criterion if repository access can already be verified.
+- The provider abstraction must remain the boundary between ticket or project logic and GitHub-specific HTTP details.
+
+## Required API Surface for v0.3
+
+The release should be planned around these endpoints from `api.github.com`:
+
+- `GET /user`
+- `GET /user/repos`
+- `GET /repos/{owner}/{repo}`
+- `GET /repos/{owner}/{repo}/branches`
+- `GET /repos/{owner}/{repo}/pulls`
+
+These endpoints are sufficient for the current KanbanGit feature set:
+
+- storing a user Git connection
+- discovering repositories the user can access
+- linking repositories to projects
+- matching branches to tickets by ticket key
+- matching pull requests to tickets by source branch name
+
+## Provider-Neutral Data Mapping
+
+The GitHub provider should map its responses into the existing provider-neutral contracts already used by Gitea integration.
+
+### Authenticated user
+
+- `id` -> `provider_user_id`
+- `login` -> `account_login`
+- `name` -> `account_name`
+
+### Repository
+
+- `id` -> `provider_repository_id`
+- `owner.login` -> `owner_name`
+- `name` -> `repository_name`
+- `full_name` -> `repository_full_name`
+- `html_url` -> `repository_url`
+- `default_branch` -> default branch metadata when available
+- `private` -> visibility label derivation
+
+### Branch
+
+- `name` -> branch name shown in ticket detail
+
+### Pull request
+
+- `number` -> provider identifier shown in ticket detail
+- `title` -> pull request title
+- `state` -> pull request status
+- `head.ref` -> source branch used for ticket-key matching
+- `html_url` -> outbound link target
+
+## Product and UX Implications
+
+- GitHub connections should appear beside Gitea connections in user settings.
+- The GitHub connection form should not require a base URL for GitHub Cloud.
+- Project repository settings should allow mixing Gitea and GitHub repositories in the same project when the provider abstraction already supports this.
+- Ticket branch and pull request sections should continue to be grouped by repository connection so provider context stays obvious.
+
+## Explicitly Deferred
+
+The provided GitHub API definition also contains app and installation endpoints, but those should not be part of release `0.3`.
+
+Deferred items:
+
+- GitHub App authentication with `GET /app`
+- installation discovery with `GET /app/installations`
+- installation token generation with `POST /app/installations/{installation_id}/access_tokens`
+- installation-scoped repository listing with `GET /installation/repositories`
+- GitHub Enterprise Server support
+- webhooks
+- review, merge, and status-check actions
+- GraphQL usage
+- branch creation from inside KanbanGit
+
+## Release Outcome
+
+If release `0.3` is completed as planned, KanbanGit should support GitHub repository awareness with the same core workflow currently targeted for Gitea:
+
+- connect a provider account
+- expose accessible repositories
+- link repositories to projects
+- surface ticket-related branches
+- surface ticket-related pull requests