GitHub Integration — Przewodnik konfiguracji

Phase 49.3 (Light) — powiadomienia oparte na webhookach + feed w sidebarze UI dla powiązanych repozytoriów GitHub. Bez synchronizacji dwukierunkowej (to Phase 49.5+ Heavy).

Arc OS odbiera zdarzenia webhooków z powiązanych repozytoriów GitHub i jednocześnie:

1. Wysyła powiadomienie Telegram do właściciela projektu
2. Aktualizuje feed w sidebarze Workspace ContextRail (polling co 30s)

Architektura

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 (dla feedu UI)
    └─→ shared/github-notifier.ts → Telegram (token master bota)

Obsługiwane zdarzenia: push, pull_request, workflow_run, issues. Pozostałe (releases, deployments, discussions) są ignorowane.

Multi-repo: jeden projekt może mieć powiązanych kilka repozytoriów (np. frontend + backend + docs). Ograniczenie: UNIQUE(project_name, owner, repo).

Szybka konfiguracja (3 minuty)

1. Wygeneruj URL + sekret webhooka

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

Przykład:

arc github link arc-v2 SerhiiInUa/citadel-v2

CLI zwróci:

• Webhook URL — https://arc-os.co/api/webhooks/github
• Secret — 32-bajtowy hex (unikalny dla każdego powiązania)
• Instrukcje krok po kroku dla GitHub UI

2. Dodaj webhook w repozytorium GitHub

Na stronie https://github.com/<owner>/<repo>/settings/hooks:

1. Kliknij Add webhook
2. Payload URL: https://arc-os.co/api/webhooks/github
3. Content type: application/json (ważne!)
4. Secret: wklej wartość z wyjścia CLI
5. Which events? → „Let me select individual events":
   • ☑ Pushes
   • ☑ Pull requests
   • ☑ Workflow runs
   • ☑ Issues
6. ☑ Active
7. Kliknij Add webhook

GitHub od razu wysyła testowe zdarzenie ping — zostanie po cichu odrzucone (Arc oczekuje tylko obsługiwanych typów). To normalne.

3. Sprawdź czy działa

Zrób push do repozytorium, otwórz PR lub uruchom workflow. Po ~1-3 sekundach:

• Właściciel projektu otrzyma powiadomienie Telegram z ikoną + podsumowaniem + linkiem GitHub
• Feed w sidebarze Workspace ContextRail zaktualizuje się (po ~30s pollingu)

Zarządzanie powiązaniami

Lista powiązanych repozytoriów

arc github links arc-v2

Usuń powiązanie

arc github unlink arc-v2 <id>

ID pobierasz z wyjścia arc github links. Webhook w GitHub nie jest usuwany automatycznie — nieprawidłowe sygnatury będą po cichu odrzucane. Lepszy przepływ: najpierw usuń webhook w GitHub UI, potem arc github unlink.

Bezpieczeństwo

• Sygnatura HMAC-SHA256 — każdy sekret webhooka = crypto.randomBytes(32).toString('hex') (256 bitów entropii)
• Porównanie timing-safe — node:crypto timingSafeEqual zapobiega timing attacks na weryfikację sygnatury
• Ciche odrzucenie — nieprawidłowe sygnatury otrzymują 401 "" bez treści (brak wycieku informacji dla skanerów)
• Rate limit — 100 req/min per projekt (okno in-memory). Przekroczenie → 429 Rate limited
• Limit rozmiaru payload — 50KB w handlerze, 64KB w nginx (ochrona przed DoS)
• Routing sygnatury multi-repo — handler szuka kandydatów po repository.full_name, potem weryfikuje sygnaturę każdego przed akceptacją (zapobiega ponownemu użyciu sekretów między projektami)
• Izolacja publicznego endpointu — konfiguracja nginx /api/webhooks/github ma auth_basic off i proxy_read_timeout 5s

Co widzisz w sidebarze

ContextRail (prawy panel w Workspace) pokazuje sekcję GitHub ⤵

• Automatycznie ukryty, jeśli projekt nie ma powiązanych repozytoriów
• Ostatnie 8 zdarzeń (najnowsze pierwsze)
• Ikona per zdarzenie: GitBranch (push) / GitPullRequest (PR) / CircleCheck (sukces CI) / CircleAlert (błąd CI) / CircleDot (issues)
• Format czasu względnego: 30s, 5m, 2h, 1d
• Kliknięcie wiersza → otwiera URL GitHub w nowej karcie
• Polling co 30s (świeże dane bez ręcznego odświeżania)

Powiadomienia Telegram

Master bot wysyła sformatowaną wiadomość do właściciela projektu:

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

Ikony:

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

Troubleshooting

Webhook zwraca 401 na testowy ping

Oczekiwane — Arc po cichu odrzuca nieobsługiwane zdarzenia (np. ping). Tylko zdarzenia produkcyjne (push, PR, workflow_run, issues) są obsługiwane.

Webhook zwraca 401 na zdarzenie push

1. Sprawdź, czy w konfiguracji webhooka GitHub ustawiono Content type: application/json (nie form-urlencoded)
2. Sprawdź sekret — musi dokładnie zgadzać się z tym, co zwrócił arc github link
3. Jeśli sekret został utracony — usuń powiązanie i utwórz ponownie (arc github unlink → arc github link)

Feed w sidebarze jest pusty, choć Telegram przychodzi

1. Sprawdź, czy ContextRail jest w ogóle widoczny (viewport ≥1280px)
2. Wymuś odświeżenie frontendu (Ctrl+Shift+R) — komponent jest buforowany
3. Sprawdź DB: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Telegram nie przychodzi

1. Sprawdź, czy projekt ma owner_id w DB: sqlite3 ... "SELECT name, owner_id FROM projects;"
2. Sprawdź token master bota w vault: grep MASTER_BOT_TOKEN config/vault.json (powinien być zaszyfrowany)
3. Zdarzenie webhooka jest w DB, ale powiadomienie nie powiodło się → sprawdź logi mastera: tmux capture-pane -t citadel-master -p | grep github-notifier

Przekroczony rate limit

Twardy limit 100 req/min/projekt. Przy CI z tysiącami runnerów — podnieś w shared/routes/github.ts:RATE_MAX.

Endpointy API

Szczegóły: API Reference.

Roadmap