KanbanGit/docs/github-integration-plan.md

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