From 14358fdddcda1987bbf8087e9e2527554b7339ff Mon Sep 17 00:00:00 2001 From: Matthieu Date: Fri, 13 Mar 2026 12:13:36 +0100 Subject: [PATCH] docs : add Gitea integration design spec Co-Authored-By: Claude Opus 4.6 --- .../2026-03-13-gitea-integration-design.md | 124 ++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-13-gitea-integration-design.md diff --git a/docs/superpowers/specs/2026-03-13-gitea-integration-design.md b/docs/superpowers/specs/2026-03-13-gitea-integration-design.md new file mode 100644 index 0000000..c3297bb --- /dev/null +++ b/docs/superpowers/specs/2026-03-13-gitea-integration-design.md @@ -0,0 +1,124 @@ +# 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 | `/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 `/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 `. + +#### 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)