# CI/CD Runner

Sistema de deploy automatizado escrito em Rust para orquestracao de deployments via Git.

# Visao Geral

# Objetivos do Projeto

O Runner foi criado para resolver os seguintes problemas:

1. Deploy manual propenso a erros - Automatizar todo o pipeline de deploy
2. Downtime durante deploys - Estrategia blue-green com zero downtime
3. Dificuldade em testar PRs - Ambientes de staging efemeros para cada PR
4. Rollout arriscado - Canary deployments com controle de trafego
5. Falta de visibilidade - Notificacoes em tempo real e logs estruturados

# Hipotese de Solucao

PROBLEMA: Deploys manuais sao lentos, propensos a erro e causam downtime

SOLUCAO: Pipeline automatizado baseado em Git
         - Push na branch `dist` aciona deploy
         - Runner detecta mudancas via cron (fetch a cada 5 min)
         - Deploy blue-green com health check antes de promover
         - Rollback automatico em caso de falha
         - Notificacao via Telegram/Discord

# Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                         REPOSITORIO                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   dev ──────────────────► main ──────────────────► dist         │
│    │                       │                        │            │
│    │ Desenvolvimento       │ Releases               │ Deploy     │
│    │ Codigo fonte          │ Tags vX.Y.Z            │ Artefatos  │
│    │ Testes locais         │ Codigo estavel         │ Builds     │
│    │                       │                        │            │
│    ▼                       ▼                        ▼            │
│  Trabalho               Producao               CI/CD Runner      │
│   diario               aprovado              faz deploy aqui     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                                                      │
                                                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                     SERVIDOR DE PRODUCAO                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   /opt/runner/                                                   │
│   ├── runner              # Binario                              │
│   ├── config.yml          # Config global                        │
│   └── state/              # Estado das apps                      │
│                                                                  │
│   /apps/{projeto}/                                               │
│   ├── .deploy.yml         # Config do projeto                    │
│   └── src/                                                       │
│       ├── production/     # Instancia producao                   │
│       │   ├── v1.0.0/                                           │
│       │   └── v1.0.1/     # Versao ativa                        │
│       └── staging/        # Instancia staging                    │
│                                                                  │
│   /etc/traefik/dynamic/                                          │
│   └── {projeto}.yml       # Routing dinamico                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

# Hierarquia de Entidades

Projeto → Instancia → Versao

meu-projeto/
├── production/     # Instancia com dominio app.projeto.com.br
│   ├── v0.1.5/
│   └── v0.1.6/     # Versao ativa
└── staging/        # Instancia com dominio staging.projeto.com.br
    └── develop/

# Features Principais

# Deploy Automatizado

• Deteccao automatica de mudancas via runner fetch --deploy
• Cron a cada 5 minutos verifica atualizacoes
• Build local, artefatos na branch dist

# Blue-Green Deployment

• Nova versao testada em container isolado
• Health check antes de promover
• Rollback automatico se falhar

# Canary Deployment

• Controle de trafego via weighted services do Traefik
• Promocao gradual (10% → 50% → 100%)
• Zero downtime na mudanca de peso

# Staging de PRs

• Ambientes efemeros para cada Pull Request
• Dominio unico (pr-42.staging.projeto.com.br)
• Cleanup automatico por TTL

# MCP Server (v1.1.0)

• Integracao com Claude Code via Model Context Protocol
• 25+ tools para gerenciamento de deploys
• Resources com documentacao embarcada
• Prompts guiados para workflows

# Seguranca

• Scan de secrets no codigo
• NPM audit e Python bandit
• Health checks obrigatorios
• Permissoes restritas em arquivos .secrets

# Versionamento

# Historico de Versoes

# Roadmap

• Multi-service support (app + worker + scheduler)
• Shared volumes em /data/apps/{projeto}/resource/
• Webhook de PR closed para auto-destroy
• Dashboard web para visualizacao

# Requisitos de Sistema

# Servidor de Producao

# Dependencias

• Docker Engine rodando
• Traefik configurado com dynamic config
• Acesso ao GitHub (token ou SSH key)
• Opcional: Telegram Bot / Discord Webhook para notificacoes

# Proximos Passos

1. Inicio Rapido - Instale e configure o Runner
2. Primeiro Deploy - Faca seu primeiro deploy
3. Referencia CLI - Todos os comandos disponiveis
4. Configuracao - Formato do .deploy.yml

# Links Uteis

• Changelog completo
• Troubleshooting
• FAQ