Saltar a contenido

ADR-0005 · Variables de entorno en GCP Secret Manager como fuente única

  • Estado: aceptado
  • Decisores: hquintero
  • Fecha de la decisión: 2026-08-28

Contexto y problema

Las variables de entorno vivían en dos lugares sin nada que los mantuviera iguales: el .env editado a mano en cada servidor (runtime) y, para autenticación a GHCR, secrets de GitHub (GHCR_PAT, credenciales de una GitHub App que ya no se usaba). Los secrets de GitHub son de solo escritura —no se puede leer el valor vigente ni volver al anterior— y no hay historial de cambios. La organización ya estandarizó Secret Manager con autenticación OIDC (sin claves guardadas) en la guía CI/CD y lo aplicó en el CMS.

Opciones consideradas

  1. Un secret por entorno en GCP Secret Manager, con el .env completo como payload (elegida).
  2. Seguir con .env manual en el servidor + secrets de GitHub.
  3. Un secret de Secret Manager por variable — descartado: multiplica bindings y no aporta.

Decisión

Dos secrets, medusa-staging-env y medusa-prod-env, cada uno con el archivo .env completo de su entorno. El workflow se autentica por OIDC (Workload Identity Federation, setup a nivel de organización) y el mismo secret alimenta los dos lados de cada carril:

  • Build: solo las variables públicas que el admin inlinea (VITE_*) entran como build-args, más GIT_SHA. Nada sensible queda en la imagen.
  • Runtime: el job de deploy escribe /opt/medusa/.env desde el secret antes de deploy.sh.

El .env del servidor pasa a ser generado: editarlo por SSH no sobrevive al próximo despliegue. Para cambiar un valor: gcloud secrets versions add y redesplegar (si la variable es VITE_*, relanzar la corrida completa, porque va horneada en la imagen).

La autenticación a GHCR queda en el GITHUB_TOKEN del propio job (build y deploy): el secret GHCR_PAT y la GitHub App dejan de usarse.

Consecuencias

Positivas

  • Una sola fuente de verdad por entorno; desaparece la deriva entre servidores y builds.
  • Cada cambio queda versionado y las versiones anteriores siguen siendo legibles.
  • Ninguna credencial de larga vida guardada en GitHub ni en los servidores (el token OIDC dura minutos; el GITHUB_TOKEN dura lo que el job).

Negativas / deuda asumida

  • Cambia el hábito operativo: el que edita el .env por SSH pierde su cambio en el próximo deploy sin aviso.
  • Dependencia nueva de GCP en el camino de despliegue: sin salida a *.googleapis.com (o con Secret Manager caído) no se puede desplegar.
  • El permiso secretAccessor es por secret: crear un secret nuevo exige repetir el binding (error 403 típico del primer despliegue, documentado en la guía).
  • Queda pendiente sacar del repositorio las credenciales hardcodeadas históricas (docker-compose.yml, start.sh) y rotarlas; este ADR no las resuelve.