GitHub Integration — Setup Guide

Phase 49.3 (Light) — webhook-basierte Benachrichtigungen + UI-Sidebar-Feed für verknüpfte GitHub-Repos. Kein bidirektionaler Sync (das ist Phase 49.5+ Heavy).

Arc OS empfängt Webhook-Events aus verknüpften GitHub-Repos und macht gleichzeitig:

1. Schickt dem Projekt-Owner eine Telegram-Benachrichtigung
2. Aktualisiert den Sidebar-Feed im Workspace ContextRail (Polling alle 30s)

Architektur

GitHub repo
    │  (push / PR / CI / issue events)
    ▼
arc-os.co/api/webhooks/github
    │  HMAC-SHA256 timing-safe verify (X-Hub-Signature-256)
    │  Rate limit 100 req/min/project
    │  Payload max 50KB
    ▼
shared/routes/github.ts handleGithubWebhook
    ├─→ DB: github_events (für UI-Feed)
    └─→ shared/github-notifier.ts → Telegram (master bot token)

Unterstützte Events: push, pull_request, workflow_run, issues. Alles andere (releases, deployments, discussions) wird ignoriert.

Multi-Repo: Ein Projekt kann mehrere Repos verknüpfen (z. B. frontend + backend + docs). Constraint: UNIQUE(project_name, owner, repo).

Schnelles Setup (3 Minuten)

1. Webhook-URL + Secret generieren

arc github link <project-name> <owner/repo>

Beispiel:

arc github link arc-v2 SerhiiInUa/citadel-v2

Die CLI gibt zurück:

• Webhook URL — https://arc-os.co/api/webhooks/github
• Secret — 32-Byte-Hex (einzigartig pro Link)
• Schritt-für-Schritt-Anleitung für die GitHub-UI

2. Webhook im GitHub-Repo hinzufügen

Auf der Seite https://github.com/<owner>/<repo>/settings/hooks:

1. Klick auf Add webhook
2. Payload URL: https://arc-os.co/api/webhooks/github
3. Content type: application/json (wichtig!)
4. Secret: Wert aus dem CLI-Output einfügen
5. Which events? → "Let me select individual events":
   • ☑ Pushes
   • ☑ Pull requests
   • ☑ Workflow runs
   • ☑ Issues
6. ☑ Active
7. Klick auf Add webhook

GitHub schickt sofort einen Test-ping-Event — dieser wird still abgelehnt (da Arc OS nur unterstützte Types erwartet). Das ist normal.

3. Prüfen, ob alles funktioniert

Mach einen Push ins Repo, öffne einen PR oder starte einen Workflow. Nach ~1–3 Sekunden:

• Der Projekt-Owner bekommt eine Telegram-Benachrichtigung mit Icon + Zusammenfassung + GitHub-Link
• Der Sidebar-Feed im Workspace ContextRail aktualisiert sich (nach ~30s Polling)

Links verwalten

Liste der verknüpften Repos

arc github links arc-v2

Link entfernen

arc github unlink arc-v2 <id>

Die ID kommt aus dem Output von arc github links. Der Webhook auf GitHub wird dabei nicht automatisch gelöscht — ungültige Signaturen werden still abgelehnt. Empfohlener Workflow: Zuerst den Webhook in der GitHub-UI löschen, dann arc github unlink ausführen.

Sicherheit

• HMAC-SHA256-Signatur — jedes Webhook-Secret = crypto.randomBytes(32).toString('hex') (256 Bit Entropie)
• Timing-safe Compare — node:crypto timingSafeEqual verhindert Timing-Angriffe auf die Signaturprüfung
• Silent Reject — ungültige Signaturen erhalten 401 "" ohne Body (kein Info-Leak an Scanner)
• Rate Limit — 100 req/min pro Projekt (In-Memory-Fenster). Bei Überschreitung → 429 Rate limited
• Payload-Größenlimit — 50KB im Handler, 64KB in nginx (DoS-Schutz)
• Multi-Repo Signature Routing — der Handler sucht Kandidaten anhand repository.full_name, prüft dann die Signatur jedes einzelnen, bevor er akzeptiert (verhindert Secret-Reuse cross-project)
• Public-Endpunkt-Isolation — nginx-Konfiguration für /api/webhooks/github hat auth_basic off und proxy_read_timeout 5s

Was du in der Sidebar siehst

ContextRail (rechtes Panel im Workspace) zeigt den Abschnitt GitHub ⤵

• Automatisch ausgeblendet, wenn das Projekt keine verknüpften Repos hat
• Die letzten 8 Events (neueste zuerst)
• Icon pro Event: GitBranch (push) / GitPullRequest (PR) / CircleCheck (CI success) / CircleAlert (CI failure) / CircleDot (Issues)
• Relatives Zeitformat: 30s, 5m, 2h, 1d
• Klick auf eine Zeile → öffnet die GitHub-URL in einem neuen Tab
• Polling alle 30s (aktuelle Daten ohne manuelles Refresh)

Telegram-Nachrichten

Der Master Bot schickt dem Projekt-Owner eine formatierte Nachricht:

🔀 [arc-v2] SerhiiInUa/citadel-v2
PR #42 opened: feat: add lazy worker lifecycle by @Sergei89
View on GitHub

Icons:

• 📦 push
• 🔀 pull_request
• ✅ workflow_run (success)
• ❌ workflow_run (failure)
• ⚙️ workflow_run (other)
• 🐛 issues

Troubleshooting

Webhook gibt 401 beim Test-Ping zurück

Erwartet — Arc OS lehnt nicht unterstützte Events still ab (z. B. ping). Nur produktive Events (push, PR, workflow_run, issues) werden verarbeitet.

Webhook gibt 401 beim Push-Event zurück

1. Prüfe, ob im GitHub-Webhook Content type: application/json eingestellt ist (nicht form-urlencoded)
2. Prüfe das Secret — es muss exakt mit dem übereinstimmen, was arc github link zurückgegeben hat
3. Falls das Secret verloren gegangen ist — Link löschen und neu erstellen (arc github unlink → arc github link)

Sidebar-Feed ist leer, obwohl Telegram-Nachrichten ankommen

1. Prüfe, ob der ContextRail überhaupt sichtbar ist (Viewport ≥1280px)
2. Frontend hard refreshen (Ctrl+Shift+R) — die Komponente wird gecacht
3. DB prüfen: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Telegram-Nachrichten kommen nicht an

1. Prüfe, ob das Projekt owner_id in der DB hat: sqlite3 ... "SELECT name, owner_id FROM projects;"
2. Prüfe den Master-Bot-Token im Vault: grep MASTER_BOT_TOKEN config/vault.json (muss verschlüsselt sein)
3. Webhook-Event ist in der DB, aber Benachrichtigung schlägt fehl → Master-Logs ansehen: tmux capture-pane -t citadel-master -p | grep github-notifier

Rate Limit erreicht

Hard Limit: 100 req/min pro Projekt. Bei CI mit tausenden Runnern — erhöhe den Wert in shared/routes/github.ts:RATE_MAX.

API-Endpunkte

Details: API Reference.

Roadmap