Configuración de Variables de Entorno Por Entorno

Orbit te permite decidir exactamente qué compilaciones ven qué variables de entorno, para que las credenciales de producción nunca terminen en una vista previa de rama accesible públicamente. Esta guía cubre cómo funcionan el alcance y la precedencia, cómo agregar una variable solo para producción, cómo se comporta la herencia de ensayo, y cómo verificar qué recibió realmente una compilación.

Por qué esto es importante

Una vista previa de rama obtiene una URL pública. Cualquiera con el enlace puede cargarla. Si una variable tiene alcance en todos los entornos, se inyecta en la compilación de esa vista previa, y sea lo que sea que haga la vista previa con ella, lo hace con tus credenciales de producción.

Esta es la razón completa por la que existe esta página. Todo lo siguiente está al servicio de una regla: los secretos de producción pertenecen al alcance de producción, y en ningún otro lugar.

Cómo funciona el alcance

Cada variable tiene un alcance que decide cuándo se inyecta en el tiempo de compilación.

Cuando la misma clave existe en ambos niveles, la más específica gana. Una anulación a nivel de entorno vence a una variable en todo el proyecto con la misma clave. La página Env vars indica esto en el subtítulo de la sección Todos los entornos: las variables en todo el proyecto están disponibles en toda compilación, y las anulaciones a nivel de entorno tienen precedencia.

Las variables en todo el proyecto también se pueden estrechar sin convertirse en una anulación. El control Disponible en ofrece tres tipos de entorno (production, staging, preview) y puedes deseleccionar cualquiera de ellos.

Agregar una variable con un alcance

1. Abre tu proyecto en Orbit y haz clic en la pestaña Env vars.
2. Desplázate hasta el formulario Add variable en la parte inferior.
3. Completa la KEY y el value.
4. Usa el desplegable Scope:
   • All environments (project-wide) la inyecta en toda compilación.
   • [Environment name] only ([type] override) la limita a ese entorno.
5. Si elegiste project-wide, usa los botones Available in para deseleccionar tipos de entorno a los que esta variable no debe llegar.
6. Marca Mark as secret para cualquier cosa sensible.
7. Haz clic en Add.

Antes de confirmar, el formulario te dice qué está a punto de hacer. Una anulación muestra un aviso diciendo que se aplicará solo a las compilaciones de ese entorno y que las variables en todo el proyecto todavía se aplican en otros lugares. Una variable en todo el proyecto restringida muestra exactamente a qué tipos de entorno se inyectará.

Agregar una variable solo para producción

Dos rutas equivalentes:

• En el desplegable Scope, elige tu entorno de producción (lleva una insignia verde production), o
• Mantén el alcance como All environments y deselecciona staging y preview bajo Available in.

De cualquier forma, la variable está ausente cuando se ejecuta una vista previa o una compilación de ensayo.

El patrón seguro

El patrón que resuelve esto limpiamente para la mayoría de proyectos:

1. Agrega la credencial de production limitada al entorno de producción solamente.
2. Agrega una variable con la misma clave, que contenga un valor de prueba o sandbox, en alcance en todo el proyecto.

Las compilaciones de producción obtienen el valor con alcance de producción porque el alcance más específico gana. Las vistas previas y el ensayo obtienen el valor de prueba. Nada está indefinido en ningún lado, y ninguna credencial de producción llega nunca a una vista previa.

Aplícalo a:

• URLs de base de datos de producción
• Claves secretas de proveedores de pagos, usando las claves de prueba del proveedor para vistas previas
• Claves de envío de correo electrónico, para que una vista previa no pueda enviar correo a clientes reales
• Tokens de administrador y secretos de firma
• Cualquier cosa con un costo por llamada

Heredar variables de producción en ensayo

Si tu entorno de ensayo es similar a producción y solo quieres anular algunos valores, no tienes que duplicarlo todo.

En Settings, busca Staging: environment variables y activa Inherit production env vars. Las variables de producción se fusionan entonces en compilaciones de ensayo con menor prioridad que las anulaciones específicas de ensayo, así que cualquier cosa que establezas explícitamente en ensayo todavía gana.

Ver y editar variables existentes

La pestaña Env vars agrupa variables en:

• All environments en la parte superior, que contiene variables en todo el proyecto
• Una sección contraíble por entorno, que contiene las anulaciones de ese entorno, con un recuento de cuántas hay

Encima de ellas hay un cuadro de búsqueda y un filtro Secrets only.

Las insignias junto a cada nombre de variable muestran a qué tipos de entorno llega. Una variable que muestra production y preview pero no staging faltará en compilaciones de ensayo, y esa fila de insignia es la forma más rápida de auditar una lista larga.

Haz clic en el icono de edición para cambiar un valor. El valor actual de una variable secreta no se puede revelar, solo reemplazar.

Copiar y comparar entre entornos

Copy variables between environments copia un conjunto completo de un alcance a otro. Elige un From y un To, opcionalmente marca Overwrite variables that already exist in the target, y haz clic en Preview para ver cuántas se añadirán, actualizarán y omitirán antes de confirmar.

La página Env sync check compara producción y ensayo clave por clave e informa qué existe solo en uno, qué tiene valores diferentes, y qué coincide. Es el primer lugar correcto para "ensayo funciona y producción no", o al revés.

Compartir variables entre proyectos

Si varios proyectos necesitan la misma credencial, usa un grupo de env en lugar de pegarla en cada proyecto. Ve a Orbit, luego Env groups, crea un grupo, agrega las variables, y vincula los proyectos que las necesitan.

Las variables del grupo se inyectan en tiempo de compilación y se encuentran al final del orden de precedencia: las variables a nivel de proyecto y a nivel de entorno ambas tienen precedencia sobre las variables del grupo. Puedes tener hasta 20 grupos en una cuenta.

Eliminar un grupo elimina esas variables de futuras compilaciones de cada proyecto vinculado. Las compilaciones ya completadas no se ven afectadas.

Importar en masa

El botón Import .env abre un cuadro de pegado. Pega un archivo .env, elige un alcance, y Orbit informa cuántas variables encontró y cuántas marcará como secreto. Las claves que contienen SECRET, TOKEN, KEY, PASSWORD y términos similares se marcan automáticamente. Hay una opción Overwrite existing variables with the same key, desactivada por defecto.

Download .env produce una plantilla de nombres de variable solo, sin valores, para compartir con un compañero que proporcionará los suyos.

Verificar qué recibió realmente una compilación

La página de detalle de cada implementación lista las claves de variable de entorno inyectadas en tiempo de compilación y las compara con tu configuración actual: agregadas, cambiadas, eliminadas, sin cambios. Las claves de color azul vinieron de una anulación específica del entorno, las grises del nivel de proyecto.

Los valores nunca se almacenan ni se muestran. Pasar el ratón sobre una clave proporciona una huella digital SHA-256, que es suficiente para confirmar que dos entornos contienen el mismo valor sin revelarlo.

Si la configuración cambió después de que esa implementación se compiló, la página lo dice con un aviso de Environment variables updated since this deployment y te recuerda que el cambio no tendrá efecto hasta que reimplementes.

Lecturas relacionadas

• Environment Variables para lo básico, secretos y reglas de prefijo de marco
• Branch Preview Deployments in Orbit para cómo funcionan las vistas previas públicas
• Viewing Build Logs para la diferencia de variable en tiempo de compilación