ntfy-bridge/docs/WEBHOOK_GITEA.md

# Configurer les webhooks Gitea avec ntfy-bridge

Guide tape par tape pour connecter Gitea  ntfy-bridge et recevoir des notifications Ntfy pour chaque push, PR, issue ou release.

---

## Prrequis

- **ntfy-bridge** install et configur (voir [README.md](../README.md))
- Un serveur **Ntfy** accessible (ex: `https://ntfy.dracodev.net`)
- Un compte **Gitea** avec accs admin au repo (ex: `https://git.dracodev.net`)

---

## Architecture

```
 Gitea (git.dracodev.net)          ntfy-bridge (ton serveur)         Ntfy (ntfy.dracodev.net)
 ┌─────────────────────┐           ┌────────────────────────┐        ┌──────────────────────┐
 │ bruno/flowdeck      │           │ coute sur :9090         │        │ Topic: dev-notifs    │
 │                     │  POST     │                         │  POST  │                      │
 │  vnement (push)    │──────────→│ /webhooks/gitea-...     │───────→│  Ton tlphone        │
 │  JSON + HMAC sig   │           │                         │        │                      │
 │                     │           │ Parse, format, forward  │        │                      │
 └─────────────────────┘           └────────────────────────┘        └──────────────────────┘
```

**Le principe** : Gitea envoie un POST HTTP contenant un JSON avec tous les dtails de l'vnement. ntfy-bridge l'coute, le parse, le formate, et le forward vers Ntfy.

---

## tape 1 — Configurer ntfy-bridge

### 1a. Modifier `ntfy-bridge.yaml`

```yaml
server:
  url: https://ntfy.dracodev.net         # Ton serveur Ntfy
  listen: "0.0.0.0:9090"                 # couter sur le rseau (pas juste localhost)
  hmac_secret: "un-secret-que-tu-choisis" # Secret partag avec Gitea

sources:
  gitea:
    - name: "FlowDeck activity"          # Nom affich dans les logs/dashboard
      webhook_path: /webhooks/gitea-flowdeck  # Chemin d'coute
      repo: bruno/flowdeck               # Repo concern
      topic: dev-notifs                  # Topic Ntfy cible
      priority_map:                      # Priorits par type d'vent
        pull_request: 4                  # 4 = high
        issue: 3                         # 3 = default
        push: 2                          # 2 = low
      template: |                        # Format du message (optionnel)
        {user} {action} sur **[{repo}]**: "{title}"
```

**Points cls** :
- `listen: "0.0.0.0:9090"` — indispensable si Gitea est sur un autre serveur. `127.0.0.1` = localhost seulement.
- `hmac_secret` — le mme secret que tu mettras dans Gitea. Optionnel mais recommand.
- `webhook_path` — le chemin dans l'URL. Doit tre unique par source.
- `template` — si absent, un format par dfaut est gnr automatiquement avec emoji.

### 1b. Lancer ntfy-bridge

```bash
cd /c/dev/git/V/ntfy-bridge
./ntfy-bridge.exe --config ntfy-bridge.yaml
```

Sortie attendue :

```
──────────────────────────────────────────────────────────────────────
  ntfy-bridge v0.1.0 — Homelab Notification Hub
──────────────────────────────────────────────────────────────────────
  Ntfy server:   https://ntfy.dracodev.net
  Listening on:  http://0.0.0.0:9090
  Dashboard:     http://0.0.0.0:9090/

  Sources loaded:
    Gitea:       2 webhooks
    Uptime Kuma: 1 webhooks
    Docker:      1 watchers
    HTTP Poll:   1 pollers (5 checks)
    Cron:        2 webhooks
    Generic:     1 webhooks
──────────────────────────────────────────────────────────────────────
```

### 1c. Vrifier que a marche

```bash
# Test health endpoint
curl http://localhost:9090/health
# → {"status":"ok","uptime_seconds":12,"total_notifications":0}

# Test dashboard
curl http://localhost:9090/
# → HTML du dashboard
```

---

## tape 2 — Configurer Gitea

### 2a. Aller dans les rglages du repo

1. Ouvre `https://git.dracodev.net/bruno/flowdeck`
2. Clic sur l'engrenage **Settings** (haut droite)
3. Menu gauche : **Webhooks**
4. Bouton **Add Webhook** → choisir **Gitea**

### 2b. Remplir le formulaire

| Champ | Valeur | Notes |
|---|---|---|
| **Target URL** | `http://192.168.30.X:9090/webhooks/gitea-flowdeck` | Remplacer X par l'IP relle du serveur |
| **HTTP Method** | POST | |
| **POST Content Type** | application/json | |
| **Secret** | `un-secret-que-tu-choisis` | Identique  `hmac_secret` dans le YAML |
| **Trigger On** | Slectionner les vnements souhauts | Push, Pull Request, Issue, Release... |

**Trouver la bonne IP** : sur le serveur o tourne ntfy-bridge :

```bash
# Linux
ip addr show | grep "inet " | grep -v 127.0.0.1

# Windows
ipconfig | findstr "IPv4"
```

### 2c. Cliquer "Add Webhook"

Gitea envoie immdiatement un **test ping** pour vrifier la connectivit.

Rsultat russi :

```
✓ Delivery successful  (HTTP 200)
```

En cas d'chec :

| Erreur | Cause probable | Solution |
|---|---|---|
| Connection refused | ntfy-bridge n'est pas lanc | Lancer `./ntfy-bridge.exe` |
| Connection refused | Firewall bloque le port 9090 | Ouvrir le port dans le firewall |
| HTTP 404 | Mauvais `webhook_path` | Vrifier que `/webhooks/gitea-flowdeck` est exact |
| HTTP 401 | Mauvais `hmac_secret` | Vrifier que le secret est identique des deux cts |
| Timeout | Mauvaise IP ou rseau inaccessible | Vrifier la connectivit rseau |

---

## tape 3 — Tester avec un vrai vnement

### Option A : Test simul (curl)

Depuis n'importe quel poste :

```bash
curl -X POST http://192.168.30.X:9090/webhooks/gitea-flowdeck \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=..." \
  -d '{
    "commits": [{"id": "abc1234567890abcdef1234567890abcdef1234", "message": "test notification ntfy-bridge"}],
    "pusher": {"username": "bruno"},
    "repository": {"full_name": "bruno/flowdeck"}
  }'
```

> Note : si `hmac_secret` est configur, gnre la signature correcte ou dsactive-le temporairement pour le test.

### Option B : Test rel

Fais un push, cre une PR, ou ouvre une issue dans le repo Gitea. Tu devrais recevoir une notification Ntfy dans les secondes qui suivent.

Exemple de notification reue :

```
bruno pushed sur [bruno/flowdeck]: "fix: corrige le bug du dashboard"
```

Ou avec le template par dfaut :

```
 [bruno/flowdeck] bruno pushed: "fix: corrige le bug du dashboard" (abc1234)
```

---

## Ajouter d'autres repos

Rpte les mmes tapes pour chaque repo :

### Dans `ntfy-bridge.yaml`

```yaml
sources:
  gitea:
    - name: "FlowDeck activity"
      webhook_path: /webhooks/gitea-flowdeck
      repo: bruno/flowdeck
      topic: dev-notifs

    - name: "ObsiGate activity"
      webhook_path: /webhooks/gitea-obsigate
      repo: bruno/obsigate
      topic: dev-notifs

    - name: "Imago activity"
      webhook_path: /webhooks/gitea-imago
      repo: bruno/imago
      topic: dev-notifs
```

### Dans Gitea

Pour chaque repo : Settings → Webhooks → Add Webhook avec l'URL correspondante.

```text
http://192.168.30.X:9090/webhooks/gitea-flowdeck   → repo bruno/flowdeck
http://192.168.30.X:9090/webhooks/gitea-obsigate   → repo bruno/obsigate
http://192.168.30.X:9090/webhooks/gitea-imago      → repo bruno/imago
```

---

## Dpannage rapide

```bash
# Vrifier que ntfy-bridge tourne
curl http://localhost:9090/health

# Voir les stats
curl http://localhost:9090/stats

# Voir la config (sans les secrets)
curl http://localhost:9090/api/config

# Voir l'historique des derniers vnements
curl http://localhost:9090/api/history

# Voir le dashboard web
# Ouvre http://localhost:9090/ dans ton navigateur
```

---

## Rfrences

- [README.md](../README.md) — Vue d'ensemble du projet
- [ARCHITECTURE.md](../ARCHITECTURE.md) — Architecture dtaille
- [ntfy-bridge.example.yaml](../ntfy-bridge.example.yaml) — Exemple de config complet
- [Documentation webhooks Gitea](https://docs.gitea.com/usage/webhooks)
- [Documentation Ntfy](https://docs.ntfy.sh/)