gitea-dashboard/docs/technical/research.md

Recherche technique — gitea-dashboard

Date : 2026-03-10 | Gitea 1.25.1 | Source : swagger.v1.json + docs.gitea.com

Contexte

Le dashboard CLI doit afficher pour chaque repo Gitea : le nombre d'issues ouvertes, la derniere release, et l'etat des milestones. Cette recherche identifie les endpoints API necessaires, la strategie de pagination, le format d'authentification, et les cas limites.

---

1. Authentification

Format recommande

Authorization: token <GITEA_TOKEN>

Le header Authorization avec le prefixe token (suivi d'un espace) est la methode recommandee. Les anciennes methodes (query parameter ?token= ou ?access_token=) sont deprecated depuis Gitea 1.23 et seront supprimees.

Source : schema securityDefinitions du swagger + https://docs.gitea.com/development/api-usage

---

2. Endpoints API necessaires

2.1 Liste des repos de l'utilisateur

Endpoint : GET /api/v1/user/repos

Retourne les repos dont l'utilisateur authentifie est proprietaire.

Parametre	Type	Description
page	integer	Numero de page (defaut : 1)
limit	integer	Elements par page (defaut : 50, max : 50)

Reponse : Array de Repository

Champs cles :

Champ	Type	Description
id	int64	Identifiant unique
name	string	Nom du repo
full_name	string	owner/name
description	string	Description
fork	boolean	Est un fork
archived	boolean	Est archive
mirror	boolean	Est un miroir
open_issues_count	int64	Issues ouvertes (inclut les PRs)
open_pr_counter	int64	PRs ouvertes (champ separe)
release_counter	int64	Nombre total de releases
owner.login	string	Login du proprietaire
updated_at	datetime	Derniere mise a jour

Alternative : GET /api/v1/repos/search retourne tous les repos visibles (pas seulement ceux de l'utilisateur). Reponse enveloppee dans {"ok": true, "data": [...]}.

2.2 Derniere release par repo

Endpoint : GET /api/v1/repos/{owner}/{repo}/releases/latest

Retourne la release la plus recente (hors draft et pre-release). Un seul objet, pas de pagination.

Champs cles :

Champ	Type	Description
tag_name	string	Nom du tag git
name	string	Titre de la release
published_at	datetime	Date de publication
prerelease	boolean	Est une pre-release

Retourne HTTP 404 si le repo n'a aucune release.

2.3 Milestones par repo

Endpoint : GET /api/v1/repos/{owner}/{repo}/milestones

Parametre	Type	Description
state	string	open, closed, all
page	integer	Numero de page
limit	integer	Elements par page

Champs cles :

Champ	Type	Description
title	string	Nom du milestone
state	StateType	open ou closed
open_issues	int64	Issues ouvertes dans le milestone
closed_issues	int64	Issues fermees dans le milestone
due_on	datetime	Date d'echeance

Le modele contient deja open_issues et closed_issues — progression calculable sans appel supplementaire.

---

3. Pagination

Parametre	Defaut	Maximum
page	1	-
limit	50	50

Headers de reponse

Header	Description
X-Total-Count	Nombre total d'elements
Link	URLs de navigation (rel="next", rel="last")

Strategie recommandee

1. Premiere requete avec ?limit=50&page=1
2. Lire X-Total-Count dans les headers
3. Si total > limit : calculer le nombre de pages, lancer les requetes suivantes
4. Alternative simple : boucler tant que len(results) == limit

Source : https://docs.gitea.com/development/api-usage (section Pagination)

---

4. Strategie d'appels

Pour N repos :

Donnee	Appels	Endpoint
Liste des repos	ceil(N/50)	GET /user/repos
Derniere release	N	GET /repos/{o}/{r}/releases/latest
Milestones	N	GET /repos/{o}/{r}/milestones
Total	ceil(N/50) + 2N

Issues ouvertes : derivees de open_issues_count - open_pr_counter du modele Repository (zero appel supplementaire).

Parallelisation : concurrent.futures.ThreadPoolExecutor avec 5-10 workers. La lib requests est thread-safe.

---

5. Cas limites

Cas	Comportement API	Gestion
Repo sans release	/releases/latest retourne 404	Capturer, afficher "—"
Repo sans milestone	/milestones retourne []	Tableau vide, rien a afficher
Repo sans issues	open_issues_count = 0	Comportement standard
Repo fork	fork = true	Afficher avec indicateur visuel
Repo archive	archived = true	Afficher avec indicateur visuel
open_issues_count inclut PRs	Herite de GitHub	Calculer open_issues_count - open_pr_counter

---

6. Decisions recommandees

#	Decision	Recommandation	Justification
1	Endpoint repos	GET /user/repos	Plus simple, reponse directe, suffisant pour v1
2	Comptage issues	open_issues_count - open_pr_counter	Zero appel supplementaire
3	Forks/archives	Tout afficher avec indicateurs	Exhaustivite, pas de filtre en v1
4	Parallelisation	ThreadPoolExecutor (5 workers)	Acceptable pour < 200 repos