108 lines
3.8 KiB
Markdown
108 lines
3.8 KiB
Markdown
# 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
|