Grupos de Variables de Entorno Compartidas

An environment variable group holds values that several Orbit projects need, such as a shared API key or a database credential, in one place. Link the group to the projects that need it and every…

Un grupo de variables de entorno contiene valores que varios proyectos de Orbit necesitan, como una clave API compartida o una credencial de base de datos, en un solo lugar. Vincula el grupo a los proyectos que lo necesitan y cada una de sus compilaciones obtiene esas variables, por lo que rotar una clave es una edición en lugar de seis.

Dónde viven los grupos de variables de entorno

Abre Orbit y elige Env groups en la navegación de nivel superior. La página se titula Shared env var groups y los describe como grupos a nivel de cuenta compartidos entre varios proyectos de Orbit.

Los grupos están por encima de los proyectos. Las variables propias de un proyecto siguen viviendo en su pestaña Env vars: consulta Environment Variables in Orbit.

Cuándo usar un grupo

La prueba es simple: ¿se pega el mismo valor en más de un proyecto?

Buenos candidatos:

Una clave de análisis compartida o de seguimiento de errores utilizada por cada interfaz.
Una cadena de conexión de réplica de lectura utilizada por varias herramientas internas.
Una clave API de terceros para un servicio con el que habla toda la cuenta.
Un token de cliente de marca de características común.

Malos candidatos:

Cualquier cosa específica de un proyecto. Pertenece a ese proyecto.
Cualquier cosa que difiera entre producción y vista previa. Los grupos no son por entorno, por lo que un valor que cambia según el entorno pertenece a las variables de entorno propias del proyecto.

Crear un grupo

Haz clic en New group.
Dale un Group name, hasta 64 caracteres. Asígnale un nombre basado en lo que contiene, por ejemplo, el servicio al que pertenecen las credenciales.
Añade una Description opcional.
Haz clic en Create group.

Una cuenta puede contener hasta 20 grupos. Cuando estés en el límite, el botón muestra (limit reached) y se rechaza crear otro.

Crear, editar y eliminar un grupo requiere un rol de propietario o administrador en la cuenta. Los desarrolladores y espectadores pueden ver grupos pero no cambiarlos, que es deliberado: una edición de grupo cambia varios proyectos a la vez.

Añadir variables

Abre el grupo y utiliza la sección Variables:

Haz clic en Add variable.
Introduce la clave y el valor.
Marca Mark as secret para cualquier cosa sensible.
Haz clic en Save group.

Una variable marcada como secreta se almacena cifrada y su valor no se devuelve al panel después. La lista muestra la clave y un indicador Marked as secret (hidden) en lugar del valor. Los valores no secretos permanecen visibles para que puedas verificarlos de un vistazo.

Marcar una variable como secreta significa que no puedes leerla desde el panel. Ese es el punto, pero también significa que el grupo no es un administrador de contraseñas. Mantén la copia autorizada donde tu equipo ya guarda las credenciales y trata el grupo como el mecanismo de distribución.

Para cambiar el valor de un secreto, escribe el nuevo y guarda. Para eliminar una variable, haz clic en Remove en su fila y guarda.

Vincular proyectos

La sección Linked projects enumera cada proyecto de la cuenta. Haz clic en un proyecto para vincularlo o desvincularlo; los proyectos vinculados están resaltados. Guarda el grupo para aplicar.

Un grupo sin proyectos vinculados no hace nada, y la sección dice No projects yet hasta que vincules uno.

Las variables de grupo se inyectan en tiempo de compilación, por lo que vincular un proyecto afecta su próxima compilación, no la implementación actualmente activa. Si necesitas el cambio ahora, vuelve a implementar: consulta Deploying Your Project.

Precedencia

La regla se indica en la página: las variables de grupo se inyectan en tiempo de compilación, y las variables a nivel de proyecto y a nivel de entorno tienen precedencia sobre las variables de grupo.

En otras palabras, lo más específico gana:

Variables a nivel de entorno, prioridad más alta.
Variables a nivel de proyecto.
Variables de grupo, prioridad más baja.

Ese orden es útil en lugar de ser simplemente una tecnicidad. Establece el valor predeterminado compartido en el grupo e anúlalo en el único proyecto que necesita algo diferente, sin eliminar ese proyecto del grupo. Consulta Environment Variables Per Environment para la capa de entorno.

También explica la confusión más común con los grupos: editas el grupo, vuelves a implementar y nada cambia, porque el proyecto tiene su propia variable con la misma clave ganando silenciosamente. Verifica primero la pestaña Env vars propia del proyecto cuando un valor de grupo parece estar siendo ignorado.

Rotar una credencial compartida

Este es el flujo de trabajo para el que existen los grupos:

Crea la nueva credencial en el proveedor, dejando la antigua activa.
Edita el valor en el grupo y guarda.
Vuelve a implementar cada proyecto vinculado o espera a su próxima implementación.
Confirma que cada proyecto funciona con la nueva credencial.
Revoca la credencial antigua en el proveedor.

Hacer el paso 5 primero te da una ventana donde cada proyecto vinculado está roto a la vez, que es precisamente el riesgo que concentra una credencial compartida.

Eliminar un grupo

Haz clic en eliminar en el grupo. La confirmación es específica sobre la consecuencia: las compilaciones futuras perderán estas variables, y las compilaciones ya completadas no se ven afectadas.

Eliminar también desvincula cada proyecto. Eso significa que las implementaciones en ejecución continúan con los valores con los que se compilaron, y la próxima compilación de cada proyecto vinculado viene sin ellos. Si esas variables son necesarias, esa compilación fallará o la aplicación se comportará mal en tiempo de ejecución.

Antes de eliminar, desvincula proyectos uno a uno y vuelve a implementar cada uno, para que descubras cuáles realmente dependen del grupo antes de que todos lo pierdan.

Consejo práctico

Mantén los grupos pequeños y con propósito. Un grupo por servicio externo supera un grupo "compartido" gigante, porque te permite vincular exactamente los proyectos que necesitan cada cosa.

Nombra las claves igual en todas partes. Si un proyecto lee SENTRY_DSN y otro lee SENTRY_KEY, un grupo compartido no puede ayudarte. Estandariza los nombres primero.

No pongas credenciales de producción en un grupo vinculado a proyectos con vistas previas públicas. Las variables de grupo llegan a cada compilación de un proyecto vinculado, incluidas las vistas previas.

Solución de problemas

Una compilación no ve la variable. Confirma que el proyecto está vinculado y guardado, y que la compilación se ejecutó después de que se realizó el vínculo. Las variables de grupo se aplican desde la próxima compilación.

El valor es incorrecto en tiempo de ejecución. Una variable a nivel de proyecto o a nivel de entorno con la misma clave la está anulando. Verifica la pestaña Env vars del proyecto.

Crear grupo no está disponible. Estás en el límite de 20 grupos, o tu rol de cuenta no es propietario ni administrador.

El valor de un secreto se muestra en blanco. Eso es correcto. Los valores secretos no se devuelven al panel después de guardar.

Un proyecto se rompió después de una edición de grupo. Revierte el valor en el grupo y vuelve a implementar, luego averigua qué proyecto estaba en desacuerdo. Rolling Back a Deployment mantiene el sitio en ejecución saludable mientras lo haces.

A dónde ir después

Environment Variables in Orbit para variables a nivel de proyecto.
Environment Variables Per Environment para la capa de anulación.
Orbit Project Settings para el resto de la configuración de un proyecto.