# 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                      │
│                                                                  │
│   /data/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

# Self-Update (v1.1.0)

• Atualizacao automatica do binario
• Canais: stable (producao) e rc (release candidate)
• Download de https://runner.ccs.systems/runner

# Canais GitOps (v1.1.6)

• Releases estáveis na raiz: /runner
• Release candidates em: /rc/runner
• Versionamento automatico por tag pattern

# Secrets Encriptados e Recovery (v1.3.2)

• Encriptacao AES-256-GCM com content key (ckey) por projeto
• Secrets persistidos como .runner/secrets.enc no repositorio
• Recuperacao zero-touch em caso de perda do servidor
• runner deploy --all para redeploy massivo apos recovery
• Network Docker auto-creation

# 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. Secrets e Encriptacao - Recuperacao zero-touch
4. Referencia CLI - Todos os comandos disponiveis
5. Configuracao - Formato do .deploy.yml

# Links Uteis

• Changelog completo
• Troubleshooting
• FAQ