Lesstime/docs/superpowers/specs/2026-03-13-gitea-integration-design.md

Intégration Gitea — Design Spec

Objectif

Lier les tickets Lesstime à Gitea pour :

• Créer une branche depuis un ticket (avec choix du type : feature, fix, refactor, etc.)
• Voir les branches, commits, PRs et statut CI liés à un ticket
• Le tout à la demande (pas de webhook, pas de cron, pas de stockage git en base)

Décisions

Question	Décision
Interaction	Depuis Lesstime uniquement (bouton + affichage)
Repos	Un projet = un repo Gitea
Nommage branches	<type>/PROJ-42-titre-en-slug (type choisi par l'utilisateur)
Détection commits	Par la branche (tous les commits d'une branche liée au ticket)
Données affichées	Branches + commits + PRs + statut CI/CD
Config serveur	Globale (admin) : URL + token API
Config repo	Par projet : owner + repo name
Synchronisation	À la demande (appel API Gitea en temps réel)

Architecture

Backend

Configuration globale — table Setting

Nouvelle entité Setting (clé-valeur) pour stocker :

• gitea_url — URL de l'instance Gitea (ex: https://git.malio.fr)
• gitea_token — Token API Gitea (accès repos)

Alternative : utiliser config/reference.php avec des variables d'environnement. La table Setting est préférable car configurable depuis l'admin sans redéploiement.

Entité Project — nouveaux champs

gitea_owner: string|null  (ex: "malio")
gitea_repo: string|null   (ex: "lesstime")

Nullable car tous les projets ne sont pas forcément liés à un repo.

Service GiteaApiService

Service Symfony qui encapsule les appels HTTP vers l'API Gitea REST v1.

Méthodes :

• listRepositories(): array — liste les repos accessibles (pour sélection dans le projet)
• createBranch(project, task, type, baseBranch): string — crée une branche <type>/CODE-NUM-slug à partir d'une branche de base
• listBranches(project, taskCode): array — liste les branches matchant le pattern */CODE-NUM*
• listCommits(project, branch): array — liste les commits d'une branche
• listPullRequests(project, taskCode): array — liste les PRs dont la branche source matche le code ticket
• getPullRequestChecks(project, prNumber): array — statut CI/CD d'une PR

Le service utilise HttpClientInterface de Symfony. Le token est envoyé en header Authorization: token <gitea_token>.

Endpoints API Platform

Nouveaux endpoints (custom operations ou controllers si nécessaire) :

• GET /api/settings/gitea — récupérer la config Gitea (admin only)
• PUT /api/settings/gitea — sauvegarder la config Gitea (admin only)
• GET /api/gitea/repositories — lister les repos disponibles (pour config projet)
• POST /api/tasks/{id}/gitea/branches — créer une branche pour un ticket
• GET /api/tasks/{id}/gitea/info — récupérer branches + commits + PRs + CI pour un ticket

Frontend

Admin — Config Gitea

Nouveau tab ou section dans l'admin pour configurer :

• URL du serveur Gitea
• Token API
• Bouton "Tester la connexion"

ProjectDrawer — Config repo

Ajout de champs dans le drawer de projet :

• Sélecteur de repo Gitea (dropdown alimenté par GET /api/gitea/repositories)
• Affiche owner/repo une fois sélectionné

TaskModal — Section Git

Nouvelle section dans la TaskModal (visible si le projet a un repo configuré) :

Bouton "Créer une branche" :

• Sélecteur de type : feature, fix, refactor, hotfix, chore
• Sélecteur de branche de base (default: branche par défaut du repo)
• Preview du nom : feature/PROJ-42-titre-de-la-tache
• Bouton de confirmation

Affichage des infos Git :

• Liste des branches liées (avec statut : active / mergée / supprimée)
• Pour chaque branche : derniers commits (hash court, message, auteur, date)
• PRs associées (titre, statut : open/merged/closed, reviewers)
• Statut CI/CD par PR (checks : success/failure/pending)
• Liens directs vers Gitea pour chaque élément

Sécurité

• Le token Gitea est stocké chiffré en base (ou au minimum non exposé dans les réponses API)
• L'endpoint GET /api/settings/gitea retourne l'URL mais masque le token (ex: ****)
• Seuls les admins peuvent configurer le serveur Gitea
• Les utilisateurs authentifiés peuvent créer des branches et voir les infos git

API Gitea — Endpoints utilisés

Action	Méthode Gitea API
Lister repos	GET /api/v1/repos/search
Lister branches	GET /api/v1/repos/{owner}/{repo}/branches
Créer branche	POST /api/v1/repos/{owner}/{repo}/branches
Lister commits	GET /api/v1/repos/{owner}/{repo}/commits?sha={branch}
Lister PRs	GET /api/v1/repos/{owner}/{repo}/pulls?state=all
Statut CI	GET /api/v1/repos/{owner}/{repo}/commits/{sha}/statuses

Hors scope

• Webhooks Gitea → Lesstime
• Stockage des commits/PRs en base
• Création de PR depuis Lesstime
• Lien multi-repo par projet
• Synchronisation périodique (cron/polling)