# Troubleshooting

Solucoes para problemas comuns no CI/CD Runner.

# Deploy

# Deploy nao inicia

Sintoma: Push na dist nao aciona deploy.

Causas e solucoes:

1. App nao registrada

   runner list
   # Se nao aparecer:
   runner add --repo usuario/meu-app

2. Cron nao configurado

   crontab -l | grep runner
   # Se nao aparecer, adicionar:
   */5 * * * * /opt/runner/runner fetch --deploy --json >> /var/log/runner-fetch.json 2>&1

3. Branch errada

   cd /apps/usuario_meu-app
   git branch
   # Deve estar na dist

4. Configuracao invalida

   runner validate --file /apps/usuario_meu-app/.deploy.yml

# Health check falha

Sintoma: Deploy falha com "health check timeout".

Solucoes:

1. Verificar endpoint

   # Ver se endpoint existe
   docker exec CONTAINER curl -s http://localhost:8000/health

2. Verificar porta

   # Porta configurada correta?
   grep port /apps/meu-app/.deploy.yml

3. Ver logs do container

   docker logs CONTAINER --tail 100

4. Verificar status

   docker inspect CONTAINER --format='{{.State.Health.Status}}'

# Container nao sobe

Sintoma: Deploy falha, container nao inicia.

Solucoes:

1. Ver logs

   docker logs CONTAINER --tail 200

2. Verificar imagem

   docker images | grep IMAGEM

3. Testar manualmente

   docker run --rm -it IMAGEM /bin/sh

4. Verificar volumes

   docker inspect CONTAINER --format='{{.Mounts}}'

# Rollback falha

Sintoma: Rollback nao funciona.

Solucoes:

1. Verificar versoes

   runner versions meu-app -i production
   # Precisa ter versao anterior

2. Verificar logs

   runner logs tail --app /apps/meu-app

# Staging

# Staging nao cria

Sintoma: runner stage deploy falha.

Solucoes:

1. Verificar GitHub CLI

   gh --version
   gh auth status

2. Verificar limite

   runner stage list
   # Se cheio, destruir algum
   runner stage destroy --id staging_app_pr35

3. Verificar PR existe

   gh pr view 42 --repo usuario/meu-app

# DNS nao resolve

Sintoma: Staging criado mas URL nao funciona.

Solucoes:

1. Verificar wildcard DNS

   dig pr-42.staging.meusite.com.br
   # Deve resolver para IP do servidor

2. Verificar Traefik

   ls /etc/traefik/dynamic/ | grep staging

3. Verificar container

   docker ps | grep staging_meu-app_pr42

# Canary

# Peso nao muda

Sintoma: runner weight executa mas trafego nao muda.

Solucoes:

1. Verificar Traefik config

   cat /etc/traefik/dynamic/meu-app.yml
   # Ver se weights estao corretos

2. Recarregar Traefik

   # Traefik faz hot-reload automatico
   # Mas pode verificar logs:
   docker logs traefik --tail 50

3. Verificar ambas versoes

   docker ps | grep meu-app
   # Ambos containers devem estar rodando

# Notificacoes

# Telegram nao envia

Solucoes:

1. Verificar token

   curl "https://api.telegram.org/bot{TOKEN}/getMe"

2. Verificar chat_id

   # Para grupos, deve ser negativo
   grep telegram /opt/runner/config.yml

3. Testar envio

   curl -X POST "https://api.telegram.org/bot{TOKEN}/sendMessage" \
     -d "chat_id={CHAT_ID}" \
     -d "text=Teste"

# Discord nao envia

Solucoes:

1. Verificar webhook

   curl -X POST "{WEBHOOK_URL}" \
     -H "Content-Type: application/json" \
     -d '{"content": "Teste"}'

2. Webhook existe?

   • Verificar se nao foi deletado no Discord

# MCP Server

# Claude Code nao reconhece

Solucoes:

1. Verificar instalacao

   runner mcp status

2. Reinstalar

   runner mcp uninstall
   runner mcp install

3. Reiniciar Claude Code

   • Fechar e abrir novamente

4. Verificar config

   cat ~/.config/claude/claude_desktop_config.json

# Tools nao funcionam

Solucoes:

1. Verificar binario

   /opt/runner/runner --version

2. Testar CLI diretamente

   runner list

# Git

# Fetch falha

Sintoma: runner fetch com erro.

Solucoes:

1. Verificar acesso

   cd /apps/meu-app
   git fetch origin dist

2. Verificar SSH key

   ssh -T git@github.com

3. Verificar URL

   git remote -v

# Conflitos na dist

Solucoes:

O Runner usa git reset --hard, conflitos nao devem ocorrer.

Se ocorrer:

cd /apps/meu-app
git fetch origin dist
git reset --hard origin/dist
git clean -fd

# Logs

# Onde estao os logs?

# Ver logs recentes

# Fetch
tail -50 /var/log/runner-fetch.json | jq .

# Deploy de uma app
runner logs tail --app /apps/meu-app

# Historico
runner logs history --app /apps/meu-app

# Comandos de Diagnostico

# Status geral
runner list --detailed

# Verificar app especifica
runner health --app /apps/meu-app

# Validar config
runner validate --file /apps/meu-app/.deploy.yml

# Ver versoes
runner versions meu-app -i production

# Ver pesos
runner weights meu-app -i production

# Listar stagings
runner stage list

# Status MCP
runner mcp status