Integração com GitHub — Guia de Configuração

Phase 49.3 (Light) — notificações via webhook + feed no sidebar da UI para repos GitHub vinculados. Sem sincronização bidirecional (isso é Phase 49.5+ Heavy).

Arc OS recebe eventos de webhook dos repos GitHub vinculados e, simultaneamente:

1. Envia notificação no Telegram para o dono do projeto
2. Atualiza o feed do sidebar no Workspace ContextRail (polling a cada 30s)

Arquitetura

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 (para UI feed)
    └─→ shared/github-notifier.ts → Telegram (master bot token)

Eventos suportados: push, pull_request, workflow_run, issues. Os demais (releases, deployments, discussions) são ignorados.

Multi-repo: um projeto pode vincular vários repos (ex.: frontend + backend + docs). Restrição: UNIQUE(project_name, owner, repo).

Configuração rápida (3 minutos)

1. Gere o webhook URL + secret

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

Exemplo:

arc github link arc-v2 SerhiiInUa/citadel-v2

O CLI retornará:

• Webhook URL — https://arc-os.co/api/webhooks/github
• Secret — hex de 32 bytes (único para cada vínculo)
• Instruções passo a passo para a UI do GitHub

2. Adicione o webhook no repositório GitHub

Na página https://github.com/<owner>/<repo>/settings/hooks:

1. Clique em Add webhook
2. Payload URL: https://arc-os.co/api/webhooks/github
3. Content type: application/json (importante!)
4. Secret: cole o valor do output do CLI
5. Which events? → "Let me select individual events":
   • ☑ Pushes
   • ☑ Pull requests
   • ☑ Workflow runs
   • ☑ Issues
6. ☑ Active
7. Clique em Add webhook

O GitHub envia imediatamente um evento ping de teste — ele será rejeitado silenciosamente (pois Arc OS aceita apenas os tipos suportados). Isso é esperado.

3. Verifique se está funcionando

Faça um push no repo, abra um PR ou execute um workflow. Em ~1–3 segundos:

• O dono do projeto receberá uma notificação no Telegram com ícone + resumo + link do GitHub
• O feed do sidebar no Workspace ContextRail será atualizado (via polling a cada ~30s)

Gerenciamento de vínculos

Listar repos vinculados

arc github links arc-v2

Remover vínculo

arc github unlink arc-v2 <id>

O ID é obtido no output de arc github links. O webhook no GitHub não é removido automaticamente — assinaturas inválidas serão rejeitadas silenciosamente. Fluxo recomendado: primeiro remova o webhook na UI do GitHub, depois execute arc github unlink.

Segurança

• Assinatura HMAC-SHA256 — cada secret de webhook = crypto.randomBytes(32).toString('hex') (256 bits de entropia)
• Comparação timing-safe — node:crypto timingSafeEqual previne timing attacks na verificação de assinatura
• Rejeição silenciosa — assinaturas inválidas recebem 401 "" sem body (sem vazamento de informação para scanners)
• Rate limit — 100 req/min por projeto (janela em memória). Ao exceder → 429 Rate limited
• Limite de tamanho de payload — 50KB no handler, 64KB no nginx (proteção contra DoS)
• Roteamento de assinatura multi-repo — o handler busca candidatos pelo repository.full_name, depois verifica a assinatura de cada um antes de aceitar (previne reuso de secret entre projetos)
• Isolamento de endpoint público — a configuração do nginx para /api/webhooks/github tem auth_basic off e proxy_read_timeout 5s

O que você vê no sidebar

O ContextRail (painel direito no Workspace) exibe a seção GitHub ⤵

• Oculto automaticamente se o projeto não tiver repos vinculados
• Últimos 8 eventos (mais recente primeiro)
• Ícone por evento: GitBranch (push) / GitPullRequest (PR) / CircleCheck (CI success) / CircleAlert (CI failure) / CircleDot (issues)
• Formato de tempo relativo: 30s, 5m, 2h, 1d
• Clique na linha → abre a URL do GitHub em nova aba
• Polling a cada 30s (dados atualizados sem refresh manual)

Mensagens no Telegram

O Master Bot envia uma mensagem formatada para o dono do projeto:

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

Ícones:

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

Solução de problemas

Webhook retorna 401 no ping de teste

Esperado — Arc OS rejeita silenciosamente eventos não suportados (como ping). Apenas eventos de produção (push, PR, workflow_run, issues) são processados.

Webhook retorna 401 em evento de push

1. Verifique se o webhook no GitHub está configurado com Content type: application/json (não form-urlencoded)
2. Verifique o secret — deve coincidir exatamente com o retornado por arc github link
3. Se o secret foi perdido — remova o vínculo e crie novamente (arc github unlink → arc github link)

Feed do sidebar vazio, mas notificação no Telegram chegou

1. Verifique se o ContextRail está visível (viewport ≥1280px)
2. Faça hard refresh no frontend (Ctrl+Shift+R) — o componente pode estar em cache
3. Verifique o DB: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Notificação no Telegram não chega

1. Verifique se o projeto tem owner_id no DB: sqlite3 ... "SELECT name, owner_id FROM projects;"
2. Verifique o token do Master Bot no vault: grep MASTER_BOT_TOKEN config/vault.json (deve estar criptografado)
3. Evento de webhook está no DB, mas a notificação falhou → veja os logs do master: tmux capture-pane -t citadel-master -p | grep github-notifier

Rate limit atingido

Limite fixo de 100 req/min por projeto. Em ambientes de CI com muitos runners — aumente em shared/routes/github.ts:RATE_MAX.

API endpoints

Detalhes: API Reference.

Roadmap