Cuando trabajas en Go, la gestión de dependencias se apoya en un sistema de proxies para asegurar velocidad y consistencia. Por defecto, Go utiliza el GOPROXY público (proxy.golang.org), que actúa como un caché global de módulos. Cuando ejecutas go get o go mod tidy, Go no va directamente a GitHub o GitLab; primero le pregunta al proxy. Esto es eficiente porque el proxy ya tiene descargados y verificados los módulos, y además audita que el contenido no haya sido manipulado.
Sin embargo, este modelo rompe cuando necesitas usar código privado (como un repositorio en un GitLab interno o un GitHub Enterprise). Si intentas descargar un módulo privado usando el proxy público, ocurrirán dos problemas: primero, el proxy devolverá un error 404 Not Found porque no tiene acceso a tu red privada; segundo, y más grave, estarás enviando los nombres de tus repositorios privados a los servidores de Google, lo cual es un riesgo de seguridad y fuga de metadatos.
Para solucionar esto, utilizamos la variable GOPRIVATE. Esta variable es una “navaja suiza” que define un patrón (como github.com/mi-empresa/*) que Go debe tratar como privado. Al definir un módulo en GOPRIVATE, Go realiza dos acciones automáticas: configura GONOPROXY (para que no use el proxy público para esos módulos) y configura GONOSUMDB (para que no intente verificar el checksum en la base de datos pública de Go, ya que tus módulos privados no están registrados allí).
Si configuras mal esto, lo más común es que go mod tidy falle con errores de red o errores de “checksum mismatch” que son muy difíciles de rastrear, ya que Go estará intentando validar la integridad de un módulo privado contra un servidor público que no conoce ese módulo.
#!/bin/bash # Simulación de configuración de entorno para un desarrollador # en un entorno corporativo con módulos privados. # 1. Definir el proxy principal y el fallback. # 'direct' le dice a Go que, si el proxy falla o no tiene el módulo, # intente descargarlo directamente desde la fuente (Git, etc.). export GOPROXY="https://proxy.golang.org,direct" # 2. Definir qué dominios son estrictamente privados. # Esto evita que los nombres de nuestros repos internos se filtren # al proxy público de Google y evita errores de checksum. export GOPRIVATE="github.com/mi-empresa/*,gitlab.mi-corporacion.com" # 3. Configurar la autenticación para repositorios privados via HTTPS. # En lugar de escribir la contraseña en la terminal, se usa un archivo .netrc. # El archivo ~/.netrc debería verse así: # machine gitlab.mi-corporacion.com # login mi_usuario_de_git # password mi_token_de_acceso_personal echo "Configuración de entorno aplicada para módulos mixtos." echo "Proxy: $GOPROXY" echo "Privados: $GOPRIVATE"
Análisis de la configuración
En el script anterior, la línea export GOPROXY="https://proxy.golang.org,direct" establece una jerarquía. Primero intentamos usar el proxy público para ganar velocidad y seguridad en módulos estándar (como github.com/google/uuid). Si el proxy no tiene el módulo, el flag direct permite que Go recurra a tu configuración local de Git para bajarlo.
La instrucción export GOPRIVATE="github.com/mi-empresa/*,gitlab.mi-corporacion.com" es el núcleo de la privacidad. Al usar el comodín *, estamos cubriendo todos los subpaquetes de nuestra organización. Esto es crucial porque, internamente, Go marcará todo lo que coincida con github.com/mi-empresa/ como algo que debe ignorar la base de datos de sumas de verificación (GOSUMDB). Sin esto, aunque descargues el código correctamente mediante SSH, el comando fallará porque Go intentará verificar que el hash del módulo coincide con el registrado en sum.golang.org, y ese servidor obviamente no tiene registro de tu código privado.
Finalmente, para la autenticación, si trabajas con servidores HTTPS internos, la forma más profesional es el uso de .netrc. Go utiliza las credenciales de este archivo para realizar las peticiones de descarga sin intervención manual.
El error frecuente
Un error muy común ocurre cuando el desarrollador intenta usar GOPRIVATE pero tiene configurado Git para usar SSH en lugar de HTTPS para repositorios de GitHub, pero no ha configurado el “insteadOf”.
Si tu GOPRIVATE incluye github.com/mi-empresa, Go intentará usar HTTPS para descargar ese módulo. Si el servidor requiere autenticación y no tienes un .netrc configurado, la descarga fallará. Muchos desarrolladores intentan arreglarlo configurando GONOSUMDB manualmente, pero el problema real es que el cliente de Git no sabe cómo autenticarse en la petición HTTPS que lanza Go.
Para solucionarlo, debes forzar a Git a usar SSH siempre que la URL parezca HTTPS para esos dominios:
git config --global url."git@github.com:".insteadOf "https://github.com/"
N° 103