Julien Martin
6bf0932da8
- 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>
177 lines
5.5 KiB
Markdown
177 lines
5.5 KiB
Markdown
# 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.
|