# Variables de entorno y secretos: alcances, build y runtime, y lo que un preview no tiene que ver

Guardá las API keys en Variables, no en el repo. All, Production y Preview deciden qué copia un preview. NEXT_PUBLIC_ y VITE_ son públicas.

Canonical URL: https://unbroker.cloud/es/blog/environment-variables-and-secrets
Published: 2026-11-07
Reviewed: 2026-11-07
Author: Timoteo Borgobello

## La respuesta corta

Los secretos quedan fuera del repositorio. En Unbroker cada variable tiene alcance All, Production o Preview. Un preview nuevo copia All y Preview, y nunca copia un valor que es solo de Production.

`NEXT_PUBLIC_*` y `VITE_*` son públicas en el bundle del cliente aunque las cargues desde Variables. La revisión que está corriendo toma un cambio de runtime recién después de un redespliegue.

## Qué va en el repo y qué va en la plataforma

Un flag que se puede publicar puede vivir en el código. Una contraseña de base, una API key y un secreto para firmar la sesión van en la vista Variables del servicio. No los subas.

La referencia de deployments dice que no hay que commitear secretos de producción, que se guardan en la configuración del servicio y que se rotan si se exponen. La guía suma las capturas y los prompts de un agente.

| Valor | Dónde va |
| --- | --- |
| Feature flag público | El repositorio, cuando publicarlo es aceptable |
| Origen de API que ve el navegador | Configuración pública del frontend |
| Contraseña o connection string de la base | Variable de runtime del backend |
| Secreto para firmar la sesión | Variable de runtime del backend |
| Clave pública de Beacon | Puede ir en la configuración del frontend |
| Secreto JWT de Beacon | Solo en el backend |

El corte es el mismo si la app arrancó en Lovable, Bolt o Cursor. Lo que una página pública no demuestra está en [una app hecha con IA en producción](https://unbroker.cloud/es/blog/ai-built-app-to-production). Un frontend y una API en el mismo proyecto igual llevan variables distintas: el origen público en el frontend, la URL de la base en la API. El esquema es [frontend y API](https://unbroker.cloud/es/soluciones/frontend-and-api).

## Alcances: All, Production y Preview

All, Production y Preview son los tres alcances. Esos nombres quedan en inglés en la interfaz.

All cubre producción y los entornos de preview. Las variables que ya existían siguen en All hasta que las cambies. Production cubre producción. La referencia describe esa opción como solo el proyecto de producción. Preview cubre los entornos que no son de producción, incluidos los previews de pull request y los entornos con nombre, como staging.

La misma clave puede tener un valor distinto en cada alcance. Dentro de un servicio o de un proyecto, el valor del entorno pisa All. Una referencia a la variable de otro servicio se resuelve en el entorno del deployment.

Poné el origen de la API de producción en Production y el de staging en Preview. No dejes una credencial de la base de producción en All, salvo que quieras que cada preview nuevo la reciba. Esa es la diferencia entre variables de Production y de Preview.

Pegar un archivo `.env` importa cada variable en el alcance que elegiste. Editar o borrar una variable afecta solo esa variante. Para cambiar el alcance y conservar el secreto guardado, dejá el valor nuevo en blanco.

La nota del 6 de octubre es [variables de entorno para producción y previews](https://unbroker.cloud/changelog/2026-10-06-environment-scoped-variables).

## Variables del servicio y variables compartidas del proyecto

Una variable de servicio pertenece a una aplicación. Una variable compartida del proyecto, shared project variable en la documentación, es un ajuste que varios servicios del proyecto necesitan igual. Si la clave coincide, la del servicio pisa la compartida.

Usá la compartida cuando el valor de verdad es común. Usá la del servicio cuando un servicio necesita otra base u otra clave.

Las variables compartidas del proyecto requieren Pro. Free no las incluye. Los previews de pull request también requieren Pro. Pro sale $25 por mes con $25 de crédito de uso. El crédito se reinicia en cada ciclo y no se acumula. Si el uso elegible queda debajo del crédito, el cargo del mes sigue siendo $25. Las filas están en [precios](https://unbroker.cloud/es/precios) y en [Plans](https://docs.unbroker.cloud/billing/plans). Lo que Free no trae está en [hosting backend gratis](https://unbroker.cloud/es/blog/free-backend-hosting).

## Variables públicas de build y secretos de runtime

`NEXT_PUBLIC_*` y `VITE_*` son variables públicas de build. En Next.js, las env vars públicas usan el prefijo `NEXT_PUBLIC_`. Unbroker elige esos prefijos para el entorno de destino antes del build. Un valor que termina en el bundle de JavaScript es público aunque lo hayas escrito en Variables. Cuando ese valor público es el origen de la API que el navegador tiene que llamar, el orden del build, CORS y las cookies están en [desplegar un frontend y una API por separado](https://unbroker.cloud/es/blog/frontend-and-api).

El resto queda solo en runtime, con una excepción documentada: las credenciales de un registro de paquetes. En un build de JavaScript generado o en un Dockerfile propio, configurá `NODE_AUTH_TOKEN` o `GITHUB_TOKEN` en el servicio o como variable compartida del proyecto. Unbroker prefiere un `NODE_AUTH_TOKEN` que no esté vacío y, si no está, usa `GITHUB_TOKEN`. La credencial elegida se monta como secreto de BuildKit y aparece con los dos nombres durante la instalación de dependencias. No se pasa como argumento de build y no queda en una variable de entorno de la imagen. `NODE_AUTH_TOKEN` se saca del entorno de runtime. `GITHUB_TOKEN` puede seguir en runtime si la app también llama a la API de GitHub. Para GitHub Packages, usá un personal access token propio con `read:packages`. Un Dockerfile recibe una variable solo si la pide con `--mount=type=secret`. Declarar `ARG` no la entrega. La referencia es [variables de entorno](https://docs.unbroker.cloud/deployments/environment-variables).

Un servidor Next.js arranca en [desplegar Next.js](https://unbroker.cloud/deploy/nextjs). Qué cambia entre `next dev` y ese servidor, incluidas las `NEXT_PUBLIC_` en el build, está en [Next.js en producción](https://unbroker.cloud/es/blog/nextjs-in-production). Cambiar un origen público es otro paso que adjuntar un hostname. El DNS y el certificado están en [dominio personalizado y HTTPS](https://unbroker.cloud/es/blog/custom-domain-https).

## Qué copian los previews nuevos y qué no copian nunca

Un preview nuevo copia All y Preview. Nunca copia una variable que es solo de Production.

Cada preview es una copia independiente. Cambiar la variable padre no reescribe un preview que ya existe. Marcarla Production no revoca un secreto que ese preview ya guardó. Sacalo en ese preview, o recreá el preview, y rotá la credencial si pudo haberse expuesto. Cambiar la etiqueta no es una revocación.

Los previews automáticos de pull request corren solo ramas del repositorio conectado. Un fork externo no abre un preview automático, porque ese código podría leer los secretos del preview. Los previews heredan la protección de acceso del servicio de origen y su ajuste Wait for CI. Cerrar o mergear el pull request elimina el preview. La actividad renueva un vencimiento de siete días. Cómo dejar la base fuera de producción está en [entornos de preview de un pull request](https://unbroker.cloud/es/blog/pull-request-preview-environments).

## Aplicar, verificar, rotar

Abrí el servicio, elegí el alcance y cargá el valor en Cloud. Redesplegá para que la revisión en marcha use la configuración nueva de runtime. Si el valor se compila en los assets del frontend, ese cambio pide un build nuevo.

Con los deploys automáticos prendidos, un push a la rama configurada encola un deployment. Ese deployment es el que aplica la variable. La rama, los watch paths y la espera de los checks de GitHub están en [desplegar con git push](https://unbroker.cloud/es/blog/deploy-on-git-push).

Verificá con un request de la aplicación. No imprimas el secreto. Para una URL de base, corré una consulta acotada. Para un origen de API, mirá el destino del request en el navegador. No vuelques todo el entorno en los logs.

Si el proveedor permite dos credenciales a la vez, creá el reemplazo, actualizá la variable, redesplegá y verificá antes de revocar el valor viejo. Si el solapamiento es imposible, usá la ventana de mantenimiento que pide ese proveedor. Revisá workers y otros consumidores, no solo el servicio web. Los servicios worker requieren Pro.

## Agentes y prompts

Pasale al agente los nombres de las claves y los alcances. Los valores secretos se cargan en Cloud. No van en el prompt, en el repositorio ni en una captura.

La inspección de servicios por MCP no devuelve credenciales ni valores de variables de entorno. `get_service` lee un servicio sin ellos. Cómo limitar el token está en [dejar que un agente despliegue con cuidado](https://unbroker.cloud/es/blog/coding-agent-deploy-safely). Una app hecha en Cursor usa el mismo corte. La lista está en [desplegar con Cursor](https://unbroker.cloud/es/desplegar/cursor).

## Cómo funciona en Unbroker

Guardar secretos en el deploy, en Unbroker, es la vista Variables. Elegís la clave, el valor y el alcance. Las variables compartidas del proyecto y los previews de pull request requieren Pro. Un fork externo no abre un preview automático.

<aside class="plan-box">
<p><strong>En Unbroker.</strong> Abrí Variables en el servicio. Elegí All, Production o Preview. Las variables compartidas del proyecto y los previews de pull request requieren Pro. La guía es <a href="https://docs.unbroker.cloud/guides/environment-variables">variables de entorno</a>.</p>
</aside>

## Lista de control

1. Dejá los secretos de producción fuera del repositorio, de las capturas y de los prompts del agente.
2. Poné un connection string en Variables. Dejá un flag público en el código solo cuando publicarlo es aceptable.
3. Dale alcance Production a una credencial de producción. No la dejes en All.
4. Apuntá Preview a una base o a una API key que puedas descartar.
5. Dejá que una variable de servicio pise la compartida del proyecto cuando un servicio necesita otro valor.
6. Tratá `NEXT_PUBLIC_*` y `VITE_*` como públicas. Se eligen antes del build.
7. Redesplegá después de un cambio de runtime. Reconstruí cuando el valor se compila en los assets del frontend.
8. Después de ajustar un alcance, editá o recreá los previews que ya copiaron el valor viejo.
9. Rotá una contraseña filtrada con solapamiento cuando el proveedor lo permite, y después revisá workers y otros consumidores.
10. Pasale a un agente nombres y alcances. Cargá los valores secretos en Cloud.

## Preguntas frecuentes

### ¿Dónde guardo las API keys de una app desplegada?

En la vista Variables del servicio, en Cloud, no en el repositorio y no en un .env commiteado. Una key de producción va en Production. Dale a Preview una key de prueba, y dejá un valor en All solo cuando cada preview nuevo tiene que recibirlo. Los pasos están en la [guía de variables de entorno](https://docs.unbroker.cloud/guides/environment-variables).

### ¿Qué diferencia hay entre las variables All, Production y Preview?

All aplica a producción y a los entornos de preview. Production aplica a producción. La referencia describe esa opción como solo el proyecto de producción. Preview aplica a los entornos que no son de producción, incluidos los previews de pull request y los entornos con nombre, como staging. Para la misma clave, el valor del entorno pisa All dentro de ese servicio o proyecto.

### ¿Los previews de un pull request reciben secretos de producción?

Un preview nuevo copia All y Preview, y no recibe valores que son solo de Production. Un secreto de producción que quedó en All sí se copia. Un preview que ya existe se queda con la copia que tiene, y marcarlo Production no saca esa copia. Los previews de pull request requieren Pro. El mapa está en [entornos de preview](https://unbroker.cloud/es/blog/pull-request-preview-environments).

### ¿Las variables NEXT_PUBLIC_ o VITE_ son secretas?

No. Esos prefijos son variables públicas de build. Unbroker las elige para el entorno de destino antes de construir. Un valor que queda en el bundle de JavaScript es público aunque lo hayas cargado en Variables.

### ¿Hay que redesplegar después de cambiar una variable?

Sí. Redesplegá el servicio para que la revisión en marcha use el valor nuevo de runtime. Si ese valor se compila en los assets del frontend, el cambio también pide un build nuevo.

### ¿Qué son las variables compartidas del proyecto y necesitan Pro?

Una variable compartida del proyecto es un ajuste que pueden usar varios servicios del proyecto. Una variable de servicio con la misma clave la pisa. Las variables compartidas del proyecto requieren Pro, y Free no las incluye. Pro sale $25 por mes con $25 de crédito de uso. Mirá [precios](https://unbroker.cloud/es/precios) y [Plans](https://docs.unbroker.cloud/billing/plans).

### ¿Cómo roto una contraseña de base que se filtró?

Si la base permite dos contraseñas a la vez, creá el reemplazo, actualizá la variable, redesplegá y verificá con una consulta acotada antes de revocar la contraseña vieja. Si no hay solapamiento, usá la ventana de mantenimiento que pide ese proveedor. Editá o recreá los previews que ya copiaron el valor viejo. Revisá workers y otros consumidores, no solo el servicio web. No imprimas la contraseña en los logs.

### ¿Un agente de código puede ver mis valores secretos?

La inspección de servicios por MCP no los devuelve. La herramienta get_service mira un servicio sin credenciales ni valores de variables de entorno. El agente sí ve un secreto que pegás en el prompt, en el repositorio o en una captura. Pasale nombres y alcances, y cargá los valores en Cloud. Los límites del token están en [dejar que un agente despliegue](https://unbroker.cloud/es/blog/coding-agent-deploy-safely).

## Related reading

- [Entornos de preview de un pull request](https://unbroker.cloud/es/blog/pull-request-preview-environments)
- [Dejar que un agente despliegue](https://unbroker.cloud/es/blog/coding-agent-deploy-safely)
- [App hecha con IA a producción](https://unbroker.cloud/es/blog/ai-built-app-to-production)
- [Dominio personalizado y HTTPS](https://unbroker.cloud/es/blog/custom-domain-https)
- [Desplegar con git push](https://unbroker.cloud/es/blog/deploy-on-git-push)
- [Hosting backend gratis](https://unbroker.cloud/es/blog/free-backend-hosting)
- [Desplegar Next.js](https://unbroker.cloud/deploy/nextjs)
- [Variables con alcance de entorno](https://unbroker.cloud/changelog/2026-10-06-environment-scoped-variables)
- [Precios](https://unbroker.cloud/es/precios)
