# 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