# FAQ

Perguntas frequentes sobre o CI/CD Runner.

# Geral

# O que e o Runner?

O Runner e um sistema de deploy automatizado escrito em Rust. Ele detecta mudancas na branch dist do seu repositorio e executa deploy automatico no servidor de producao.

# Preciso de Docker?

Sim. O Runner usa Docker para gerenciar containers das aplicacoes e Traefik para routing HTTP.

# Preciso de Kubernetes?

Nao. O Runner foi projetado para ambientes single-server com Docker. Para Kubernetes, considere outras solucoes como ArgoCD.

# Qual a diferenca entre Runner e GitHub Actions?

# O Runner suporta multiplos servidores?

Nao diretamente. O Runner foi projetado para single-server. Para multiplos servidores, considere o DeployAlly ou configure runners independentes.

# Configuracao

# Onde fica o .deploy.yml?

Na raiz do seu repositorio, versionado junto com o codigo. Ele vai para a branch dist junto com os artefatos.

# Posso ter multiplas instancias?

Sim. Configure no .deploy.yml:

instances:
  production:
    domain: app.meusite.com.br
  staging:
    domain: staging.meusite.com.br
  pr:
    domain_pattern: "pr-${PR_NUMBER}.staging.meusite.com.br"

# Como configuro variaveis de ambiente?

1. Crie .env.template com templates
2. O Runner gera .env e .secrets no primeiro deploy
3. Para secrets, use ${GENERATE:secret:32}

# Quantas versoes o Runner mantem?

Configuravel via keep_versions no .deploy.yml. Padrao: 3 versoes.

# Deploy

# O deploy e automatico?

Sim, via cron. Configure para executar runner fetch --deploy a cada 5 minutos.

# Como faco rollback?

runner rollback --app /apps/meu-app

Ou para versao especifica:

runner rollback meu-app --to v1.0.0

# O que e blue-green deployment?

E uma estrategia onde a nova versao e testada em um container separado antes de receber trafego. Se o health check passar, o trafego e direcionado para a nova versao.

# O que e canary deployment?

E uma estrategia onde a nova versao recebe gradualmente mais trafego (10% → 50% → 100%), permitindo validar em producao antes do rollout completo.

# Posso pular os testes?

Sim:

runner deploy meu-app --skip-tests

Mas nao e recomendado em producao.

# Staging

# O que sao ambientes de staging?

Sao ambientes temporarios criados para testar Pull Requests antes do merge. Cada PR pode ter seu proprio ambiente acessivel via URL unica.

# Quanto tempo dura um staging?

Configuravel via ttl_hours. Padrao: 48 horas. Apos o TTL, e destruido automaticamente pelo cleanup.

# Quantos stagings posso ter?

Configuravel via max_instances (por projeto) e max_total_instances (global).

# Preciso de DNS wildcard?

Sim, para staging de PRs. Configure *.staging.seudominio.com apontando para o servidor.

# MCP

# O que e MCP?

Model Context Protocol. E um protocolo para integrar ferramentas com assistentes de IA como Claude Code.

# Como integro com Claude Code?

runner mcp install

Depois reinicie o Claude Code.

# Quais tools estao disponiveis?

25+ tools para deploy, rollback, canary, staging, environment, logs, etc. Veja Referencia MCP.

# Performance

# O deploy causa downtime?

Nao. O Runner usa blue-green deployment. A nova versao e testada antes de receber trafego.

# Quanto tempo leva um deploy?

Depende do tamanho da aplicacao e testes configurados. Tipicamente 30-120 segundos.

# O canary causa downtime?

Nao. Mudancas de peso sao feitas via Traefik hot-reload, sem reiniciar containers.

# Seguranca

# Onde ficam os secrets?

No arquivo .secrets com permissao 600 (apenas root pode ler). O Runner gera este arquivo automaticamente.

# O Runner escaneia vulnerabilidades?

Sim. Executa NPM audit e Python bandit antes do deploy.

# Como atualizo o Runner?

runner self-update

Ou para release candidate:

runner self-update --channel rc

# Integracao

# Funciona com GitHub?

Sim. O Runner clona repositorios do GitHub via Git.

# Funciona com GitLab/Bitbucket?

Em teoria sim (qualquer Git), mas testado apenas com GitHub.

# Posso usar com Terraform?

Sao complementares. Terraform para infraestrutura, Runner para deploy de aplicacoes.

# Troubleshooting

# Onde vejo os logs?

• Fetch: /var/log/runner-fetch.json
• Deploy: runner logs tail --app /apps/meu-app
• Container: docker logs CONTAINER

# Como valido minha configuracao?

runner validate --file .deploy.yml

# Como verifico o health de uma app?

runner health --app /apps/meu-app

# Preciso de mais ajuda?

• Troubleshooting - Problemas comuns
• Referencia CLI - Comandos detalhados
• Logs: verifique /opt/runner/logs/ e /var/log/runner-*.json