AkiGarage/safe-public-github-release

Publicación pública segura en GitHub

Regla principal

Protege la confianza pública antes que la velocidad. Prefiere una instantánea pública limpia, un PR/CI de rama de lanzamiento, artefactos de Release de GitHub verificados, sumas de verificación y la aprobación explícita del mantenedor para operaciones irreversibles.

Nunca publiques desde el historial privado en su lugar. Un repositorio que se creó como una instantánea pública limpia y se mantuvo privado solo para los retoques finales puede volverse público después de la compuerta de limpieza final. Usa PyPI/TestPyPI solo cuando la distribución del paquete Python esté realmente en el alcance.

Flujo de trabajo

1. Inspecciona primero:
   • git status -sb, remotos, rama actual, etiquetas y flujos de trabajo relevantes.
   • Visibilidad del repositorio público, rama predeterminada, estado de release/etiqueta y entornos de GitHub con gh.
   • Documentos existentes que mencionen rutas de instalación, publicación, Homebrew, TestPyPI, PyPI, repositorios privados, rutas locales o archivos de traspaso.
2. Delimita la superficie pública:
   • Los documentos públicos y los metadatos del paquete pueden mencionar el propietario/repositorio público, el nombre del paquete, las etiquetas públicas y los comandos de instalación oficiales.
   • Los documentos públicos no deben mencionar nombres de repositorios privados, rutas de inicio locales, HANDOFF.md, CONTINUITY.md, .local, .codex, tokens, claves, transcripciones internas sin procesar o instrucciones solo para mantenedores a menos que se reescriban como orientación para el público.
   • Prefiere enlaces relativos en README para documentos y medios locales del repositorio. Las URL absolutas de propietario/repositorio de GitHub están bien en las notas de la versión, pero en el README pueden crear un acoplamiento evitable con el propietario y falsos positivos en las comprobaciones de limpieza de la superficie pública.
3. Prepara las compuertas de lanzamiento de GitHub:
   • Compila/prueba localmente antes de la mutación remota.
   • Usa release/vX.Y.Z -> PR -> CI -> fusión por defecto antes de etiquetar.
   • Requiere la aprobación visual de Aki del README renderizado en GitHub antes de fusionar cuando el README o los archivos README localizados cambien.
   • Verifica los activos de Release antes de la subida: nombres de archivo esperados, metadatos de versión, suma de verificación, contenido del archivo y comprobaciones de firma/notarización específicas de la plataforma cuando corresponda.
   • Para activos .app zip de macOS, compila el archivo sin metadatos AppleDouble o de Finder. Prefiere COPYFILE_DISABLE=1 zip o un comando de archivo equivalente, y rechaza archivos que contengan __MACOSX, .DS_Store o archivos ._*. Esos archivos adicionales pueden hacer que una aplicación firmada falle en la verificación después de descomprimir.
   • Siempre verifica el archivo exacto que se subirá extrayéndolo a un directorio temporal, verificando los metadatos de la versión de la aplicación/paquete y ejecutando la verificación de firma/notarización correspondiente en la carga útil extraída.
4. Publica la release de GitHub en este orden:
   • Vuelve a obtener main, verifica que la última CI esté en verde y confirma que el árbol de trabajo local esté limpio.
   • Confirma que la etiqueta de destino y la Release de GitHub no existan ya.
   • Crea la etiqueta en el commit verificado de main.
   • Empuja la etiqueta.
   • Crea archivos de suma de verificación a partir de los archivos de subida finales usando nombres base orientados a la release, no rutas locales como dist/....
   • Crea la Release de GitHub con notas intencionales y solo activos intencionales.
   • Sube archivos de suma de verificación cuando sean útiles para el tipo de activo e incluye la suma de verificación en las notas de la Release cuando ayude a los usuarios a verificar la descarga.
5. Verifica después de la publicación en GitHub:
   • La etiqueta apunta al commit esperado.
   • La Release de GitHub es visible en la URL esperada.
   • Los activos de Release y las sumas de verificación coinciden con los archivos verificados localmente.
   • Descarga los activos de Release publicados en un directorio temporal y verifícalos a partir de las copias descargadas. Para archivos respaldados por suma de verificación, ejecuta shasum -a 256 -c <activo>.sha256; para zips .app de macOS, descomprime el activo descargado y ejecuta la versión de la aplicación y las comprobaciones de codesign --verify --strict --deep en la aplicación extraída.
   • El README/documentos públicos coinciden con la versión activa de la release y los nombres de los activos.

Subsección opcional de PyPI / TestPyPI

Usa esta subsección solo cuando la release de GitHub también publique un paquete Python, CLI o ruta de instalación uvx.

1. Asegúrate de que existan entornos de GitHub para testpypi y pypi.
2. Mantén pypi detrás de la aprobación del mantenedor.
3. Usa id-token: write y Editores de Confianza de PyPI en lugar de tokens de PyPI almacenados.
4. Publica en este orden:
   • Flujo de trabajo de solo compilación desde la etiqueta prevista.
   • Archivo de Release de GitHub con SHA256SUMS y atestaciones de artefacto.
   • Publicación en TestPyPI, luego prueba de instalación.
   • Publicación en PyPI solo después de que TestPyPI muestre la versión y la prueba de instalación pase.
   • Actualización de documentos para que la ruta de instalación activa sea la principal.
5. Verifica después de publicar:
   • El JSON de PyPI/TestPyPI contiene la versión esperada.
   • uvx --from <paquete> <comando> --help funciona.
   • La re-subida de la misma versión está bloqueada por las comprobaciones de preparación.
   • El README/documentos públicos coinciden con la ruta de instalación activa.

Lista de verificación de instantánea pública solo en GitHub

Usa esto cuando el destino sea un repositorio de GitHub o una release de aplicación sin PyPI.

1. Mantén el repositorio privado hasta que la compuerta final pase. Si el destino público es un repositorio separado ya público, nunca copies el historial privado en él; mueve solo el contenido de la instantánea limpiada.
2. Usa una rama de lanzamiento y un PR por defecto para instantáneas públicas:
   • Crea o actualiza release/vX.Y.Z en el repositorio público.
   • Confirma la instantánea preparada y los documentos públicos en esa rama.
   • Abre un PR en main y deja que la CI se ejecute allí.
   • Cuando el README o los documentos orientados a la release cambien, usa también readme-release-sync para que la copia pública se mantenga legible, bilingüe y alineada con el comportamiento enviado.
   • Dale a Aki enlaces de README renderizados por GitHub para el PR/rama y espera la aprobación visual explícita antes de fusionar. Las vistas previas locales de Markdown, las vistas de archivos sin procesar, las capturas de pantalla o las comprobaciones automatizadas de enlaces no reemplazan esta compuerta.
   • Fusiona solo después de que la CI esté en verde y la limpieza de la superficie pública haya pasado.
   • Empuja directamente a main solo cuando Aki pida explícitamente saltarse la compuerta del PR.
3. Limpia los archivos rastreados, no solo el árbol de trabajo:
   • secretos, rutas locales, nombres de mantenedores, nombres de repositorios privados antiguos, archivos de traspaso, archivos generados y nombres de productos obsoletos.
   • git ls-files para archivos .mov, .mp4, salidas de compilación, cachés y archivos binarios grandes.
4. Trata los medios del README como parte de la superficie pública:
   • Los GIF incrustados son el formato de demostración más fiable para README de GitHub; mantenlos por debajo del límite práctico de imagen/GIF de GitHub.
   • Las inserciones de <video> en README local y los enlaces de vista previa MP4 locales al repositorio pueden fallar o abrir páginas de vista previa de archivos inestables de GitHub.
   • Pon demostraciones MP4 opcionales en los activos de Release de GitHub solo cuando sean realmente necesarias, y elimínalas, junto con las referencias en las notas de la release, si el producto no las necesita.
5. Antes de crear la etiqueta o la Release de GitHub, vuelve a obtener:
   • Estado de fusión del PR y último estado de CI en main después de la fusión.
   • git status -sb, git log --oneline -1, git tag --list y activos de release actuales.
   • README y rutas de imagen referenciadas a través de la API de contenidos de GitHub cuando el repositorio ya sea público.
   • Contenido del archivo y resultados de verificación de activos extraídos para cada subida binaria.
6. Antes de cambiar la visibilidad, vuelve a obtener:
   • gh repo view ... --json visibility,isPrivate,url,defaultBranchRef.
   • Último estado de Actions para la rama predeterminada.
   • Activos de Release y notas de release.
   • README y rutas de imagen referenciadas a través de la API de contenidos de GitHub.
7. Cambia la visibilidad solo después de que Aki diga explícitamente que publique, luego verifica visibility=PUBLIC, disponibilidad de URL de README público, activos de Release y un árbol de trabajo local limpio.

Flujo de instantánea limpia a repositorio público

Usa este flujo cuando un repositorio privado/interno alimente un repositorio público separado.

1. Termina y valida la funcionalidad en el repositorio privado.
2. Crea una carpeta de instantánea temporal a partir de una lista blanca de archivos públicos.
3. Aplica nombres públicos y elimina superficies solo privadas en la instantánea.
4. Limpia la instantánea en busca de secretos, rutas privadas, archivos de traspaso, nombres de productos antiguos, archivos generados y archivos grandes accidentales.
5. Copia la instantánea limpiada en el árbol de trabajo del repositorio público.
6. Crea o cambia a release/vX.Y.Z.
7. Actualiza el README público, README localizado, changelog, metadatos de versión, borrador de notas de release y referencias a medios del README en esa rama.
8. Inspecciona git diff, enlaces a medios del README, paridad bilingüe, redacción obsoleta y resultados de escaneo de superficie pública.
9. Ejecuta las comprobaciones locales relevantes de compilación/prueba/empaquetado.
10. Confirma los cambios de preparación de release en release/vX.Y.Z y empuja la rama.
11. Abre un PR en main; no etiquetes ni crees una Release de GitHub todavía.
12. Espera a la CI, corrige fallos en la rama de release y vuelve a ejecutar comprobaciones.
13. Envía a Aki las URL de README renderizadas por GitHub para README.md y cualquier archivo README localizado en el PR/rama. Espera la aprobación visual explícita de que el README se vea correcto en GitHub.
14. Fusiona el PR solo después de que la CI, las compuertas de limpieza y la aprobación visual del README renderizado por GitHub de Aki hayan pasado.
15. Vuelve a obtener main y verifica que el commit fusionado esté limpio y en verde.
16. Detente para la aprobación de Aki antes de crear vX.Y.Z, subir activos o crear/publicar la Release de GitHub.

Flujo sin repositorio público todavía

Usa esta ruta cuando el proyecto nunca ha tenido un repositorio público.

1. No conviertas el repositorio de trabajo privado/interno en público.
2. Crea un nuevo repositorio de publicación limpio y mantenlo privado al principio.
3. Inicialízalo solo a partir de la instantánea pública limpiada, no del historial privado.
4. Usa nombres de productos orientados al público, metadatos de paquete, archivos README, licencia, changelog, borrador de notas de release, capturas de pantalla/GIF y flujos de trabajo desde el principio.
5. Ejecuta la misma limpieza de secretos/ruta privada/archivo grande/superficie pública en los archivos rastreados.
6. Usa release/vX.Y.Z -> PR -> CI -> aprobación visual del README renderizado por GitHub de Aki -> fusión, aunque el repositorio siga siendo privado.
7. Crea la etiqueta y el borrador de Release de GitHub previstos mientras el repositorio aún sea privado cuando sea posible, y verifica los activos/comprobaciones allí.
8. Detente para la aprobación de Aki antes de cambiar la visibilidad.
9. Cambia la visibilidad a público solo después de la limpieza final, CI en verde, activos de release intencionales y la aprobación explícita de Aki.
10. Después del cambio de visibilidad, vuelve a obtener y verifica la disponibilidad del README público, los activos de Release, las etiquetas, el último estado de Actions y el árbol de trabajo local limpio.

Lecciones importantes

• Las definiciones de flujos de trabajo de GitHub Actions se toman de la ref utilizada para despachar el flujo de trabajo. Si se creó una etiqueta antes de agregar una nueva entrada o compuerta de flujo de trabajo, despachar desde esa etiqueta antigua no conocerá la nueva entrada.
• Las releases futuras deben colocar las compuertas de release antes de crear la etiqueta. Luego despacha desde esa etiqueta con las entradas protegidas.
• Si una etiqueta histórica única es anterior a la compuerta, no adivines. Ejecuta comprobaciones de preparación locales, prueba TestPyPI primero, verifica artefactos/atestaciones y documenta la excepción.
• La higiene de los activos de Release es importante: después de las subidas exploratorias, la Release pública final debe contener solo artefactos intencionales. Elimina los activos no deseados y sus líneas SHA o menciones en las notas de release antes de publicar.

Manual detallado

Lee references/pypi-trusted-release-runbook.md para la lista de verificación paso a paso, los patrones de comando y los patrones de auditoría de documentos públicos.