DevOps y observabilidad
Integración Git en Microsoft Fabric: un flujo de desarrollo práctico
Cómo funciona de verdad la integración Git en Fabric en el día a día: workspace y rama, commit y actualización, branch out, pull requests, conflictos, deriva y permisos.
En este artículo
La integración Git de Fabric es la funcionalidad que permite a un equipo dejar de tratar un workspace como la única copia de su trabajo. Los notebooks, pipelines, modelos semánticos, informes y las definiciones de Lakehouse y Warehouse se convierten en archivos de un repositorio Git, con historial, ramas y pull requests.
También es fácil usarla mal. Hay equipos que conectan un workspace compartido a main, dejan que cinco personas lo editen y descubren que la integración Git no les ha dado aislamiento, ni revisión, ni despliegue. Les ha dado el historial de versiones de un desorden compartido.
Esta guía trata del flujo de desarrollo: cómo pasa un cambio del workspace de un ingeniero a un commit revisado en main. Promover ese commit a QA y a producción es otro trabajo, que se explica en CI/CD de Microsoft Fabric con fabric-cicd: de Git a DEV, QA y PROD. Mantener separadas esas dos responsabilidades es la idea más importante de este artículo.
Qué hace la integración Git de Fabric
La integración Git funciona a nivel de workspace. Un workspace se conecta a un repositorio Git, una rama y una carpeta de ese repositorio. Una vez conectado:
- Cada elemento compatible se serializa en una carpeta de archivos: un archivo de metadatos
.platformmás archivos de definición comonotebook-content.py,pipeline-content.jsono archivos TMDL para un modelo semántico. - Las carpetas del workspace se reflejan como carpetas en Git, hasta diez niveles de profundidad.
- Un panel Source control (control de código fuente) muestra qué elementos han cambiado en el workspace (para hacer commit) y cuáles han cambiado en la rama (para actualizar).
- Puedes hacer commit de los cambios del workspace a la rama y actualizar el workspace desde la rama.
Los proveedores compatibles son Azure DevOps, GitHub y GitHub Enterprise, todos en sus versiones en la nube. La mayoría de los elementos habituales de ingeniería de datos son compatibles, incluidos Lakehouses, notebooks, definiciones de trabajos de Spark, Environments, pipelines, Dataflow Gen2, Warehouses, modelos semánticos e informes, aunque algunos tipos de elementos siguen en versión preliminar. Consulta la lista actual antes de depender de un elemento concreto.
Qué no hace
La integración Git es control de código fuente y sincronización. No es:
- Una herramienta de despliegue. No promueve un commit a QA ni a producción, no reemplaza los ID propios de cada entorno ni decide qué workspace recibe qué versión. Para eso están los pipelines de despliegue o fabric-cicd.
- Una copia de seguridad de los datos. Versiona las definiciones de los elementos, no los datos. Las tablas del Lakehouse, los archivos del área
Filesy las vistas de Spark no se rastrean; actualizar un workspace desde Git no los sobrescribe ni los restaura. Un Warehouse se confirma como proyecto de base de datos (su esquema), no con sus filas. - Un proceso de revisión por sí sola. Hacer commit desde el workspace directamente a
maines posible, y se salta la revisión por completo a menos que las directivas de rama lo impidan. - Aislamiento. Un workspace es un único runtime. Todas las personas que trabajan en él comparten los mismos elementos, sea cual sea la rama a la que esté conectado.
Una vez que ese límite está claro, el resto del flujo se deduce solo.
Workspace y rama: la única regla que importa
Un workspace solo puede estar conectado a una rama a la vez, y cada cambio hecho en el workspace afecta a todos los que lo usan. Por eso la propia recomendación de Microsoft es que los desarrolladores trabajen en workspaces separados, cada uno conectado a su propia rama, en lugar de que muchas personas compartan uno.
Eso da una regla sencilla:
Un cambio activo, una rama, un workspace.
La regla produce este flujo:
- 1Feature branch
- 2Workspace de desarrollo de FabricConectado a la feature branch
- 3Editar y probar los elementos
- 4Hacer commit desde el panel Source control
- 5Pull request hacia main
- 6Revisión y merge
- 7Proceso de despliegueQA y después producción
El paso de despliegue del final no forma parte de la integración Git, y es a propósito. Los workspaces desplegados no están conectados a Git; los actualiza el pipeline de publicación a partir de un commit revisado.
Configurar un workspace de desarrollo
Un administrador del workspace lo conecta a un repositorio, una rama y una carpeta desde Workspace settings → Git integration. Apunta la carpeta al directorio que lee tu herramienta de despliegue (por ejemplo, una carpeta workspace/), para que lo que los desarrolladores confirman sea exactamente lo que despliega el pipeline.
En la primera conexión, Fabric sincroniza ambos lados:
- Si el workspace o la rama están vacíos, el contenido se copia desde el lado que no está vacío.
- Si ambos tienen contenido, tú eliges la dirección. Hacer commit del workspace sobrescribe el contenido de la rama; actualizar el workspace desde Git sobrescribe el contenido del workspace.
Lee esa elección con atención. Una rama de Git siempre se puede restaurar a un commit anterior; un workspace sobrescrito por una actualización, no. Ante la duda, haz primero commit del workspace en una rama nueva.
La conexión con Git es por usuario. Cada persona que trabaja en un workspace conectado se autentica ante el proveedor Git con su propia cuenta. No compartas un personal access token entre todo el equipo.
Una rama por desarrollador o un workspace de desarrollo compartido
Hay dos configuraciones de desarrollo habituales.
Una rama por desarrollador (recomendado). Cada ingeniero usa la acción Branch out (crear rama) en el panel Source control. Fabric crea una nueva rama de Git a partir del último commit del workspace de origen y, o bien crea un nuevo workspace conectado a ella, o bien cambia uno existente. El nuevo workspace queda vinculado a su origen como branch workspace, lo que facilita volver a él. La ramificación selectiva permite llevar solo algunos elementos al nuevo workspace, siempre que también selecciones sus dependencias.
Ventajas: aislamiento real, pull requests pequeñas y enfocadas, y nadie sobrescribe el notebook de otra persona. Coste: más workspaces, y cada uno necesita sus propios datos para hacer pruebas.
Workspace de desarrollo compartido. Un único workspace conectado a una rama dev compartida, usado por un equipo pequeño. Es más sencillo y funciona cuando dos o tres personas se coordinan de cerca. Deja de funcionar a medida que crece el equipo: el cambio a medio terminar de una persona se convierte en el problema de todos, los commits mezclan trabajo que no tiene relación y las revisiones pierden sentido.
Un término medio práctico es un workspace de integración compartido que solo recibe cambios fusionados, más branch workspaces individuales para editar. Nadie edita directamente el workspace de integración; se actualiza desde main y sirve para comprobar que el trabajo fusionado encaja.
Sincronización: commit y actualización
Dos operaciones mueven los cambios entre el workspace y la rama.
Commit (workspace → Git). La sección Changes enumera los elementos modificados en el workspace. Puedes seleccionar qué elementos confirmar y añadir un mensaje. La vista de comparación también permite confirmar archivos concretos dentro de un elemento, en los elementos compatibles. Si la rama tiene commits nuevos que no has traído, el commit queda deshabilitado hasta que actualices. Fabric no te deja hacer commit sobre un estado de la rama que no has visto.
Actualización (workspace ← Git). La sección Updates enumera los elementos que han cambiado en la rama. A diferencia del commit, la actualización siempre aplica la rama completa hasta el último commit; no puedes elegir elementos individuales. Si el mismo elemento ha cambiado en ambos lados, la actualización queda deshabilitada hasta que se resuelva el conflicto.
Esa asimetría define la rutina diaria:
- Empieza el día con una actualización para que tu workspace coincida con la rama.
- Haz cambios, pruébalos en el workspace y luego haz commit de conjuntos de elementos pequeños y coherentes.
- Vuelve a actualizar antes de hacer commit si otra persona ha hecho push a tu rama.
Como los notebooks se guardan como archivos de código fuente, los mensajes de commit y los diffs se pueden leer en las pull requests. Mantén los notebooks enfocados y pasa los valores de ejecución mediante parámetros en lugar de editar el código para cada entorno; Parámetros de notebooks en Microsoft Fabric explica ese patrón.
Pull requests y main protegido
Fabric no ejecuta las pull requests; lo hace tu proveedor Git. Y eso es una ventaja: la revisión, las directivas de rama, los aprobadores obligatorios y la validación de compilación viven donde ya vive tu proceso de ingeniería.
Configuración recomendada:
- Protege
main. Exige pull requests, al menos un revisor y una compilación de validación correcta. La directiva de rama debe rechazar los commits directos desde un workspace amain. - Valida en la CI. Comprueba que las carpetas de los elementos están bien formadas, que el archivo de parámetros de despliegue es válido y que no se han colado ID de desarrollo en archivos que el despliegue no reescribe.
- Revisa las definiciones de los elementos, no solo el código. Un cambio en el JSON de un pipeline, un nuevo acceso directo de Lakehouse o una relación de un modelo semántico se pueden revisar igual que una celda de Python.
- Primero merge, luego despliegue. Después del merge, el pipeline de publicación despliega
mainen el siguiente entorno. Nadie copia elementos a mano entre workspaces.
Después de un merge, los desarrolladores actualizan sus workspaces (o crean un branch workspace nuevo desde main) para el siguiente cambio.
Escenarios de conflicto
Un conflicto se produce cuando el mismo elemento ha cambiado en el workspace y en la rama desde la última sincronización. El elemento muestra el estado Conflict, el commit queda deshabilitado y la actualización ofrece Resolve conflicts.
Tienes cuatro salidas:
- Elegir una versión por elemento en la interfaz. Accept incoming changes sobrescribe la versión del workspace con la de la rama. Keep current content conserva la versión del workspace, de la que luego hay que hacer commit. La vista de comparación muestra ambas versiones lado a lado antes de que decidas.
- Volver al último estado sincronizado. Undo devuelve los elementos en conflicto del workspace a su última versión sincronizada; en el lado de Git puedes revertir commits.
- Resolver en Git. Usa Checkout new branch para crear una rama a partir del último commit sincronizado, haz commit de los cambios de tu workspace en ella, fusiónala con la rama original en tu proveedor Git (resolviendo allí el conflicto) y luego vuelve a cambiar el workspace a la rama original.
- Actualización manual tras una actualización fallida. Una actualización también puede fallar sin un conflicto directo, por ejemplo cuando se ha cambiado el nombre de un elemento dependiente o se ha eliminado. Fabric muestra qué elemento ha fallado para que puedas corregirlo y volver a intentarlo.
La mayoría de los conflictos surgen de dos personas que editan el mismo elemento en la misma rama. Los branch workspaces por desarrollador los hacen poco frecuentes; cuando ocurren, resolverlos en Git con un merge normal suele ser la opción más clara.
Deriva del workspace
La deriva es la diferencia entre lo que dice la rama y lo que contiene el workspace. En un workspace de desarrollo, cierta deriva es normal: es tu trabajo sin confirmar. Los problemas empiezan cuando la deriva se vuelve permanente:
- Cambios sin confirmar que duran demasiado. El trabajo que pasa días en un workspace es invisible para los revisores y se pierde si el workspace se sobrescribe. Haz commit pronto en una rama de funcionalidad; una rama no cuesta nada.
- Elementos que la integración no rastrea. Los datos, las tablas y archivos del Lakehouse y las conexiones no están en Git. Documenta cómo obtiene un branch workspace nuevo los datos que necesita para hacer pruebas, o cada desarrollador se inventará su propia configuración.
- Workspaces desplegados conectados a Git. Un workspace de QA o de producción conectado a una rama da a la gente una segunda forma de cambiarlo. Mantén desconectados los workspaces desplegados y actualízalos solo a través del pipeline de publicación.
- Vinculaciones del Lakehouse predeterminado. Las definiciones de los notebooks llevan su Lakehouse predeterminado en los metadatos. Fabric puede vincular automáticamente los notebooks al Lakehouse correspondiente de otro workspace, pero comprueba la vinculación después de hacer branch out; un notebook de un branch workspace que sigue escribiendo en el Lakehouse del workspace de origen es una forma silenciosa de deriva.
Permisos
Los permisos vienen de dos sitios, y ambos deben permitir una acción:
| Acción | Workspace de Fabric | Proveedor Git |
|---|---|---|
| Conectar, desconectar, cambiar la conexión | Admin | Acceso de lectura al repositorio |
| Hacer commit de los cambios del workspace | Contributor o superior, con acceso de escritura a todos los elementos | Acceso de escritura, y la directiva de rama debe permitir un commit directo en esa rama |
| Actualizar el workspace desde Git | Contributor o superior, con acceso de escritura a todos los elementos | Acceso de lectura |
| Cambiar de rama o hacer checkout de una rama nueva | Admin, o Member/Contributor cuando el workspace lo permite | Lectura; permiso para crear ramas si es una rama nueva |
| Hacer branch out a otro workspace | Contributor o superior | Lectura y permiso para crear ramas |
Los Viewers no pueden ver la información de Git ni realizar acciones de Git. Los administradores del tenant deben habilitar la integración Git y, para Azure DevOps, las exportaciones entre regiones geográficas cuando el workspace y el repositorio están en regiones distintas. Lo que de verdad impide los commits directos son las directivas de rama en main, así que configúralas en el proveedor Git; Fabric las respeta.
Errores comunes
- Muchos desarrolladores en un solo workspace con una sola rama, esperando que Git los aísle.
- Hacer commit directamente en
maindesde un workspace porque nunca se configuraron las directivas de rama. - Tratar la integración Git como despliegue, conectando los workspaces de QA y producción a ramas y «actualizándolos».
- Esperar que Git restaure los datos. Restaura definiciones; las tablas y los archivos no se tocan.
- Elegir «actualizar el workspace» en la primera conexión sin comprobar qué lado tiene el trabajo más reciente.
- Commits enormes que mezclan elementos sin relación, lo que hace penosas la revisión y la resolución de conflictos. GitHub y Azure DevOps también aplican límites de tamaño a los commits.
- Compartir un único personal access token para todo el equipo en lugar de conexiones por usuario.
- Escribir valores de entorno a fuego en los notebooks, de modo que cada promoción requiere una edición en lugar de un parámetro.
Recomendación
Usa la integración Git para aquello para lo que está diseñada: versionar las definiciones de los elementos y moverlas entre el workspace de un desarrollador y una rama. Da a cada cambio activo su propia rama y su propio branch workspace, protege main con pull requests y validación, y trata un merge a main como la única entrada del despliegue.
Después, pasa el relevo a un proceso de despliegue que conozca los entornos. La integración Git responde a «qué ha cambiado y quién lo ha aprobado». fabric-cicd responde a «qué se está ejecutando en QA y en producción». Mantén separadas esas respuestas y ambas seguirán siendo fiables. Para ver cómo encajan estos workspaces en la plataforma completa, consulta Diseñar una arquitectura escalable de Microsoft Fabric.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Sigue aprendiendo
- Guía rápidaMonitorear pipelines y notebooks de FabricMonitorea pipelines y notebooks de Microsoft Fabric con Monitoring hub, Workspace Monitoring, el monitoreo de Spark, KQL, alertas y telemetría de capacidad para que los errores y las regresiones de rendimiento sean observables.Abrir guía rápida
- ArtículoContenido en inglésDeploy a Fabric Solution with Git, Deployment Pipelines and Database ProjectsA hands-on Microsoft Fabric lifecycle lab: version a workspace with Git integration, promote it from Dev to Test with a deployment pipeline and deployment rules, change a Warehouse schema as a database project, cause two controlled deployment failures and plan rollback.Leer artículo
¿Qué debería crear después?
Estoy construyendo Javi Builds alrededor de problemas reales que enfrentan los ingenieros de datos. Dime qué tema te gustaría ver después.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.