Merge remote-tracking branch 'origin/main' into codex/gitea-repository-read-check

2026-03-26 13:01:24 +01:00
parent 662bb6e103 8b79dd9ad9
commit bb31bf8f0c
13 changed files with 331113 additions and 2 deletions
@@ -12,7 +12,7 @@ class UpdateUserAdminStatusRequest extends FormRequest
     */
    public function authorize(): bool
    {
-        return $this->user()?->is_admin === true;
+        return $this->user()?->can('access-admin') ?? false;
    }

    /**
@@ -15,6 +15,7 @@ The product centers around projects. Each project owns its own board configurati
 - [Product Spec](product-spec.md) describes expected product behavior, user-visible rules, and scope boundaries.
 - [Domain Model](domain-model.md) defines the canonical domain concepts, relationships, and invariants that future database tables, Eloquent models, policies, and frontend types should follow.
 - [Architecture Roadmap](architecture-roadmap.md) captures the planned architecture direction, permission strategy, integration boundaries, and staged implementation intent.
+- [GitHub Integration Plan](github-integration-plan.md) captures the first planned GitHub-specific integration strategy for release `0.3`.
 - [Release Task Breakdown](releases/README.md) splits the planned work into small ordered implementation tickets grouped by release.

 ## Glossary
@@ -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
@@ -0,0 +1,6 @@
+## Missing features
+
+### Ticket
+
+- 02:
+  - Delete Projekt as Admin
@@ -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
@@ -6,9 +6,11 @@ This directory contains small, ordered implementation tickets grouped by release

 - [Release 0.1 - Kanban, Ticketing, Users, and Permissions Foundation](0.1-kanban-foundation/01-admin-and-user-management-foundation.md)
 - [Release 0.2 - Gitea Integration](0.2-gitea-integration/01-git-provider-abstraction-and-gitea-foundation.md)
+- [Release 0.3 - GitHub Integration](0.3-github-integration/README.md)

 ## Scope notes

 - Release `0.1` covers the core Kanban, ticket, user, team, and permission foundation.
 - Release `0.2` covers the first Git provider integration with Gitea.
+- Release `0.3` covers GitHub Cloud as the second Git provider using the existing provider abstraction and user connection model.
 - Roadmap and other currently out-of-scope items are intentionally not broken into tickets here.
@@ -4,5 +4,4 @@ export type ProjectModel = {
    key: string;
    created_at: string;
    updated_at: string;
-    [key: string]: unknown;
 };