# Configurando Notificacoes

O Runner envia notificacoes de deploy via Telegram, Discord ou ambos simultaneamente, alem de gravar um audit trail em JSON Lines.

# Arquitetura v1.4.0

A partir da v1.4.0, o pipeline usa o NotifyManager v2 com suporte a multiplos canais:

config.yml (notify:)
       |
       v
  NotifyManager
       |
  +----+----+----+
  |         |    |
Telegram  Discord  StructuredLog
(HTTP)    (HTTP)   (deploy-events.jsonl)

Canais ativados automaticamente:

• Telegram — se telegram_bot_token e telegram_chat_id configurados
• Discord — se discord_webhook configurado
• Structured Log — sempre ativo (audit trail em JSONL)

# Setup Rapido

# Via comando (recomendado)

runner notify setup --channel telegram

O setup interativo:

1. Pede o token do bot (do @BotFather)
2. Valida via API do Telegram (getMe)
3. Pede para enviar mensagem ao bot (DM, grupo ou canal)
4. Auto-detecta chat_id — se encontrar multiplos chats, mostra lista
5. Envia mensagem de teste
6. Salva no config.yml

# Setup completo

# Telegram
runner notify setup --channel telegram

# Discord
runner notify setup --channel discord

# Ambos
runner notify setup --channel both

# Verificar status
runner notify status

# Testar envio
runner notify test

# Configuracao no config.yml

# /opt/runner/config.yml
notify:
  channel: telegram           # telegram | discord | both
  telegram_bot_token: "123456789:ABCdefGHI..."
  telegram_chat_id: "-1001234567890"
  discord_webhook: "https://discord.com/api/webhooks/..."

# Telegram

# Criar Bot

1. Abra o Telegram e busque @BotFather
2. Envie /newbot
3. Siga as instrucoes para criar o bot
4. Copie o token (formato: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

# Enviar para DM (mensagem privada)

runner notify setup --channel telegram

1. Cole o token do bot
2. Envie qualquer mensagem direto pro bot no Telegram
3. Aperte Enter — o setup detecta o chat automaticamente

# Enviar para Grupo

1. No BotFather: /mybots > seu bot > Bot Settings > Group Privacy > Turn off
2. Adicione o bot ao grupo
3. Envie uma mensagem no grupo
4. Execute runner notify setup --channel telegram
5. Cole o token e aperte Enter
6. Escolha o grupo na lista de chats detectados

# Enviar para Canal

Canais exigem setup manual porque o bot nao recebe getUpdates de canais.

1. Adicione o bot como administrador do canal (permissao "Post Messages")

2. Descubra o chat_id:

   Canal publico (@meucanal):

   curl -s "https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=@meucanal&text=teste"

   Na resposta, pegue chat.id (negativo, tipo -1001234567890).

   Canal privado: encaminhe uma mensagem do canal pro @userinfobot — ele responde com o ID.

3. Edite o config.yml:

   notify:
     channel: telegram
     telegram_bot_token: "SEU_TOKEN"
     telegram_chat_id: "-100XXXXXXXXXX"

4. Teste: runner notify test

# Exemplo de Mensagem

Deploy Iniciado
Projeto: meu-app
Instancia: production
Versao: v1.2.0

Deploy Concluido
Projeto: meu-app
Instancia: production
Versao: v1.2.0

# Discord

# Criar Webhook

1. Abra as configuracoes do canal Discord
2. Va em Integracoes > Webhooks
3. Clique em "Criar Webhook"
4. Copie a URL do webhook

# Configurar

runner notify setup --channel discord

Cole a URL do webhook quando solicitado. O setup envia um embed de teste e salva no config.yml.

# Manual

notify:
  channel: discord
  discord_webhook: "https://discord.com/api/webhooks/123456/abcdef..."

# Telegram vs Discord

# Eventos Notificados

# Formato das Notificacoes (v2.0.7)

Todas as notificacoes incluem um deploy_id (8 caracteres) para correlacao entre mensagens.

# Deploy com Sucesso

✅ Deploy Concluído

📦 Projeto: meu-app
🌐 Instance: production
🏷️ Versão: v1.2.0
🆔 a3f7c2d1

# Deploy com Falha — Mensagem 1 (resumo)

Quando o deploy falha, a primeira notificacao mostra o erro extraido (ate 800 chars) e qual versao ficou ativa:

❌ Deploy Falhou

📦 Projeto: meu-app
🌐 Instance: production
🏷️ Versão: abc1234
🆔 a3f7c2d1
🔄 Rollback: v1.0.0 (versão anterior mantida)

⚠️ Erro:
docker build failed: npm ERR! missing: react

O Runner detecta automaticamente a linha de erro relevante em outputs verbosos do Docker BuildKit, npm, compiladores Rust, Python, etc.

# Deploy com Falha — Mensagem 2 (verbose)

Se o erro for maior que 800 caracteres, o runner envia automaticamente uma segunda mensagem com o log completo (ate 3800 chars), vinculada pelo mesmo deploy_id:

📋 Log de Erro Completo
🆔 a3f7c2d1
📦 meu-app/production

docker build failed: #8 [build 3/5] RUN npm install
#8 2.341 npm ERR! code E404
#8 2.342 npm ERR! 404 Not Found - GET https://registry...
#8 2.343 npm ERR! 404 'react-missing@latest' is not in
#8 2.344 npm ERR! the npm registry.
...
(log completo do build)

Configuravel no config.yml:

notify:
  verbose_errors: true    # default: true (envia segunda mensagem)

Para desabilitar: verbose_errors: false.

# Deploy Bloqueado (retry exaurido)

Quando o mesmo commit falha max_deploy_retries vezes (padrao: 3), o deploy automatico para de tentar. Nenhuma notificacao adicional e enviada — apenas o log do fetch --deploy registra:

⊘ meu-app/front — deploy bloqueado (mesmo commit falhou 3x)

O deploy e desbloqueado automaticamente ao receber um novo push (commit diferente).

# Structured Logging (Audit Trail)

Alem das notificacoes por canal, o pipeline grava todos os eventos em deploy-events.jsonl no diretorio de logs (/opt/runner/logs/).

Cada linha e um JSON:

{"timestamp":"2026-03-12T17:45:00Z","event_type":"DeployStarted","project":"meu-app","instance":"production","version":"v1.2.0"}
{"timestamp":"2026-03-12T17:46:30Z","event_type":"DeploySuccess","project":"meu-app","instance":"production","version":"v1.2.0"}

O structured log e sempre ativo, independente dos canais configurados.

# Comandos

# Desabilitar Notificacoes

Nao configure nenhum canal no config.yml — ou remova a secao notify:.

# Troubleshooting

# Telegram nao envia

1. Verifique o token: runner notify status
2. Verifique se o chat_id esta correto (negativo para grupos/canais)
3. Para grupos: verifique se o bot foi adicionado e o Group Privacy esta desligado
4. Para canais: verifique se o bot e admin com permissao "Post Messages"
5. Teste manualmente:

   curl -s "https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>&text=teste"

# Discord nao envia

1. Verifique a URL do webhook: runner notify status
2. Verifique se o webhook nao foi deletado no Discord
3. Teste manualmente:

   curl -X POST "<WEBHOOK_URL>" -H "Content-Type: application/json" -d '{"content":"teste"}'

# Setup nao detecta chat_id

1. Certifique-se de enviar a mensagem depois do bot ser validado
2. Envie a mensagem e espere 2-3 segundos antes de apertar Enter
3. Se nao detectar, o setup pede o chat_id manualmente

# Logs estruturados nao escrevem

1. Verifique permissoes do diretorio /opt/runner/logs/
2. O diretorio e criado automaticamente se nao existir