Puedes crear un nuevo entorno ramificando desde cualquier entorno activo existente. El proceso clona la base de datos fuente y opcionalmente copia recursos de configuración, dándote un espacio de trabajo aislado para desarrollar o probar cambios.

---

Cómo crear un nuevo entorno

1. Abre el menú desplegable Selector de entorno en la barra de navegación superior de la Consola Backend.
2. Haz clic en el botón + Crear entorno.
3. Aparecerá un cuadro de diálogo modal con las siguientes opciones de configuración.

Campos de configuración

• Rama desde: Selecciona el entorno fuente desde el cual ramificar. Solo los entornos con estado active están disponibles como fuentes.
• Nombre del entorno: Introduce un nombre único para el nuevo entorno (ej: staging, feature-auth, qa-sprint-12). Los nombres solo pueden contener caracteres alfanuméricos, guiones y guiones bajos.

Modo de rama

Elige cómo se clona la base de datos fuente:

• Full (esquema + datos): Crea una copia completa de la base de datos fuente, incluyendo todas las estructuras de tablas y datos de filas. Úsalo cuando necesites datos realistas para pruebas o QA.
• System (solo esquema): Copia solo el esquema de la base de datos (tablas, columnas, índices, relaciones, enums, vistas) sin datos de filas. Úsalo para entornos de desarrollo limpios donde quieras empezar con un conjunto de datos vacío.

Copiar configuración desde la fuente

Opcionalmente copia configuraciones de recursos del entorno fuente. Cada opción se controla con una casilla y requiere el rol ProjectOwner:

• Proveedores de almacenamiento de archivos: Copia las configuraciones de proveedores (S3, GCS, Azure, Filestack) al nuevo entorno. Cada proveedor copiado recibe un nuevo identificador único.
• Rutas de gateway: Copia rutas personalizadas de API gateway y webhooks. Esto preserva tu configuración de enrutamiento en el nuevo entorno.
• Config de seguridad: Copia orígenes CORS y configuraciones de límite de tasa. Esto garantiza que el nuevo entorno herede las mismas políticas de red que su padre.
• Variables de entorno: Copia pares clave-valor de variables de entorno. Esto permite que el nuevo entorno comience con los mismos secretos de configuración que la fuente.

Nota: Los proveedores de autenticación están excluidos intencionalmente de las opciones de copia por razones de seguridad. Los secretos de cliente OAuth, credenciales de Cognito y otras claves de autenticación deben configurarse de forma independiente por entorno para prevenir el intercambio accidental de credenciales.

4. Haz clic en Crear entorno para iniciar el proceso de ramificación.

---

Qué ocurre durante la ramificación

Cuando creas un nuevo entorno, ocurre la siguiente secuencia:

1. Validación: El sistema verifica que el nombre del entorno sea único y que el entorno fuente esté en estado active.
2. Creación de registro: Se crea un nuevo registro de entorno y se registra con el proyecto en el almacén de configuración de la plataforma.
3. Clonación de base de datos: Se clona la base de datos PostgreSQL fuente. En modo Full, se incluyen todos los datos; en modo System, solo se copia el esquema (estructuras de tablas).
4. Usuarios de base de datos: Se provisionan automáticamente nuevas credenciales seguras de base de datos para el entorno clonado.
5. Registro de configuración: El nuevo entorno se vincula a la configuración global del proyecto.
6. Copia de recursos: Si se seleccionó, los proveedores de archivos, rutas de gateway, config de seguridad y variables de entorno se copian de la fuente al nuevo entorno.
7. Activación de estado: El estado del entorno pasa a active y queda disponible para usar.

Si algún paso falla, el sistema realiza un rollback automático: la base de datos clonada y las credenciales asociadas se eliminan, garantizando que no queden recursos huérfanos.

---

GraphQL API

Mutation: branchEnvironment

mutation BranchEnvironment($input: BranchEnvironmentInput!) {
  branchEnvironment(input: $input) {
    success
    message
    environment {
      id
      name
      parentId
      parentName
      branchMode
      branchedAt
      status
      createdAt
      updatedAt
    }
  }
}

Variables:

{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "name": "staging",
    "sourceEnvironment": "master",
    "mode": "full",
    "copyFileProviders": true,
    "copyGatewayRoutes": true,
    "copySecurityConfig": false,
    "copyEnvironmentVariables": true
  }
}

Respuesta:

{
  "data": {
    "branchEnvironment": {
      "success": true,
      "message": "Environment created successfully",
      "environment": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "staging",
        "parentId": "master-env-id",
        "parentName": "master",
        "branchMode": "full",
        "branchedAt": "2026-03-08T20:00:00Z",
        "status": "active",
        "createdAt": "2026-03-08T20:00:00Z",
        "updatedAt": "2026-03-08T20:00:05Z"
      }
    }
  }
}

Campos de entrada

Campo	Tipo	Requerido	Descripción
projectId	String	Sí	El identificador único del proyecto
name	String	Sí	Nombre para el nuevo entorno
sourceEnvironment	String	Sí	Nombre del entorno desde el cual ramificar
mode	String	Sí	Modo de clonación: "full" o "system"
copyFileProviders	Boolean	No	Copiar configuraciones de proveedores de almacenamiento
copyGatewayRoutes	Boolean	No	Copiar rutas personalizadas de API gateway
copySecurityConfig	Boolean	No	Copiar configuraciones CORS y límite de tasa
copyEnvironmentVariables	Boolean	No	Copiar pares clave-valor de variables de entorno

Requisitos de permisos

• Crear un entorno sin banderas de copia requiere acceso estándar al proyecto.
• Habilitar cualquier bandera de copia (copyFileProviders, copyGatewayRoutes, copySecurityConfig, copyEnvironmentVariables) requiere el rol ProjectOwner, ya que estas operaciones implican copiar datos de configuración sensibles.