Runbook de recuperação de versão
Procedimentos de recuperação para restaurar o repositório quando uma sequência de versão falha no meio do processo, com diagnósticos etapa por etapa.
Este runbook restaura ahmed-g-gad/apothem a um estado funcional quando uma
sequência de versão de limpeza-total-no-local falha no meio do processo. O
repositório público não é excluído nem recriado durante a versão. A recuperação
depende da tag de segurança de histórico específica da versão, do clone local do
mantenedor e do estado dos gerenciadores de pacotes a jusante.
1. Taxonomia de etapas
| Etapa | Ação | Modo de falha | Caminho de recuperação |
|---|---|---|---|
| 1 | Capturar e enviar a tag de segurança de histórico | A tag está ausente, não assinada ou aponta para o grafo errado | Recriar a tag a partir do ponto de merge pré-squash antes de mover main |
| 2 | Verificar CI, fortaleza de auditoria, estado dos pacotes e changelog | Qualquer portão falha | Pare; conserte localmente; não mova main |
| 3 | Mover main para o único commit de versão assinado | O force-with-lease falha, o commit não está assinado ou a mensagem do commit está errada | Redefina main local para o commit assinado pretendido e tente novamente com um lease novo |
| 4 | Publicar GitHub Release, Pages, npm e metadados | Um publicador ou superfície de verificação falha | Mantenha o commit de versão; execute novamente apenas o publicador que falhou depois de registrar a falha |
Cada ação de recuperação é idempotente. Executá-la em um estado limpo não faz nada; executá-la em um estado parcial restaura a condição esperada pós-etapa.
2. Recuperação da tag de segurança
Verifique a tag de segurança antes de qualquer reescrita de histórico:
git fetch origin --tags
git show --summary --show-signature <history-safety-tag>
git merge-base --is-ancestor origin/main <history-safety-tag>Esperado: a tag existe, a verificação de assinatura é bem-sucedida quando a tag
está assinada, e o grafo completo pré-squash é alcançável a partir da tag. Se a
tag estiver ausente localmente, mas presente no remoto, busque-a. Se ela estiver
ausente no remoto, interrompa a versão e recrie-a antes de tocar em main:
git tag -s <history-safety-tag> <pre-squash-commit>
git push origin <history-safety-tag>3. Recuperação do branch principal
Diagnostique o estado de main público:
gh api repos/ahmed-g-gad/apothem/commits/main \
--jq '.sha, .commit.message, .commit.verification.verified, .commit.verification.reason'Esperado após a migração: a mensagem é exatamente
release: Apothem <release-version> e verification.verified é true.
Se o push com force-with-lease falhou antes de alterar o GitHub, deixe o remoto como está, busque-o, reconstrua o commit de versão assinado localmente e tente novamente somente depois que o lease corresponder:
git fetch origin main
git push --force-with-lease=main:<expected-remote-sha> origin mainSe o push aterrissou com um commit não assinado ou não verificado, conserte a configuração de assinatura local, recrie o commit de versão a partir da mesma árvore e faça force-push novamente com um lease. Não exclua a tag de segurança.
4. Recuperação de publicadores
Cada publicador é repetido de forma independente depois que o commit de versão do GitHub é verificado:
| Superfície | Diagnóstico | Recuperação |
|---|---|---|
| GitHub Release | gh release view <release-tag> --json tagName,isDraft,isPrerelease,assets | Exclua apenas um rascunho malformado; caso contrário, envie os recursos ausentes com gh release upload --clobber |
| Tag de versão | git ls-remote origin refs/tags/<release-tag> e git tag -v <release-tag> | Re-tague a partir do mesmo SHA com -a -s se a tag estiver ausente ou não assinada; nunca reutilize um nome de tag para um commit diferente |
| npm | npm view @ahmed-g-gad/apothem version e npx @ahmed-g-gad/apothem@<version> --version | Execute novamente publish-npm.yml para <release-tag> depois de confirmar o npm Trusted Publishing para @ahmed-g-gad/apothem |
| Pages | gh run list --workflow=publish-static-site.yml --limit=1 e curl -sSI https://apothem.ahmedgad.com/ | Execute novamente publish-static-site.yml; verifique se o CNAME ainda resolve para ahmed-g-gad.github.io |
| Metadados do GitHub | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | Aplique correção em descrição, página inicial e tópicos no local; não recrie o repositório |
5. Rollback
O rollback é o último recurso. Prefira primeiro a recuperação direcionada de
publicadores. Se o único commit de versão precisar ser revertido, restaure
main a partir da tag de segurança:
git fetch origin --tags
git switch main
git reset --hard <history-safety-tag>
git push --force-with-lease origin mainApós o rollback, execute o CI novamente, reaplique a proteção de branch se o GitHub relatar desvio, e registre o rollback como um incidente que bloqueia a versão. Mantenha a tag de versão apenas se os artefatos da versão permanecerem válidos; caso contrário, exclua a versão e a tag malformadas antes de tentar novamente.
6. Referências cruzadas
- Configuração do Pages:
site/content/docs/runbooks/pages-enablement.mdx. - Procedimento de versão:
site/content/docs/runbooks/release-cycle.mdx. - Receitas de empacotamento:
packaging/README.md. - Âncora de recuperação: a tag de segurança de histórico específica da versão.