Entornos de preview explicados: una copia nueva de tu app para cada pull request

Un entorno de preview (o de vista previa) es una copia temporal de tu aplicación, construida a partir de una pull request o de una rama y accesible en su propia URL. Quien revisa abre un enlace y prueba el cambio en el navegador en lugar de leer un diff. Cuando el trabajo termina, el entorno desaparece.

Esta guía explica para qué sirven los entornos de preview, qué los hace complicados de gestionar y cómo funcionan en Nodion.

¿Qué es un entorno de preview?

Piensa en él como un entorno de staging temporal para un solo cambio. Cada pull request, o la rama que elijas, recibe:

• su propia build del código de esa rama,
• su propia app en ejecución con su propia URL,
• sus propias copias de los servicios de los que depende, normalmente al menos una base de datos nueva,
• una duración limitada.

A diferencia de un servidor de staging compartido, nadie tiene que esperar a que quede libre y una funcionalidad a medio terminar no puede interferir en las pruebas de otra. Para la misma idea también verás los términos review apps, deploy previews o entornos efímeros.

Por qué los usan los equipos

• Revisar software en ejecución, no solo código. Un diseño roto, un flujo confuso o una página lenta saltan a la vista en el navegador y se pasan por alto fácilmente en un diff.
• QA por cambio. Quien hace las pruebas revisa cada cambio por separado antes del merge, así que cada bug que encuentra pertenece exactamente a una pull request.
• Stakeholders sin entorno de desarrollo. Diseñadores, product managers o un cliente abren un enlace. Sin checkout local y sin compartir pantalla.
• Probar migraciones. Una migración de esquema tiene que ejecutarse contra una base de datos real antes de que la preview funcione. Una migración que solo funciona en un portátil falla aquí, no en producción.
• Trabajo en paralelo. Cinco pull requests abiertas son cinco previews, en lugar de una cola delante de un único servidor de staging.

Qué los hace complicados

Hacer la build de la app es lo fácil. Lo difícil es todo lo que la rodea.

Bases de datos

Una app sin datos es difícil de revisar, así que la mayoría de las previews necesitan una base de datos. Hay tres opciones habituales: una base de datos vacía, una base de datos vacía con datos iniciales (seed) o una copia de producción. Copiar la base de datos de producción es tentador, pero lleva datos reales de clientes, incluidos datos personales, a muchos entornos de corta duración a los que puede acceder más gente. Además, es lento cuando la base de datos es grande. Para la mayoría de los equipos, una base de datos vacía con un script de seed que genere datos de demostración realistas es la opción por defecto más segura.

Secretos

Una preview ejecuta código que todavía no se ha revisado. Las credenciales de producción no deben estar ahí. Asigna a las previews claves de prueba o de sandbox para los proveedores de pago, el email y las APIs de terceros, para que un bug en una rama no pueda hacer un cargo en una tarjeta real ni enviar correos a clientes reales.

URLs y callbacks

Cada preview tiene un hostname distinto. Las URLs de redirección de OAuth, los endpoints de webhooks, las reglas CORS y las cookies vinculadas a tu dominio de producción pueden dejar de funcionar. Las apps que leen su propia URL base de la configuración, en lugar de llevar el dominio de producción escrito en el código, tienen muchos menos problemas aquí.

Coste y limpieza

Cada preview abierta ejecuta una app, más una base de datos nueva por cada base de datos vinculada a la app principal. Diez pull requests abiertas pueden suponer diez entornos adicionales, y una preview olvidada sigue en marcha hasta que alguien la cierra. La limpieza tiene que ocurrir sin que nadie tenga que pensar en ella, y por eso las previews deberían caducar solas.

Cómo funcionan los entornos de preview en Nodion

En Nodion, las previews forman parte de cada aplicación que se despliega desde un repositorio Git:

• Actívalas en los Settings de la app.
• Una preview por pull request o rama. Cada preview es una app efímera con su propia URL.
• A mano o automáticas. Crea una preview a mano o deja que Nodion la cree automáticamente para las pull requests.
• Una base de datos nueva. Por cada base de datos vinculada a la app, la preview recibe su propia base de datos vacía, nunca un clon de tus datos de producción. Los volúmenes, los buckets y las zonas de email no se copian.
• La configuración de la app viene incluida. Una preview empieza con una copia de las variables de entorno de la app, secrets incluidos. Las variables de las bases de datos vinculadas apuntan a las bases de datos nuevas de la preview; todo lo demás, incluidas las claves y las URLs de otros servicios, se copia tal cual, así que revísalo. Nodion añade NODION_PREVIEW=1, NODION_PR_NUMBER, NODION_BRANCH y NODION_PARENT_APP.
• Las previews caducan tras un número de días sin despliegue (7 por defecto, configurable en los ajustes de la app). Hasta entonces, puedes volver a desplegar o cerrar cada una desde la pestaña Previews de la app.
• Solo apps de Git. Las apps desplegadas desde una imagen ya construida no tienen previews.

La base de datos nueva es una decisión deliberada: las bases de datos vinculadas a una preview empiezan vacías, así que no contienen datos de producción. Revisa también las claves y las URLs copiadas, para que el código de la preview no pueda llegar a sistemas de producción a través de ellas. La otra cara es que tu app tiene que poder arrancar con una base de datos vacía, algo que de todos modos merece la pena resolver bien.

Para empezar, conecta tu repositorio en integraciones de Git, crea la app a partir de él y activa las previews en sus ajustes. Tienes los detalles en la documentación de aplicaciones.

Un ciclo de revisión típico

1. Un desarrollador abre una pull request. Con las previews automáticas activadas, se inicia una preview para ella con su propia URL y una base de datos vacía.
2. El desarrollador publica el enlace de la preview en la pull request. Revisores, QA y el product owner prueban el cambio en el navegador.
3. Los comentarios dan lugar a nuevos commits. Vuelve a desplegar la preview desde la pestaña Previews para que los revisores vean el código más reciente.
4. Cuando se haya aprobado y fusionado el cambio, cierra la preview o deja que caduque sola.

Nadie tuvo que pedir turno en staging, y Nodion creó una base de datos nueva en lugar de reutilizar la vinculada a la app principal. Revisa todas las demás claves y URLs copiadas antes de ejecutar código de preview, porque siguen apuntando adonde apunte la configuración de la app.

Prepara tu app para las previews

• Ejecuta las migraciones automáticamente cuando la app se despliega o arranca, para que una base de datos nueva reciba el esquema actual sin pasos manuales.
• Añade un script de seed que cree un login de prueba y algo de contenido de demostración. Quien revisa debería ver algo útil desde el primer clic.
• Lee la URL base de una variable de entorno en lugar de escribir tu dominio de producción en el código.
• Configura en modo de prueba las acciones con efectos externos cuando NODION_PREVIEW esté definida: pagos, emails y todo lo que escriba en otros sistemas. Las previews heredan los secrets de la app, así que sin esa comprobación una preview usa tus claves de producción.
• Mantén pequeñas las pull requests. Una preview de un cambio concreto es mucho más fácil de revisar que una de una semana de trabajo.

Cuándo puedes prescindir de ellos

En un proyecto en solitario con pocos cambios a la semana, puede bastar con un entorno local y producción. Las previews compensan en cuanto más de una persona revisa, prueba o aprueba los cambios, o cuando las migraciones de base de datos forman parte de tu trabajo habitual.

Las previews vienen incluidas en todas las apps de Git en Nodion, junto con procesos, logs, métricas y auto-deploy. Consulta Applications para ver el panorama completo.