Variables y secrets

Lizard almacena la configuración como secrets. Vienen en dos alcances: servicio (el predeterminado) y proyecto (--global), y se combinan en el entorno de tu app con un orden de precedencia definido. No hay un alcance global a nivel de workspace.

Configurar variables

lizard secrets set es variádico: configura una o varias a la vez. De forma predeterminada escribe en el servicio vinculado:

lizard secrets set DATABASE_URL=postgres://… LOG_LEVEL=info
lizard secrets set API_KEY=sk_live_… --service api

Añade --global para escribir en el alcance de proyecto (todos los servicios del proyecto lo verán):

lizard secrets set NODE_ENV=production --global

Listar, eliminar, importar

lizard secrets list                       # current scope
lizard secrets list --show                # reveal values
lizard secrets delete OLD_KEY ANOTHER_KEY # variadic; add -y in scripts
cat .env | lizard secrets import          # KEY=value lines from stdin

secrets import lee líneas simples KEY=value y conserva las comillas como parte del valor. secrets delete pide confirmación; pasa -y cuando se ejecuta fuera de una terminal.

Consulta la referencia de comandos de lizard secrets para ver todas las opciones.

Alcances

Usa por defecto el alcance de servicio. Un servicio comprometido puede leer su propio entorno; un alcance más amplio significa más credenciales expuestas sin necesidad. Reserva --global para valores no secretos y demostrablemente públicos como LOG_LEVEL, NODE_ENV, feature flags o un frontend SENTRY_DSN. Si no estás seguro de si un valor es un secret, trátalo como tal y asígnalo al servicio.

Los valores DATABASE_URL y REDIS_URL de cada addon de Postgres y Redis en marcha ya llegan a todos los servicios del proyecto, con la precedencia más baja. Para elegir un addon concreto o usar su URL privada, vincúlalo por consumidor con una referencia en lugar de --global:

lizard secrets set DATABASE_URL='${{postgres.DATABASE_PRIVATE_URL}}' --service api
lizard secrets set DATABASE_URL='${{postgres.DATABASE_PRIVATE_URL}}' --service worker

Si los valores del addon cambian, cada consumidor recoge el valor nuevo en su siguiente deploy o cambio de variables.

Precedencia

Cuando la misma clave se define en varios lugares, la última escritura prevalece:

addon-issued env  <  project secrets  <  project env  <  app env  <  app secrets  <  platform vars

Así que los secrets de la app anulan los secrets del proyecto, y las variables de la plataforma (PORT, LIZARD_SERVICE_NAME, LIZARD_PROJECT_ID, LIZARD_PUBLIC_DOMAIN, LIZARD_PRIVATE_DOMAIN) se aplican al final y no se pueden sobrescribir. PORT solo se define cuando el servicio tiene un puerto HTTP. Si defines PORT tú mismo, cambias el puerto al que Lizard dirige el tráfico en el siguiente deploy, salvo que el puerto se haya fijado con lizard port.

Tiempo de compilación vs. tiempo de ejecución

La mayoría de los cambios de variables se aplican sin recompilar: el servicio se reinicia para recogerlos, lo que tarda unos segundos. Las excepciones son los valores de compilación integrados en la imagen:

• Cambiar un valor VITE_* o NEXT_PUBLIC_* inicia al momento una recompilación de los servicios en marcha afectados (todos los servicios en marcha si es --global).
• Lizard integra estos valores como líneas ENV en los servicios de GitHub (el Dockerfile que genera lizardpack, o el Dockerfile raíz del repositorio) y en los servicios Node compilados desde buildCommand / startCommand. Un servicio con un dockerfilePath personalizado, o uno subido con lizard up sin esos comandos, no recibe variables de Lizard en la compilación; ningún servicio recibe build args salvo COMMIT_SHA. Para valores públicos en esos casos, haz commit de ellos en .env.production, define un comando de compilación o escríbelos en tu Dockerfile.

Consulta Pipeline de compilación → desencadenantes de recompilación.

Verificación

El acceso por shell a los servicios (lizard ssh) está desactivado, así que comprueba los valores de otra forma:

lizard logs --build --service api          # warns about every empty ${{…}} reference
lizard secrets list --service api --show   # stored values
lizard secrets list --service api --ref    # reference templates you can use

Si un valor que esperabas no está ahí, consulta Resolución de problemas → un secret o una referencia no aparece.

Desarrollo local

Ejecuta un comando localmente con los secrets de proyecto y de servicio del servicio inyectados:

lizard run --service api -- node scripts/seed.js

Los valores llegan tal como están guardados: las referencias ${{…}} quedan como texto literal y las variables de la plataforma (PORT, LIZARD_*) no se inyectan. Para un script que necesita la base de datos, ejecútalo con los valores de conexión reales del addon:

lizard run --service postgres -- node scripts/seed.js

Consulta qué inyecta lizard run.

Ver también

• Referencias entre servicios: lee los valores de un servicio desde otro sin copiar y pegar credenciales.
• lizard secrets: la referencia completa de comandos.

Actualizado 9 de octubre de 2026