AkiGarage/safe-public-github-release

Release Pública Segura no GitHub

Regra Central

Proteja a confiança pública antes da velocidade. Prefira uma fotografia pública limpa, um PR/CI de branch de release, artefatos de Release do GitHub verificados, somas de verificação e aprovação explícita do mantenedor para operações irreversíveis.

Nunca publique a partir de histórico privado no mesmo lugar. Um repositório que foi criado como uma fotografia pública limpa e mantido privado apenas para polimento final pode ser tornado público após a verificação final de sanitização. Use PyPI/TestPyPI apenas quando a distribuição de pacotes Python estiver realmente no escopo.

Fluxo de Trabalho

1. Inspecione primeiro:
   • git status -sb, remotes, branch atual, tags e workflows relevantes.
   • Visibilidade do repositório público, branch padrão, estado de release/tag e ambientes do GitHub com gh.
   • Documentos existentes que mencionem caminhos de instalação, publicação, Homebrew, TestPyPI, PyPI, repositórios privados, caminhos locais ou arquivos de handoff.
2. Escopo da superfície pública:
   • Documentos públicos e metadados de pacote podem mencionar o proprietário/repositório público, nome do pacote, tags públicas e comandos oficiais de instalação.
   • Documentos públicos não devem mencionar nomes de repositórios privados, caminhos locais do usuário, HANDOFF.md, CONTINUITY.md, .local, .codex, tokens, chaves, transcrições internas brutas ou instruções exclusivas do mantenedor, a menos que reescritas como orientações para o público.
   • Prefira links relativos no README para documentos e mídias do próprio repositório. URLs absolutas do GitHub (owner/repo) são aceitáveis em notas de release, mas no README podem criar acoplamento desnecessário com o proprietário e falsos positivos em verificações de superfície pública.
3. Prepare os gates de release do GitHub:
   • Compile/teste localmente antes de mutações remotas.
   • Use release/vX.Y.Z -> PR -> CI -> merge por padrão antes de criar a tag.
   • Exija aprovação visual do README renderizado pelo GitHub de Aki antes do merge quando o README ou arquivos README localizados forem alterados.
   • Verifique os ativos da Release antes do upload: nomes de arquivo esperados, metadados de versão, soma de verificação, conteúdo do arquivo e verificação de assinatura/notarização específica da plataforma, quando aplicável.
   • Para ativos .app zip do macOS, crie o arquivo sem metadados AppleDouble ou do Finder. Prefira COPYFILE_DISABLE=1 zip ou um comando de arquivamento equivalente, e rejeite arquivos contendo __MACOSX, .DS_Store ou arquivos ._*. Esses arquivos extras podem fazer com que um aplicativo assinado falhe na verificação após a descompactação.
   • Sempre verifique o arquivo exato que será enviado, extraindo-o para um diretório temporário, verificando os metadados da versão do aplicativo/pacote e executando a verificação de assinatura/notarização relevante na carga extraída.
4. Publique a release do GitHub nesta ordem:
   • Reobtenha main, verifique se o CI mais recente está verde e confirme que o worktree local está limpo.
   • Confirme que a tag alvo e a Release do GitHub ainda não existem.
   • Crie a tag no commit verificado de main.
   • Envie a tag.
   • Crie arquivos de soma de verificação a partir dos arquivos finais de upload, usando nomes base voltados à release, não caminhos locais como dist/....
   • Crie a Release do GitHub com notas intencionais e apenas ativos intencionais.
   • Envie arquivos de soma de verificação quando úteis para o tipo de ativo e inclua a soma de verificação nas notas da Release quando ajudar os usuários a verificar o download.
5. Verifique após a publicação no GitHub:
   • A tag aponta para o commit esperado.
   • A Release do GitHub está visível na URL esperada.
   • Os ativos da Release e as somas de verificação correspondem aos arquivos verificados localmente.
   • Baixe os ativos da Release publicada em um diretório temporário e verifique-os a partir das cópias baixadas. Para arquivos com soma de verificação, execute shasum -a 256 -c <asset>.sha256; para zips de .app do macOS, descompacte o ativo baixado e execute a versão do app e as verificações codesign --verify --strict --deep no app extraído.
   • O README/documentos públicos correspondem à versão da release ativa e aos nomes dos ativos.

Subseção Opcional para PyPI / TestPyPI

Use esta subseção apenas quando a release do GitHub também publicar um pacote Python, CLI ou caminho de instalação uvx.

1. Garanta que os ambientes do GitHub existam para testpypi e pypi.
2. Mantenha pypi atrás da aprovação do mantenedor.
3. Use id-token: write e Editores Confiáveis do PyPI em vez de tokens PyPI armazenados.
4. Publique nesta ordem:
   • Workflow apenas de build a partir da tag pretendida.
   • Arquivo da Release do GitHub com SHA256SUMS e atestações de artefato.
   • Publicação no TestPyPI, seguida de instalação de teste.
   • Publicação no PyPI apenas após o TestPyPI mostrar que a versão e o teste de instalação passam.
   • Atualização da documentação para tornar o caminho de instalação ativo o primário.
5. Verifique após a publicação:
   • O JSON do PyPI/TestPyPI contém a versão esperada.
   • uvx --from <package> <command> --help funciona.
   • O reenvio da mesma versão é bloqueado pelas verificações de prontidão.
   • O README/documentos públicos correspondem ao caminho de instalação ativo.

Checklist de Fotografia Pública Apenas no GitHub

Use quando o alvo for um repositório GitHub ou release de aplicativo sem PyPI.

1. Mantenha o repositório privado até que o gate final passe. Se o alvo público for um repositório já público separado, nunca copie o histórico privado para ele; mova apenas o conteúdo da fotografia sanitizada.
2. Use uma branch de release e PR por padrão para fotografias públicas:
   • Crie ou atualize release/vX.Y.Z no repositório público.
   • Faça commit da fotografia preparada e documentos públicos nessa branch.
   • Abra um PR para main e deixe o CI executar lá.
   • Quando o README ou documentos voltados à release forem alterados, também use readme-release-sync para que a cópia pública permaneça legível, bilíngue e alinhada com o comportamento entregue.
   • Forneça a Aki links do README renderizado pelo GitHub para o PR/branch e aguarde aprovação visual explícita antes do merge. Visualizações locais de Markdown, visualizações de arquivo bruto, capturas de tela ou verificações automatizadas de links não substituem este gate.
   • Faça o merge apenas quando o CI estiver verde e a verificação de superfície pública tiver passado.
   • Faça push diretamente para main apenas quando Aki explicitamente pedir para pular o gate de PR.
3. Sanitize arquivos rastreados, não apenas a árvore de trabalho:
   • segredos, caminhos locais, nomes de mantenedores, nomes antigos de repositórios privados, arquivos de handoff, arquivos gerados, e nomes de produtos desatualizados.
   • git ls-files para arquivos .mov, .mp4 acidentais, saídas de build, caches e arquivos binários grandes.
4. Trate a mídia do README como parte da superfície pública:
   • GIFs inline são o formato de demonstração mais confiável no README do GitHub; mantenha-os abaixo do limite prático de imagem/GIF do GitHub.
   • Incorporações locais de <video> no README e links de visualização MP4 do repositório podem falhar ou abrir páginas instáveis de visualização de arquivo do GitHub.
   • Coloque demos MP4 opcionais nos ativos da Release do GitHub apenas quando realmente necessários, e remova-os, juntamente com referências nas notas de release, se o produto não precisar deles.
5. Antes de criar a tag ou a Release do GitHub, reobtenha:
   • Estado do merge do PR e status do CI mais recente em main após o merge
   • git status -sb, git log --oneline -1, git tag --list e ativos de release atuais
   • README e caminhos de imagem referenciados através da API de conteúdo do GitHub quando o repositório já é público
   • Conteúdo do arquivo e resultados de verificação do ativo extraído para cada upload binário
6. Antes de alterar a visibilidade, reobtenha:
   • gh repo view ... --json visibility,isPrivate,url,defaultBranchRef
   • Status mais recente do Actions para a branch padrão
   • Ativos da Release e notas de release
   • README e caminhos de imagem referenciados através da API de conteúdo do GitHub
7. Altere a visibilidade apenas depois que Aki disser explicitamente para publicar; em seguida, verifique visibility=PUBLIC, disponibilidade da URL pública do README, ativos da Release e um worktree local limpo.

Fluxo de Fotografia Limpa para Repositório Público

Use este fluxo quando um repositório privado/interno alimenta um repositório público separado.

1. Conclua e valide o recurso no repositório privado.
2. Crie uma pasta de fotografia temporária a partir de uma lista de permissões de arquivos públicos.
3. Aplique a nomenclatura pública e remova superfícies exclusivamente privadas na fotografia.
4. Sanitize a fotografia em busca de segredos, caminhos privados, arquivos de handoff, nomes de produtos antigos, arquivos gerados e arquivos acidentais grandes.
5. Copie a fotografia sanitizada para a árvore de trabalho do repositório público.
6. Crie ou mude para release/vX.Y.Z.
7. Atualize o README público, README localizado, changelog, metadados de versão, rascunho de notas de release e referências de mídia do README nessa branch.
8. Inspecione git diff, links de mídia do README, paridade bilíngue, redação desatualizada e resultados da verificação de superfície pública.
9. Execute as verificações locais relevantes de build/teste/pacote.
10. Faça commit das alterações de preparo da release em release/vX.Y.Z e envie a branch.
11. Abra um PR para main; não crie tag ou Release do GitHub ainda.
12. Aguarde o CI, corrija falhas na branch de release e reexecute as verificações.
13. Envie a Aki as URLs do README renderizado pelo GitHub para README.md e quaisquer arquivos README localizados no PR/branch. Aguarde aprovação visual explícita de que o README parece correto no GitHub.
14. Faça o merge do PR apenas depois que o CI, os gates de sanitização e a aprovação visual do README renderizado pelo GitHub de Aki passarem.
15. Reobtenha main e verifique se o commit mesclado está limpo e verde.
16. Pare para aprovação de Aki antes de criar vX.Y.Z, enviar ativos ou criar/publicar a Release do GitHub.

Fluxo para Projeto sem Repositório Público

Use esta rota quando o projeto nunca teve um repositório público.

1. Não torne o repositório de trabalho privado/interno público.
2. Crie um novo repositório de publicação limpo e mantenha-o privado inicialmente.
3. Inicialize-o apenas a partir da fotografia pública sanitizada, não do histórico privado.
4. Use nomes de produtos, metadados de pacote, arquivos README, licença, changelog, rascunho de notas de release, capturas de tela/GIFs e workflows voltados ao público desde o início.
5. Execute a mesma sanitização de segredos/caminhos privados/arquivos grandes/superfície pública nos arquivos rastreados.
6. Use release/vX.Y.Z -> PR -> CI -> aprovação visual do README renderizado pelo GitHub de Aki -> merge, mesmo que o repositório ainda seja privado.
7. Crie a tag pretendida e o rascunho da Release do GitHub enquanto o repositório ainda estiver privado, quando possível, e verifique ativos/somas de verificação lá.
8. Pare para aprovação de Aki antes de alterar a visibilidade.
9. Altere a visibilidade para público apenas após a sanitização final, CI verde, ativos de release intencionais e aprovação explícita de Aki.
10. Após alterar a visibilidade, reobtenha e verifique a disponibilidade do README público, ativos da Release, tags, status mais recente do Actions e worktree local limpo.

Lições Importantes

• As definições de workflow do GitHub Actions são obtidas a partir da ref usada para despachar o workflow. Se uma tag foi criada antes de uma nova entrada ou guarda de workflow ser adicionada, o despacho a partir dessa tag antiga não saberá sobre a nova entrada.
• Releases futuras devem implementar guards de release antes de criar a tag. Em seguida, despache a partir dessa tag com as entradas guardadas.
• Se uma tag histórica única for anterior à guarda, não adivinhe. Execute verificações de prontidão locais, comprove o TestPyPI primeiro, verifique artefatos/atestações e documente a exceção.
• A higiene dos ativos da Release é importante: após uploads exploratórios, a Release pública final deve conter apenas artefatos intencionais. Exclua ativos indesejados e remova suas linhas SHA ou menções nas notas de release antes de publicar.

Runbook Detalhado

Leia references/pypi-trusted-release-runbook.md para o checklist passo a passo, padrões de comando e padrões de auditoria de documentos públicos.