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,32 @@
+# 01 GitHub Provider Foundation and Auth Strategy
+
+## Goal
+
+Introduce GitHub as the second concrete Git provider behind the existing provider abstraction while keeping the first GitHub auth mode aligned with KanbanGit's current per-user connection model.
+
+## Requirements
+
+- Add GitHub as a supported provider key and provider client.
+- Target GitHub Cloud on `https://api.github.com`.
+- Keep project, ticket, and repository-connection core logic free from GitHub-specific assumptions wherever possible.
+- The provider client must support the API surface needed for:
+  - authenticated user metadata
+  - repository listing
+  - repository lookup
+  - branch listing
+  - pull request listing
+- The release must choose one initial GitHub auth strategy and document it clearly.
+
+## Acceptance Criteria
+
+- The codebase has a clear GitHub provider implementation behind the existing provider boundary.
+- GitHub-specific HTTP details do not leak into ticket or project core logic.
+- The selected GitHub auth strategy is compatible with the current `UserGitConnection` concept.
+- The provider foundation is sufficient for later repository linking, branch discovery, and pull request visibility tickets in release `0.3`.
+
+## Out of Scope
+
+- GitHub App JWT handling
+- GitHub installation tokens
+- GitHub Enterprise Server support
+- Webhook processing
@@ -0,0 +1,26 @@
+# 02 User GitHub Connections and Repository Discovery
+
+## Goal
+
+Allow a user to connect GitHub in settings and expose the repositories that user can read through the chosen token.
+
+## Requirements
+
+- Add GitHub as an option in user Git connection settings.
+- GitHub Cloud connections must use a fixed API base URL instead of asking the user for an instance URL.
+- Connection verification must confirm repository read access.
+- Authenticated user metadata from `GET /user` should be stored when available for display purposes.
+- Accessible repositories must be loaded from the authenticated user's GitHub repository list.
+
+## Acceptance Criteria
+
+- A user can add, update, list, and remove a GitHub connection from settings.
+- A token that can read repositories is accepted.
+- A token that cannot read repositories is rejected with a clear validation error.
+- Repositories available through the GitHub connection appear as selectable repository sources in project settings.
+
+## Out of Scope
+
+- OAuth browser login flows
+- GitHub App installation authorization
+- Background repository synchronization beyond on-demand fetches
@@ -0,0 +1,26 @@
+# 03 Project GitHub Repository Connections
+
+## Goal
+
+Allow projects to link one or more GitHub repositories through the existing project repository settings workflow.
+
+## Requirements
+
+- Reuse the existing repository connection model and project settings flow for GitHub.
+- A GitHub repository connection must store enough data to identify the provider and repository.
+- Repository linking must remain protected by the appropriate project-level permissions.
+- The repository list must make the provider source clear when a project uses more than one Git provider.
+- The design should allow a project to hold both Gitea and GitHub repository connections when supported by the underlying provider abstraction.
+
+## Acceptance Criteria
+
+- An authorized user can add, edit, list, and remove GitHub repository connections for a project.
+- A project can hold more than one GitHub repository connection.
+- A project can display mixed-provider repository connections without ambiguity.
+- The stored data remains compatible with the provider-neutral repository connection layer introduced in earlier releases.
+
+## Out of Scope
+
+- Cross-project shared repository connections
+- Automatic background metadata refresh
+- Organization-level permission management inside KanbanGit
@@ -0,0 +1,26 @@
+# 04 GitHub Ticket Branch Discovery by Ticket Key
+
+## Goal
+
+Show GitHub branches related to a ticket by matching configured repository branches against the ticket key prefix.
+
+## Requirements
+
+- Add GitHub branch matches to the ticket detail view through the same provider-neutral branch section used for other providers.
+- For each configured GitHub repository connection, identify branches whose names start with the ticket key.
+- A matching branch must be shown on the ticket when its name starts with the exact ticket key, for example `AUTH-42-...`.
+- Present matches in a way that makes the repository source and provider clear.
+- The first implementation may use direct fetches or a simple cache, but it must not require a large background sync system.
+
+## Acceptance Criteria
+
+- A ticket with key `AUTH-42` shows GitHub branches such as `AUTH-42-login-form`.
+- Branches that do not start with the ticket key are not shown.
+- If multiple configured repositories contain matching branches, the ticket shows matches from each relevant repository.
+- The branch section remains compatible with mixed-provider repository connections.
+
+## Out of Scope
+
+- Commit listing
+- Branch creation from inside KanbanGit
+- Cross-ticket branch disambiguation beyond exact ticket-key prefix matching
@@ -0,0 +1,29 @@
+# 05 GitHub Ticket Pull Request Visibility
+
+## Goal
+
+Show GitHub pull requests related to a ticket alongside the matching branches in the ticket detail view.
+
+## Requirements
+
+- Add a GitHub pull requests section to the ticket detail view using the existing provider-neutral pull request presentation model.
+- Pull requests must be associated to a ticket using the same ticket-key-based branch naming convention as branch discovery.
+- Show enough pull request information to identify and open the matching item, at minimum:
+  - title
+  - provider identifier or number
+  - repository source
+  - status if available
+- The implementation may derive pull request matches from source branch names.
+
+## Acceptance Criteria
+
+- A ticket shows GitHub pull requests whose source branch starts with the ticket key.
+- Pull requests unrelated to the ticket key are not shown.
+- The ticket detail view clearly separates branch matches from pull request matches.
+- Pull request visibility remains compatible with mixed-provider repository connections.
+
+## Out of Scope
+
+- Pull request review actions inside KanbanGit
+- Merge controls
+- Status checks and CI reporting
@@ -0,0 +1,41 @@
+# Release 0.3 - GitHub Integration
+
+## Purpose
+
+Add GitHub as the second supported Git provider with parity to the current Gitea-based repository, branch, and pull request visibility flows.
+
+## API Basis
+
+This release is planned from `docs/gitApiDocs/api.github.com.json`.
+
+Primary endpoints for release `0.3`:
+
+- `GET /user`
+- `GET /user/repos`
+- `GET /repos/{owner}/{repo}`
+- `GET /repos/{owner}/{repo}/branches`
+- `GET /repos/{owner}/{repo}/pulls`
+
+## Release Decisions
+
+- The first release targets GitHub Cloud on `https://api.github.com`.
+- The first auth mode is a per-user token connection.
+- Repository readability is the connection gate.
+- Authenticated user profile data is an optional enrichment step for display metadata.
+- GitHub App and installation flows are intentionally deferred.
+
+## Tickets
+
+- [01 GitHub Provider Foundation and Auth Strategy](01-github-provider-foundation-and-auth-strategy.md)
+- [02 User GitHub Connections and Repository Discovery](02-user-github-connections-and-repository-discovery.md)
+- [03 Project GitHub Repository Connections](03-project-github-repository-connections.md)
+- [04 GitHub Ticket Branch Discovery by Ticket Key](04-github-ticket-branch-discovery-by-ticket-key.md)
+- [05 GitHub Ticket Pull Request Visibility](05-github-ticket-pull-request-visibility.md)
+
+## Deferred from This Release
+
+- GitHub App authentication and installations
+- GitHub Enterprise Server
+- Webhooks
+- Merge, review, and status-check actions
+- Branch creation from ticket detail