# 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 no repositorio (branch dist com artefatos compilados, branch de codigo direto, PR ou tag — configuravel por instance) 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. Por padrao vai para a branch dist junto com os artefatos compilados (instances.X.source.type: dist), mas pode tambem rodar direto de uma branch de codigo, PR, tag ou imagem Docker pronta — configuravel via instances.X.source.type (dist | branch | pr | tag | local | image).

# 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.

# O que acontece quando um deploy falha?

O Runner protege o servico em todas as fases:

• Build falha: o container antigo nao e tocado, site continua no ar
• Container nao inicia: se o anterior foi parado (por conflito de porta), o Runner reinicia automaticamente (v1.4.1+)
• Health check falha: o container novo e removido e o anterior e reiniciado

A notificacao de falha mostra qual versao ficou ativa e o erro real extraido do output.

# O que acontece se o deploy falha repetidamente?

A partir da v1.4.1, o Runner rastreia qual commit falhou. Se o mesmo commit falhar max_deploy_retries vezes (padrao: 3), o deploy automatico e bloqueado ate um novo push (commit diferente) ser feito. Isso evita loops infinitos de notificacoes.

Para configurar:

# /opt/runner/config.yml
max_deploy_retries: 3  # 0 = ilimitado

# Como faco rollback?

runner rollback --app /data/apps/meu-app

Ou para versao especifica:

runner rollback meu-app --to v1.0.0

# Como deployar a mesma app em maquinas diferentes?

Use --instance ao registrar a app em cada maquina:

# Maquina de producao
runner add --repo usuario/meu-app --instance production

# Maquina de staging
runner add --repo usuario/meu-app --instance staging

Cada maquina deploya apenas sua instancia. Variaveis de ambiente e secrets sao isolados por instancia. Veja o guia Multi-Ambiente.

# 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.

# Posso fixar o nome do container?

Nao, e e por design. O nome e sempre derivado: {project}_{instancia}_{versao} (ex: meu_app_production_v1-2-3). A versao no nome e o que sustenta o blue-green — o container novo sobe enquanto o antigo ainda existe, e o antigo so e removido depois do health check passar. Com nome fixo os dois colidiriam, e voce perderia o deploy sem downtime.

Se o objetivo e outro container achar esse por um nome estavel, use network_aliases: — um alias DNS que aponta sempre pro container atual, independente da versao:

networks:
  - internal_ccs_da
network_aliases:
  internal_ccs_da: [meu-app]     # outro container conecta em `meu-app:8000` pra sempre

O Runner troca o container a cada deploy e o alias segue apontando pro novo. Veja Network avancado para a sintaxe completa (inclusive a forma inline, com o alias junto da network).

Se o app veio de um docker-compose.yml, o wizard ja popula network_aliases: com o service-name original — apps do mesmo bundle se resolvem por nome curto (livekit:7880), igual no compose.

Outros casos que costumam virar "quero fixar o nome":

# 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 /data/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 /data/apps/meu-app

# Posso deployar sem Traefik?

Sim (v2.0.1+). Use ports: no .deploy.yml e nao coloque domain na instancia. O runner mapeia portas diretamente no container e pula a geracao de Traefik config.

# Como limpo imagens Docker antigas?

runner cleanup --images --build-cache 72h

Ou configure no cron semanal. O pipeline tambem limpa automaticamente imagens de versoes que excedem keep_versions.

# O token do GitHub aparece no `ps aux`?

Nao (v2.0.5+). O runner usa GIT_ASKPASS — o token e passado via pipe, nunca aparece nos argumentos do processo ou no .git/config.

# O runner detecta secrets automaticamente?

Sim (v2.4.2). O runner env set analisa o nome da variavel com Aho-Corasick e classifica por confianca. DB_PASSWORD e encriptado automaticamente (se tem ckey). CACHE_KEY e max_tokens sao filtrados como falsos positivos. Use --secret ou --force para forcar.

# O que e `deploy_id`?

Um identificador unico de 8 caracteres gerado por deploy (v2.0.7). Aparece em todas as notificacoes para correlacao entre mensagens.

# Posso registrar um PR para auto-deploy?

Sim (v2.0.0+). Use runner add --repo user/repo --pr 42 --branch feat/checkout. O runner detecta updates e deploya automaticamente. Cleanup por TTL (48h) ou merge/close.

# Preciso de mais ajuda?

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