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

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

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

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

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

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

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.

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

# 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 — Vue d'ensemble du projet
• ARCHITECTURE.md — Architecture dtaille
• ntfy-bridge.example.yaml — Exemple de config complet
• Documentation webhooks Gitea
• Documentation Ntfy