Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Runbook de reversão de lançamento

Status: Ativo Escopo: público, estado atual Última revisão: 2026-09-03 Responsável: engenharia de lançamento do AX Code

Este runbook descreve como retirar um lançamento publicado estável (canal latest) da CLI do AX Code e restaurar o anterior. Lançamentos de pré-lançamento (canal beta) não tocam o tap do Homebrew nem o winget, então revertê-los exige apenas o passo de lançamento do GitHub abaixo.

Prefira hotfix à frente (entregar vX.Y.Z+1) para bugs funcionais. Reverta apenas por falhas de integridade do lançamento: artefatos quebrados ou mal assinados, um instalador corrompido, um erro de canal ou de tag (por exemplo uma tag de pré-lançamento publicada em latest) ou uma regressão grave sem correção rápida.

1. Congelar o canal

Pause novos lançamentos e retomadas de postpublish_only até a reversão concluir. O fluxo de lançamento recusa substituir ativos em um lançamento já publicado, então nenhuma reexecução concorrente pode sobrescrever o estado em reversão.

2. Reapontar o lançamento do GitHub

Marque o lançamento ruim como pré-lançamento, para que latest resolva para a tag anterior, e restaure as notas de lançamento anteriores se elas foram sobrescritas:

gh release edit "vX.Y.Z" --repo defai-digital/ax-code --prerelease
gh release edit "vX.Y.(Z-1)" --repo defai-digital/ax-code --latest

Se os ativos do lançamento ruim estão corrompidos ou mal assinados, apague-os também, para que nenhum instalador possa buscá-los:

gh release delete-asset "vX.Y.Z" "<asset-name>" --repo defai-digital/ax-code

Não apague o objeto do lançamento em si até os artefatos terem sido investigados; os ativos assinados e os logs do fluxo são a evidência da análise posterior.

3. Reverter o tap do Homebrew

bash .github/scripts/update-homebrew.sh enviou um commit de fórmula ao repositório compartilhado defai-digital/homebrew-tap. Reverta esse commit para que brew upgrade ax-code sirva de novo a versão anterior. O antigo repositório defai-digital/homebrew-ax-code contém apenas metadados de migração; não restaure a fórmula dele:

git -C homebrew-tap revert --no-edit <formula-commit>

Confira a convergência depois, com o job de smoke do Homebrew (.github/workflows/install-matrix-smoke.yml), contra a versão restaurada.

4. Reverter manifestos do winget

Manifestos do winget são enviados pelos mantenedores a microsoft/winget-pkgs a partir do ZIP de manifestos anexado ao lançamento do GitHub. Se a versão ruim já foi aceita, abra um PR que reverta esses arquivos de manifesto. Se ainda está em revisão, feche o PR. O envio --clobber no lançamento só substitui o ZIP anexado, nunca o pacote publicado.

5. Comunicar

Publique uma nota curta na discussão do lançamento e em qualquer canal de suporte: versões afetadas, a versão restaurada e instruções de reinstalação:

Homebrew: brew update && brew upgrade ax-code (ou brew uninstall ax-code && brew install ax-code).
Windows e outros: execute de novo o instalador fixado a partir da página do lançamento anterior; o instalador falha fechado em divergência de assinatura e inicializa um minisign fixado e conferido por SHA-256.

6. Verificar o estado restaurado

Confirme que o lançamento GitHub latest aponta para a tag anterior e que cada ativo verifica:

gh release download "vX.Y.(Z-1)" --repo defai-digital/ax-code -p '*.zip' -p '*.minisig'
minisign -V -p docs/release/ax-minisign.pub -m ax-code-darwin-arm64.zip -x ax-code-darwin-arm64.zip.minisig

Confirme que a fórmula Homebrew serve a versão restaurada e instala de forma limpa em um runner limpo (o fluxo de smoke da matriz de instalação faz isso).
Confirme que ax-code --version em uma instalação nova relata a versão restaurada e passa em ax-code doctor.

7. Análise posterior

Registre o que passou nos gates de lançamento e ainda assim saiu quebrado, e abra correções contra .github/workflows/release.yml (validação, cobertura de smoke) antes do próximo lançamento. Atualize este runbook se algum passo não funcionou como escrito.