petitspas/docs/PROCEDURE-API-GITEA.md

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) :

export GITEA_TOKEN="<votre_token>"

Pour l’utiliser dans les commandes :

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 :

-H "Authorization: token $GITEA_TOKEN"

Exemple :

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 :

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 :

# 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 :

# 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

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

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.