# GitLab Bridge

Bridge API `FastAPI` entre `OpenWebUI` et `GitLab`.

Ce service joue le rôle d’intermédiaire entre un client OpenAPI/OpenWebUI et l’API GitLab v4. Il centralise les appels GitLab, utilise un **token technique côté serveur** et ajoute de la **journalisation HTTP + audit SQL**.

---

## 🎯 Objectif

Le bridge permet notamment de :

- vérifier l’état du service ;
- rechercher des groupes GitLab ;
- lister et créer des projets ;
- créer, lister, clôturer ou rouvrir des issues ;
- gérer des labels sur une ou plusieurs issues ;
- créer et suivre des milestones ;
- fournir des réponses simples et compatibles avec un usage depuis `OpenWebUI`.

---

## ⚙️ Prérequis

Avant démarrage, prévoir :

- **Python 3.11+**
- un accès réseau à votre instance **GitLab**
- un **token API GitLab** disposant des droits nécessaires
- une base **MariaDB/MySQL** accessible pour la journalisation d’audit

---

## 📦 Installation locale

Depuis le dossier du projet :

```bash
cd /var/www/html/gitlab-bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

> Si votre environnement ne fournit pas déjà `python-dotenv`, ajoutez au besoin :
>
> ```bash
> pip install python-dotenv
> ```

---

## 🔐 Configuration

Créer un fichier `.env` à la racine du projet :

```env
APP_NAME=gitlab-bridge
APP_ENV=dev
APP_DEBUG=false
APP_HOST=0.0.0.0
APP_PORT=8080

GITLAB_BASE_URL=https://gitlab.example.com
GITLAB_API_TOKEN=glpat_xxxxxxxxxxxxxxxxxxxx
GITLAB_TIMEOUT=15
GITLAB_VERIFY_SSL=true

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=gitlab_bridge
DB_USER=gitlab_bridge
DB_PASSWORD=change_me
DB_ECHO=false
```

### Variables importantes

| Variable | Obligatoire | Description |
|---|---:|---|
| `GITLAB_BASE_URL` | ✅ | URL de base de GitLab |
| `GITLAB_API_TOKEN` | ✅ | Token technique utilisé par le bridge |
| `GITLAB_TIMEOUT` | non | Timeout des appels GitLab, défaut `15` |
| `DB_HOST` / `DB_PORT` | ✅ | Hôte et port MariaDB/MySQL |
| `DB_NAME` | ✅ | Base utilisée par le bridge |
| `DB_USER` / `DB_PASSWORD` | ✅ | Identifiants SQL |
| `APP_HOST` / `APP_PORT` | non | Hôte et port d’écoute du service |

> Ne pas versionner le fichier `.env` avec des secrets réels.

---

## ▶️ Lancement

### Mode développement

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080
```

### En utilisant les variables du `.env`

```bash
uvicorn app.main:app --reload --host "$APP_HOST" --port "$APP_PORT"
```

Une fois démarré, les accès utiles sont :

- `GET /health`
- `GET /docs` : documentation Swagger UI
- `GET /redoc` : documentation ReDoc
- `GET /openapi.json` : schéma OpenAPI

Exemple local :

- `http://localhost:8080/health`
- `http://localhost:8080/docs`

---

## 🧱 Structure du projet

- `app/main.py` : point d’entrée FastAPI
- `app/api/v1/` : endpoints exposés
- `app/core/` : configuration et logging
- `app/db/` : session SQLAlchemy et modèles ORM
- `app/schemas/` : schémas Pydantic des requêtes/réponses

---

## 🔌 Endpoints disponibles

### Santé

| Méthode | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Vérifie que l’API répond correctement |

### Groupes GitLab

| Méthode | Endpoint | Description |
|---|---|---|
| `POST` | `/api/v1/groups/search` | Recherche des groupes GitLab à partir d’un libellé naturel |

### Projets GitLab

| Méthode | Endpoint | Description |
|---|---|---|
| `POST` | `/api/v1/projects/check-create` | Pré-vérifie une création de projet |
| `POST` | `/api/v1/projects/assistant-list` | Liste les projets d’un groupe avec résolution assistée |
| `POST` | `/api/v1/projects/assistant-create` | Crée un projet avec logique de clarification |
| `POST` | `/api/v1/projects/create` | Crée directement un projet GitLab |
| `POST` | `/api/v1/projects/assistant-tasks` | Retourne les tâches/issues d’un projet |
| `POST` | `/api/v1/projects/assistant-progress` | Calcule la progression d’un projet |

### Issues GitLab

| Méthode | Endpoint | Description |
|---|---|---|
| `POST` | `/api/v1/issues/assistant-list` | Liste des issues d’un projet |
| `POST` | `/api/v1/issues/assistant-create` | Création assistée d’issue |
| `POST` | `/api/v1/issues/create` | Création directe d’une issue |
| `POST` | `/api/v1/issues/assistant-close` | Clôture assistée d’une issue |
| `POST` | `/api/v1/issues/assistant-reopen` | Réouverture assistée d’une issue |
| `POST` | `/api/v1/issues/assistant-list-labels` | Liste les labels d’un projet |
| `POST` | `/api/v1/issues/assistant-add-label` | Ajoute un label à une issue |
| `POST` | `/api/v1/issues/assistant-add-label-bulk` | Ajoute un label à plusieurs issues |
| `POST` | `/api/v1/issues/assistant-add-label-all` | Ajoute un label à toutes les issues d’un projet |

### Milestones GitLab

| Méthode | Endpoint | Description |
|---|---|---|
| `POST` | `/api/v1/milestones/assistant-list` | Liste les milestones d’un projet |
| `POST` | `/api/v1/milestones/assistant-create` | Crée une milestone |
| `POST` | `/api/v1/milestones/assistant-assign-issue` | Affecte une issue à une milestone |
| `POST` | `/api/v1/milestones/assistant-list-issues` | Liste les issues d’une milestone |
| `POST` | `/api/v1/milestones/assistant-progress` | Calcule la progression d’une milestone |

---

## 🧪 Exemples d’appel

### 1) Vérification de santé

```bash
curl http://localhost:8080/health
```

Réponse attendue :

```json
{
  "status": "ok"
}
```

### 2) Recherche d’un groupe GitLab

```bash
curl -X POST "http://localhost:8080/api/v1/groups/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "developpements",
    "root_hint": "si",
    "limit": 10
  }'
```

### 3) Création directe d’une issue

```bash
curl -X POST "http://localhost:8080/api/v1/issues/create" \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "si/intelligence-artificielle/serveur-ia-interne",
    "title": "Test OpenWebUI",
    "description": "Issue de test créée via le bridge",
    "labels": ["test", "ia"]
  }'
```

### 4) Création directe d’un projet

```bash
curl -X POST "http://localhost:8080/api/v1/projects/create" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Serveur IA Interne",
    "path": "serveur-ia-interne",
    "namespace_path": "si/intelligence-artificielle",
    "description": "Projet créé via GitLab Bridge",
    "visibility": "private",
    "initialize_with_readme": true
  }'
```

---

## 🪵 Journalisation et audit

Le service ajoute plusieurs mécanismes de traçabilité :

- logs JSON sur la sortie standard ;
- ajout d’un en-tête `X-Request-ID` sur chaque réponse ;
- masquage des clés sensibles (`token`, `password`, `authorization`, etc.) ;
- création automatique de la table d’audit SQL `ai_gitlab_audit_logs` au démarrage.

---

## 🛡️ Sécurité et déploiement

Points d’attention :

- le bridge agit avec un **token GitLab serveur** ; il doit donc être protégé par réseau privé, reverse proxy, filtrage IP ou authentification amont ;
- le `CORS` est actuellement autorisé pour `https://ia.tarbouriech.tech` dans `app/main.py` ;
- toute modification de frontal autorisé nécessite une mise à jour du middleware `CORSMiddleware`.

---

## ❗ Dépannage rapide

| Problème | Cause probable | Vérification |
|---|---|---|
| erreur `500` au démarrage | variables `.env` manquantes | vérifier `GITLAB_*` et `DB_*` |
| erreur `403` GitLab | token insuffisant ou refusé | vérifier les droits du `GITLAB_API_TOKEN` |
| erreur `502` | GitLab injoignable | tester l’accès réseau à `GITLAB_BASE_URL` |
| échec au boot sur la base | MariaDB/MySQL indisponible | vérifier les paramètres `DB_*` |

---

## 📌 Notes

- Le bridge s’appuie sur l’API GitLab `v4`.
- Les schémas de requête/réponse sont définis dans `app/schemas/`.
- Pour une intégration `OpenWebUI`, utiliser de préférence le schéma exposé par `GET /openapi.json`.