Go CLI Release Kit

Para quién es

Has escrito una herramienta de línea de comandos en Go y la gente quiere instalarla. La documentación de GoReleaser es buena y gratuita, y un .goreleaser.yaml que funcione lleva una tarde. Lo demás lleva más tiempo: un comando de versión que imprima el commit real, un install.sh que no te dé vergüenza pasar por curl, una estrategia de checksums, CI que haga la release al crear un tag, una fórmula de Homebrew que no lleve un hash vacío.

Este kit es un esqueleto de repositorio que copias y renombras. Todo lo que contiene se ha ejecutado en un container limpio, y la salida va incluida para que veas qué significaba "funciona".

Qué contiene

• .goreleaser.yaml para Linux, macOS y Windows en amd64 y arm64. Builds estáticos, -trimpath, versión, commit y fecha del commit inyectados, un archivo de checksums y un changelog agrupado por prefijo de Conventional Commits.
• install.sh, un instalador que verifica, con opción de fijar la versión y comprobación opcional de firma GPG.
• Un verificador de reproducibilidad que compila dos veces en entornos limpios separados y compara los resultados.
• Un script de subida de versión que lee tus commits y elige el siguiente tag.
• Generadores de Homebrew y Scoop que construyen la fórmula y el manifiesto a partir de tus checksums reales.
• Plantillas de CI para GitHub Actions y GitLab: lint, tests con el detector de race conditions y release al crear un tag.
• Un CLI de ejemplo solo con la biblioteca estándar, con tests, y una guía paso a paso de la primera release con una checklist.

Lo que el instalador rechaza

Un instalador que descarga un binario y lo ejecuta es un buen sitio para ser estricto. En las pruebas, install.sh se detiene, no instala nada y deja intacta cualquier instalación existente cuando:

• el archivo no coincide con su SHA-256 (alteramos uno para comprobarlo),
• el archivo de checksums no tiene entrada para el archivo, o la tiene dos veces,
• falta el archivo de checksums, o la release no existe,
• la URL es http sin cifrar,
• la cadena de versión está mal formada o vacía,
• la plataforma no es una de las que compilaste. La detección de arquitectura se prueba con un uname falso, incluidos armv7, i686, riscv64, FreeBSD y shells de Windows.

Con una clave GPG configurada, también se rechazan una clave equivocada, un archivo de checksums modificado, una firma ausente y un archivo de clave ausente, de modo que la firma protege el propio archivo de checksums.

Builds reproducibles, comprobados

repro-check.sh clona el repositorio dos veces, en directorios distintos, con un entorno vacío y una caché de Go nueva, con dos segundos de diferencia, y compara los binarios, los archivos y el archivo de checksums. En el proyecto de ejemplo, 13 de 13 archivos fueron idénticos. Dos errores deliberados, incrustar la hora de compilación en los ldflags y omitir -trimpath, hicieron que todos los archivos fueran distintos. Es decir, la comprobación falla cuando debe fallar.

Cifras

Los flags del linker -s -w reducen el tamaño de los archivos a la mitad aproximadamente en este ejemplo: el archivo de Linux amd64 pesa 770,338 bytes con ellos y 1,531,872 sin ellos. Los tiempos de compilación dependen mucho del estado de la caché; el README los lista con su configuración.

Cómo se probó

183 comprobaciones automáticas en un container Linux limpio con GoReleaser v2.20.0, más una pasada de build y tests del ejemplo con Go 1.22. Las comprobaciones incluyen una release snapshot que produce seis archivos, la ejecución del binario de Linux generado y la comparación de la salida de su --version, la verificación del archivo de checksums contra los archivos, un build con tag para el changelog, unos 25 casos para el script de subida de versión sobre repositorios git temporales y actionlint sobre los workflows de GitHub.

Requisitos

Go, git y GoReleaser OSS. Docker, si quieres ejecutar el banco de pruebas.

Preguntas frecuentes

¿Por qué no usar directamente la documentación de GoReleaser?

Puedes. La documentación cubre GoReleaser. Este kit cubre lo que lo rodea y comprueba que las piezas funcionan juntas.

¿Soporta GitLab?

Sí. Hay una plantilla de GitLab CI, con notas sobre la configuración del token.

¿Puedo usar mi propio module path y mis propios nombres?

Sí. La guía de la primera release lista todos los sitios donde hay que renombrar.

Licencia

Úsalo en tus propios proyectos. El archivo LICENSE del esqueleto es tuyo para reemplazarlo. Por favor, no revendas el kit.

Historial de cambios

• 0.1.0: primera versión.

Leer más

• Verify a downloaded binary: checksums, GPG, minisign, cosign (en inglés)
• Reproducible Go builds: build twice, compare the hashes (en inglés)
• A GoReleaser v2 config for a small Go CLI, line by line (en inglés)
• What a curl | sh installer for a Go binary should refuse (en inglés)

Obtener

Comprar en Polar: $24

Polar, como merchant of record, se ocupa del pago, los impuestos y las facturas. Al terminar la compra recibes un enlace de descarga.