Guía

Cómo desplegar una aplicación que usa una dependencia Git privada

Una dependencia privada necesita credenciales durante la compilación, pero estas no pertenecen al código fuente. Una clave de despliegue conecta el repositorio sin exponer tu clave SSH personal.

Equipo de Adios20 de agosto de 20266 min de lectura

Cuando falla una dependencia privada en una compilación en la nube, el código puede estar bien. La compilación simplemente no tiene una forma segura de demostrar que puede leer el repositorio.

Lo que el error realmente dice

Un comando local de Git puede pedir un nombre de usuario, una contraseña o una clave SSH. Una compilación remota no puede detenerse a esperar esa respuesta. Cuando Go, npm, pip u otra herramienta accede a un repositorio privado por HTTPS sin credenciales, Git informa de que las preguntas interactivas del terminal están desactivadas.

Ese mensaje no suele significar que el nombre del paquete sea incorrecto. Significa que la compilación necesita una identidad no interactiva con permiso para leer el repositorio.

A typical private Go module failure

fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled

Usa una clave de despliegue, no tu clave personal

Una clave SSH tiene dos partes. La pública se puede registrar en Bitbucket, GitHub o GitLab. La privada demuestra que la compilación posee esa clave pública. Solo la parte privada necesita almacenamiento de secretos.

Crea una clave dedicada a esta tarea. Si alguna vez queda expuesta, puedes revocarla sin interrumpir tu acceso personal a Git ni la cuenta de otro desarrollador.

—Dale acceso de solo lectura, salvo que la compilación realmente haga push de código.
—Limítala a los repositorios que necesita el grafo de dependencias.
—No reutilices la clave SSH personal de un desarrollador.
—Nunca guardes en un commit la clave privada ni una URL de repositorio que contenga credenciales.

ssh-keygen -t ed25519 -C "adios-build" -f ~/.ssh/adios-build -N ""

Coloca cada parte en el lugar correcto

Añade el contenido de adios-build.pub como clave de acceso de solo lectura en el repositorio privado. Después sube adios-build, sin el sufijo .pub, al equipo de Adios propietario de la aplicación.

El nombre del secreto es una etiqueta que eliges. El ejemplo usa BITBUCKET_DEPLOY_KEY porque deja claro su propósito en el manifiesto y la lista de secretos.

cat ~/.ssh/adios-build.pub

adios secrets set BITBUCKET_DEPLOY_KEY \
  --from-file ~/.ssh/adios-build

Indica a Adios y Go dónde está el código fuente privado

El manifiesto conecta la compilación con la clave guardada mediante build.ssh. En proyectos Go, GOPRIVATE también indica a la herramienta de módulos qué rutas de importación deben evitar el proxy público y la base de datos de sumas de comprobación.

Puedes conservar la ruta habitual del módulo con formato HTTPS en go.mod. En los hosts Git compatibles, el proceso de trabajo de compilación de Adios prepara el acceso SSH sin añadir la clave a la aplicación en ejecución.

build:
  ssh:
    - default=secret://BITBUCKET_DEPLOY_KEY
  env:
    GOPRIVATE: "bitbucket.org/your-workspace/*"

build_cmd: go build -o app ./cmd/api

Reintenta la compilación y lee el siguiente error

Ejecuta de nuevo adios up cuando ambas partes de la clave y el manifiesto estén configurados. Si se descarga la dependencia privada, la conexión está completa. Adios resuelve el secreto dentro del proceso de trabajo y elimina el archivo temporal de la clave al terminar la compilación.

Si sigue fallando, el nuevo mensaje suele señalar uno de los lados de la conexión. Permission denied significa que el proveedor no aceptó la clave pública. Un secreto ausente significa que la clave privada está guardada con otro nombre o en otro equipo. Si Go contacta con su proxy público, GOPRIVATE no cubre la ruta completa de importación del módulo.

Rota el acceso sin cambiar el código de la aplicación

Una referencia a un secreto mantiene las credenciales fuera del repositorio, por lo que la rotación no requiere editar go.mod ni archivos de código fuente. Crea un par de reemplazo, autoriza su clave pública y actualiza BITBUCKET_DEPLOY_KEY con adios secrets set.

Ejecuta una compilación correcta con la nueva clave antes de retirar la pública anterior. Ese breve solapamiento evita una caída innecesaria y deja una sola credencial activa de compilación cuando termina la rotación.

Todos los artículos