From 6bf0932da821daa2133a92c69d6b15bffb22b262 Mon Sep 17 00:00:00 2001 From: Julien Martin Date: Sun, 8 Feb 2026 16:39:47 +0100 Subject: [PATCH] docs: Index, doc API Gitea et script fermeture issue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/00_INDEX.md | 1 + docs/26_GITEA-API.md | 176 +++++++++++++++++++++++++++++++++++ scripts/gitea-close-issue.sh | 36 +++++++ 3 files changed, 213 insertions(+) create mode 100644 docs/26_GITEA-API.md create mode 100644 scripts/gitea-close-issue.sh diff --git a/docs/00_INDEX.md b/docs/00_INDEX.md index 062e0f7..df689ca 100644 --- 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 diff --git a/docs/26_GITEA-API.md b/docs/26_GITEA-API.md new file mode 100644 index 0000000..1cbea2e --- /dev/null +++ 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="" +``` + +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 `. +- **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. diff --git a/scripts/gitea-close-issue.sh b/scripts/gitea-close-issue.sh new file mode 100644 index 0000000..3403745 --- /dev/null +++ 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