# Reverter para versão anterior

Sintoma — gatilho típico:

Deploy v1.3.0 passou no healthcheck mas a feature nova está quebrando em prod.

Ou: healthcheck automático falhou e o runner reverteu sozinho, mas você quer forçar rollback para uma versão específica anterior.

# Causa

A versão nova tem bug funcional — não de infraestrutura. O container subiu, o health passou (ou você quer ir além do rollback automático), mas o comportamento em produção está errado.

# Diagnóstico — qual versão voltar

Primeiro, identifique qual versão estava boa:

runner instances meu-app          # lista versões disponíveis com timestamps
runner logs history meu-app       # logs dos deploys passados
runner audit --project meu-app    # eventos: deploy_success, rollback_started, etc.

runner instances mostra versões retidas no servidor (controlado por keep_versions no manifest). Se a versão desejada não estiver mais disponível localmente, você precisa re-deployar da dist.

# Fix — rollback para versão imediatamente anterior

runner rollback meu-app

Sem flags, o runner volta pra versão anterior ao deploy atual.

# Fix — rollback para versão específica

runner rollback meu-app --version v1.2.3

Alternativa via promote (força 100% de tráfego para uma versão retida):

runner promote meu-app -i production v1.2.3

Use promote se você quiser confirmar a versão sem o blue-green completo do rollback.

# Cuidado com efeitos colaterais

Schema de banco de dados — se a v1.3.0 rodou migrations, voltar para v1.2.3 pode quebrar a app se o schema novo é incompatível. Rode a migration reversa antes do rollback.

Secrets adicionados na versão nova — a v1.2.3 não conhecia NOVA_VAR criada na v1.3.0. A app não vai falhar por isso (a variável simplesmente não existia antes), mas confirme que nada crítico depende dela.

Cache — se a v1.3.0 invalidou ou mudou o formato do cache, a v1.2.3 pode ler dados inválidos. Considere flushar o Redis antes de confirmar o rollback.

# Workflow seguro

Use este fluxo quando o bug é crítico e você precisa de controle total:

# 1. Ver versões disponíveis
runner instances meu-app

# 2. Pausar para impedir auto-deploy enquanto investiga
runner pause meu-app

# 3. Reverter para a versão estável
runner rollback meu-app --version v1.2.3

# 4. Validar que está OK
runner status meu-app
curl -s https://meu-app.com.br/health

# 5. Liberar auto-deploy quando estiver tudo OK
runner unpause meu-app

runner pause garante que o cron fetch --deploy não vai re-deployar a versão quebrada enquanto você valida o rollback.

# Reset completo (último recurso)

Se o state do runner estiver inconsistente ou você precisar reconstruir o ambiente do zero:

runner reset meu-app

Com --hard, também limpa .env, .secrets e persistent_dirs:

runner reset meu-app --hard

Use reset apenas quando rollback não for suficiente. O reset redeploya a partir do zero e exige que o wizard seja re-executado se os secrets forem wipados.

# Como prevenir

• Canary deployment — suba a versão nova com peso baixo (10-20%) antes de ir a 100%. Ver Multi-instance routing.
• Healthcheck robusto — o check padrão só valida que o container subiu. Um endpoint /health que exercita DB e dependências pega mais bugs antes de chegar ao usuário.
• Testes E2E antes do push — runner deploy aceita --skip-tests mas não use em produção sem razão clara.

# Ver também

• Healthcheck failed — rollback automático por health
• Multi-instance routing — canary + blue-green
• Pause/unpause — controle manual do cron