docs: Index, doc API Gitea et script fermeture issue

- docs/00_INDEX.md : entrée pour 26_GITEA-API - docs/26_GITEA-API.md : procédure API Gitea (auth, issues, PR, branches, dépannage) - scripts/gitea-close-issue.sh : fermer une issue via l'API (GITEA_TOKEN / .gitea-token) Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-08 16:39:47 +01:00 · 2026-02-08 16:39:47 +01:00 · 6bf0932da8
commit 6bf0932da8
parent 2f1740b35f
3 changed files with 213 additions and 0 deletions
--- a/docs/00_INDEX.md
+++ b/docs/00_INDEX.md
@ -27,6 +27,7 @@ Ce fichier sert d'index pour naviguer dans toute la documentation du projet.
 - [**23 - Liste des Tickets**](./23_LISTE-TICKETS.md) - 61 tickets Phase 1 détaillés
 - [**24 - Décisions Projet**](./24_DECISIONS-PROJET.md) - Décisions architecturales et fonctionnelles
 - [**25 - Backlog Phase 2**](./25_PHASE-2-BACKLOG.md) - Fonctionnalités techniques reportées
+- [**26 - API Gitea**](./26_GITEA-API.md) - Procédure d'utilisation de l'API Gitea (issues, PR, branches, labels)

 ### Administration (À créer)
 - [**30 - Guide d'administration**](./30_ADMIN.md) - Gestion des utilisateurs, accès PgAdmin, logs
--- a/docs/26_GITEA-API.md
+++ b/docs/26_GITEA-API.md
@ -0,0 +1,176 @@
+# Procédure – Utilisation de l'API Gitea
+
+## 1. Contexte
+
+- **Instance** : https://git.ptits-pas.fr  
+- **API de base** : `https://git.ptits-pas.fr/api/v1`  
+- **Projet P'titsPas** : dépôt `jmartin/petitspas` (owner = `jmartin`, repo = `petitspas`)
+
+## 2. Authentification
+
+### 2.1 Token
+
+Le token est défini dans l'environnement (ex. `~/.bashrc`) :
+
+```bash
+export GITEA_TOKEN="<votre_token>"
+```
+
+Pour l'utiliser dans les commandes :
+
+```bash
+source ~/.bashrc   # ou : . ~/.bashrc
+# Puis utiliser $GITEA_TOKEN dans les curl
+```
+
+### 2.2 En-tête HTTP
+
+Toutes les requêtes API doivent envoyer le token :
+
+```bash
+-H "Authorization: token $GITEA_TOKEN"
+```
+
+Exemple :
+
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas"
+```
+
+## 3. Endpoints utiles
+
+### 3.1 Dépôt (repository)
+
+| Action        | Méthode | URL |
+|---------------|---------|-----|
+| Infos dépôt   | GET     | `/repos/{owner}/{repo}` |
+| Liste dépôts | GET     | `/repos/search?q=petitspas` |
+
+Exemple – infos du dépôt :
+
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas" | jq .
+```
+
+### 3.2 Issues (tickets)
+
+| Action           | Méthode | URL |
+|------------------|---------|-----|
+| Liste des issues | GET     | `/repos/{owner}/{repo}/issues` |
+| Détail d'une issue | GET   | `/repos/{owner}/{repo}/issues/{index}` |
+| Créer une issue | POST    | `/repos/{owner}/{repo}/issues` |
+| Modifier une issue | PATCH | `/repos/{owner}/{repo}/issues/{index}` |
+| Fermer une issue | PATCH   | (même URL, `state: "closed"`) |
+
+**Paramètres GET utiles pour la liste :**
+
+- `state` : `open` ou `closed`
+- `labels` : filtre par label (ex. `frontend`)
+- `page`, `limit` : pagination
+
+Exemples :
+
+```bash
+# Toutes les issues ouvertes
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues?state=open" | jq .
+
+# Issues ouvertes avec label "frontend"
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues?state=open" | \
+  jq '.[] | select(.labels[].name == "frontend") | {number, title, state}'
+
+# Détail de l'issue #47
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues/47" | jq .
+
+# Fermer l'issue #31
+curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"state":"closed"}' \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues/31"
+
+# Créer une issue
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Titre du ticket","body":"Description","labels":[1]}' \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues"
+```
+
+### 3.3 Pull requests
+
+| Action        | Méthode | URL |
+|---------------|---------|-----|
+| Liste des PR  | GET     | `/repos/{owner}/{repo}/pulls` |
+| Détail d'une PR | GET   | `/repos/{owner}/{repo}/pulls/{index}` |
+| Créer une PR  | POST    | `/repos/{owner}/{repo}/pulls` |
+| Fusionner une PR | POST  | `/repos/{owner}/{repo}/pulls/{index}/merge` |
+
+Exemples :
+
+```bash
+# Liste des PR ouvertes
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/pulls?state=open" | jq .
+
+# Créer une PR (head = branche source, base = branche cible)
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"head":"develop","base":"master","title":"Titre de la PR"}' \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/pulls"
+```
+
+### 3.4 Branches
+
+| Action        | Méthode | URL |
+|---------------|---------|-----|
+| Liste des branches | GET | `/repos/{owner}/{repo}/branches` |
+
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/branches" | jq '.[].name'
+```
+
+### 3.5 Webhooks
+
+| Action        | Méthode | URL |
+|---------------|---------|-----|
+| Liste webhooks | GET  | `/repos/{owner}/{repo}/hooks` |
+| Créer webhook | POST  | `/repos/{owner}/{repo}/hooks` |
+
+### 3.6 Labels
+
+| Action        | Méthode | URL |
+|---------------|---------|-----|
+| Liste des labels | GET | `/repos/{owner}/{repo}/labels` |
+
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/labels" | jq '.[] | {id, name}'
+```
+
+## 4. Résumé des URLs pour P'titsPas
+
+Remplacer `{owner}` par `jmartin` et `{repo}` par `petitspas` :
+
+| Ressource        | URL |
+|------------------|-----|
+| Dépôt            | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas` |
+| Issues           | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues` |
+| Issue #n         | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues/{n}` |
+| Pull requests    | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/pulls` |
+| Branches         | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/branches` |
+| Labels           | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/labels` |
+
+## 5. Documentation officielle
+
+- Swagger / OpenAPI : https://docs.gitea.com/api  
+- Référence selon la version de Gitea installée (ex. 1.21, 1.25).
+
+## 6. Dépannage
+
+- **401 Unauthorized** : vérifier le token et l'en-tête `Authorization: token <TOKEN>`.
+- **404** : vérifier owner/repo et l'URL (sensible à la casse).
+- **422 / body invalide** : pour POST/PATCH, envoyer `Content-Type: application/json` et un JSON valide.
--- a/scripts/gitea-close-issue.sh
+++ b/scripts/gitea-close-issue.sh
@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Ferme une issue Gitea via l'API.
+# Usage: GITEA_TOKEN=votre_token ./scripts/gitea-close-issue.sh [numéro]
+# Exemple: GITEA_TOKEN=xxx ./scripts/gitea-close-issue.sh 83
+
+set -e
+ISSUE="${1:-83}"
+BASE_URL="${GITEA_URL:-https://git.ptits-pas.fr/api/v1}"
+REPO="jmartin/petitspas"
+
+if [ -z "$GITEA_TOKEN" ]; then
+  if [ -f .gitea-token ]; then
+    GITEA_TOKEN=$(cat .gitea-token)
+  fi
+fi
+
+if [ -z "$GITEA_TOKEN" ]; then
+  echo "Définir GITEA_TOKEN ou créer .gitea-token avec votre token Gitea."
+  exit 1
+fi
+
+echo "Fermeture de l'issue #$ISSUE..."
+RESP=$(curl -s -w "\n%{http_code}" -X PATCH \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"state":"closed"}' \
+  "$BASE_URL/repos/$REPO/issues/$ISSUE")
+HTTP_CODE=$(echo "$RESP" | tail -1)
+BODY=$(echo "$RESP" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ]; then
+  echo "Issue #$ISSUE fermée."
+else
+  echo "Erreur HTTP $HTTP_CODE: $BODY"
+  exit 1
+fi