Introducción
En un artículo anterior analizamos las distintas estrategias para gestionar despliegues entre entornos en Microsoft Fabric, comparando varios modelos en función del papel que juegan Git y las canalizaciones de la plataforma. En ese post se presentaban tres enfoques distintos, desde los más sencillos hasta otros con mayor nivel de control y automatización, con el objetivo de entender qué aporta cada uno y en qué escenarios tiene sentido utilizarlos.
A partir de ese marco teórico, en el siguiente artículo bajamos a tierra el primer escenario práctico, utilizando GitHub únicamente como sistema de control de versiones y delegando el despliegue entre entornos en las canalizaciones nativas de Microsoft Fabric. En ese modelo, Git actúa como histórico y punto de colaboración, pero no decide qué contenido se despliega en los entornos superiores.
En el tercer artículo, dimos un paso más manteniendo una única rama en GitHub, donde Git deja de ser solo un histórico de cambios y pasa a convertirse en el punto de referencia que determina qué versión del contenido está lista para ser desplegada, incorporando despliegues automatizados mediante GitHub Actions.
En este nuevo post continuamos esa evolución natural del modelo. Partiendo del escenario anterior, veremos cómo se separa explícitamente el trabajo en curso del contenido aprobado, utilizando una rama Dev conectada al área de desarrollo de Fabric y una rama Main reservada para el estado aprobado, desde la cual se ejecutan los despliegues automatizados a otros entornos.
El objetivo es seguir trabajando con un escenario realista y progresivo, sin introducir complejidad innecesaria, mostrando paso a paso cómo aplicar este modelo en Microsoft Fabric, qué aporta respecto a enfoques anteriores y cuándo tiene sentido adoptar este nivel adicional de control.
Escenario de partida
Partimos de un entorno en el que el área de desarrollo de Microsoft Fabric está vinculada a un repositorio de GitHub, pero únicamente a una rama de trabajo (Dev). Si todavía no tienes configurada esta integración, puedes consultar el artículo anterior donde se explica el proceso paso a paso.
¡Importante! Recuerda asignar el área de trabajo de desarrollo a la rama Dev de GitHub, no a la rama Main.
En este modelo, el área de desarrollo se utiliza exclusivamente como entorno de edición y validación inicial. Los cambios realizados en ella se sincronizan con la rama Dev del repositorio, que representa el trabajo en curso y no tiene por qué estar siempre en un estado desplegable.
La rama Main del repositorio se reserva para reflejar el estado aprobado del contenido. El paso de Dev a Main marca explícitamente qué versión está lista para ser desplegada en otros entornos, separando de forma clara el trabajo en curso del contenido validado.
A partir de ese momento, cualquier despliegue a los entornos de Test o Producción se ejecuta siempre desde GitHub, mediante canalizaciones de compilación y despliegue externas, y nunca directamente desde el workspace de Fabric. Estas canalizaciones recuperan el contenido definido en la rama Main y, mediante las APIs de Microsoft Fabric, crean o actualizan los elementos correspondientes en cada entorno.
En este enfoque, Fabric no promueve contenido entre entornos ni toma decisiones sobre qué se despliega. Su papel se limita a recibir y materializar el estado declarado en el repositorio. Todo lo que llega a Main se considera aprobado, y la disciplina del proceso se apoya en políticas de rama, revisiones, validaciones automáticas y controles en el propio pipeline. El resultado es un flujo más controlado y predecible, que mantiene la simplicidad conceptual pero introduce una separación clara entre desarrollo y aprobado.
Despliegue desde GitHub mediante GitHub Actions
Para ejecutar los despliegues desde GitHub hacia los entornos de Test y Producción se utilizan GitHub Actions, el sistema de automatización y CI/CD nativo de GitHub.
GitHub Actions permite definir flujos de trabajo que se ejecutan a partir de eventos en el repositorio, como una ejecución manual, la creación de una versión o un cambio aprobado en la rama Main. Estos flujos se describen mediante archivos de configuración almacenados en el propio repositorio y forman parte del código versionado.
En este escenario, las Actions actúan como el motor de despliegue. Su responsabilidad es leer exclusivamente el contenido definido en la rama Main y, mediante scripts o llamadas a las APIs de Microsoft Fabric, crear o actualizar los artefactos correspondientes en los entornos de Test y Producción. El área de desarrollo se utiliza únicamente como entorno de trabajo y validación inicial, pero no participa en el proceso de despliegue ni actúa como origen del mismo.
Este enfoque refuerza la idea de Git como fuente única de verdad. Todo lo que se despliega procede del repositorio, todo lo que llega a Main se considera aprobado y cada despliegue es reproducible, auditable y automatizable.
Fabric, en este modelo, se limita a recibir las definiciones que le llegan desde el pipeline y a materializarlas en los distintos entornos. No existe promoción entre áreas de trabajo ni dependencias implícitas entre entornos.
¿Qué librería o método usaremos?
A la hora de automatizar el despliegue de artefactos en Microsoft Fabric existen varias alternativas, pero no todas cubren los mismos escenarios ni ofrecen el mismo nivel de madurez. En este ejemplo se han descartado deliberadamente algunas opciones “oficiales” en favor de una solución más completa y alineada con el tipo de artefactos que se gestionan.
Uso directo de las APIs de Fabric
Aunque Fabric expone APIs REST para la gestión de distintos objetos, actualmente estas APIs presentan limitaciones importantes. La más relevante es que no permiten desplegar todos los tipos de artefactos, siendo especialmente restrictivas con elementos clave como los notebooks. Esto hace que cualquier solución basada únicamente en APIs obligue a mantener flujos paralelos o procesos manuales, rompiendo el principio de automatización completa.
Fabric CLI
El Fabric CLI es una herramienta útil para escenarios interactivos y operaciones puntuales, pero no está pensada como motor de despliegue CI/CD completo. Su uso en pipelines introduce complejidad adicional, dependencia de comandos imperativos y una menor capacidad de control sobre el estado final del workspace. Además, no ofrece una abstracción clara para gestionar despliegues masivos ni limpieza de artefactos obsoletos de forma declarativa.
fabric-cicd como alternativa
La librería fabric-cicd, aunque no es todavía una herramienta oficial, resuelve de forma elegante muchas de estas carencias. Permite trabajar directamente sobre el contenido del repositorio, soporta un abanico mucho más amplio de artefactos y facilita operaciones críticas como la publicación completa y la eliminación de objetos huérfanos.
Su enfoque está claramente orientado a CI/CD, encajando de forma natural con GitHub Actions y con un modelo donde Git es la única fuente de verdad.
Por estos motivos, se ha optado por utilizar fabric-cicd como base del proceso de despliegue. Aunque no sea una solución oficialmente soportada, ofrece actualmente la mejor cobertura funcional para escenarios reales de automatización en Microsoft Fabric, especialmente cuando se gestionan notebooks, lakehouses y pipelines dentro de un mismo flujo.
Cuándo y cómo se despliega
En este modelo, Git actúa como la única fuente de verdad y los despliegues se ejecutan exclusivamente a partir del estado del repositorio mediante GitHub Actions. El momento de desplegar no depende del área de desarrollo ni del estado del workspace, sino de cuándo un conjunto de cambios pasa a considerarse aprobado en Git.
La aprobación del contenido se produce mediante la integración de una pull request desde la rama Dev a la rama Main. Ese merge marca de forma explícita qué versión está validada y lista para ser desplegada en otros entornos, separando claramente el trabajo en curso del contenido aprobado.
A partir de ese punto, el comportamiento del despliegue depende del entorno de destino. El despliegue al entorno de Test se ejecuta automáticamente tras el merge en Main, mientras que el despliegue a Producción se realiza de forma manual desde GitHub Actions, introduciendo un punto de control explícito antes de publicar cambios en un entorno crítico.
Configuración de los entornos
En este modelo, la ejecución de los despliegues se gestiona directamente desde GitHub mediante workflows diferenciados y el uso de environments para aislar configuración y credenciales por entorno. Esto permite automatizar el flujo sin perder control sobre cuándo y dónde se despliega el contenido aprobado.
El entorno de Producción se gestiona de forma distinta al de Test. Aunque parte del mismo estado aprobado en la rama Main, su despliegue no es automático y se ejecuta manualmente desde GitHub Actions. Esta decisión introduce un punto de control explícito antes de publicar cambios en Producción, separando claramente la validación técnica del contenido de la decisión de ponerlo en uso real.
GitHub permite asociar cada workflow a su environment correspondiente, lo que facilita la gestión independiente de credenciales y variables por entorno. En este enfoque, Test se beneficia de un flujo completamente automatizado, mientras que Producción queda protegida por una ejecución manual, equilibrando automatización y control y evitando despliegues accidentales en entornos críticos.
Acceder a la configuración del repositorio
Desde el repositorio de GitHub vinculado a Microsoft Fabric, accede a la sección de configuración del repositorio. Esta opción se encuentra en el menú superior bajo el apartado de Settings.
Crear entorno
Dentro de la configuración del repositorio, accede al apartado Environments. Aquí se definen los distintos entornos de despliegue que utilizarán las GitHub Actions.
Crea un nuevo entorno con el nombre Test. Este nombre será el que posteriormente utilice la acción de despliegue para identificar el entorno al que se va a publicar el contenido.
Configurar el entorno
Una vez creado el environment, GitHub nos lleva automáticamente a su pantalla de configuración. Desde aquí se definen las reglas que controlan cuándo y cómo se puede desplegar contenido a este entorno, así como los secretos y variables que utilizarán las GitHub Actions durante el despliegue.
En este caso práctico no se define ninguna restricción adicional sobre ramas o etiquetas. El despliegue al entorno de Test no depende de una aprobación manual, sino que se ejecuta automáticamente cuando una pull request desde la rama Dev es aprobada e integrada en la rama Main, de acuerdo con la lógica definida en el workflow de GitHub Actions.
El control de qué versión se despliega ya está garantizado por la separación entre la rama Dev, que representa el trabajo en curso, y la rama Main, que refleja el estado aprobado del contenido, así como por el propio workflow de GitHub Actions. Por este motivo, añadir restricciones adicionales en este punto no aporta valor y solo complica el modelo.
En el siguiente punto «Environment secrets» sí tiene sentido definir secretos de entorno. Estos valores serán utilizados por los workflows de GitHub Actions para autenticarse contra Microsoft Fabric y realizar el despliegue al entorno de Test. Al asociarlos al environment, GitHub garantiza que solo estarán disponibles durante la ejecución del despliegue y únicamente para los jobs que utilicen dicho entorno.
Para que GitHub pueda desplegar contenido en el entorno de Test sin intervención manual, es necesario proporcionar al pipeline una identidad con permisos suficientes en Microsoft Fabric. En este caso, se utiliza una aplicación registrada en Azure (Entra ID), creada específicamente para tareas de automatización.
Esta aplicación se autentica contra las APIs de Microsoft Fabric / Power BI mediante OAuth2 y dispone, como mínimo, de permisos de administrador sobre el área de trabajo. De este modo, puede crear o actualizar artefactos durante el proceso de despliegue, sin depender de la identidad de un usuario concreto.
Importante: Además de asignar permisos al Service Principal a nivel de workspace, es imprescindible habilitar explícitamente en el tenant de Microsoft Fabric / Power BI el uso de Service Principals para la ejecución de APIs. Si esta opción no está activada en los Tenant settings, las llamadas a la API fallarán con errores de tipo 401 Unauthorized, incluso cuando la autenticación sea correcta y la aplicación tenga rol de administrador sobre el workspace. Este es un requisito a nivel de tenant que suele pasarse por alto y que no puede resolverse únicamente desde el pipeline ni desde el código.
El secreto que se define a continuación corresponde al client secret de esa aplicación de Azure. GitHub Actions lo utilizará para obtener un token de acceso en tiempo de ejecución y ejecutar las llamadas necesarias al CLI de Fabric. Se debe llamar CLIENT_SECRET:
De forma adicional, se debe completar la configuración del environment con el resto de datos de la aplicación de Azure utilizada para el despliegue. Separar estos valores independientes facilita la lectura del workflow, mejora la mantenibilidad y permite rotar secretos sin tener que modificar la lógica del pipeline. En concreto, se suelen definir las siguientes:
- CLIENT_ID, correspondiente al Application (client) ID de la aplicación registrada en Entra ID.
- TENANT_ID, que identifica el tenant donde está registrada dicha aplicación.
Con esta configuración, el pipeline dispone de toda la información necesaria para autenticarse correctamente contra Microsoft Fabric en tiempo de ejecución.
Tambien es necesario crear una variable para definir el workspace de Microsoft Fabric sobre el que va a actuar el pipeline. Para ello, se crea una variable de entorno , llamada TARGET_WORKSPACE_ID, cuyo valor es el ID del área de trabajo.
El mismo proceso debe repetirse para el entorno de Producción (pasos 2 y 3). En este caso, se crea un nuevo environment en el repositorio, normalmente denominado Prod, y se configuran los mismos secrets que en el entorno de Test, pero utilizando los valores correspondientes a Producción y la variable con el nombre correspondiente al área de trabajo de Prod.
La aplicación de Azure asociada debe disponer, como mínimo, de permisos de administrador sobre el área de trabajo de Producción, y los identificadores (CLIENT_ID, TENANT_ID y CLIENT_SECRET) deben reflejar esa configuración. De este modo, cada entorno queda completamente aislado a nivel de credenciales y controlado de forma independiente desde GitHub.
Asociar los entornos al proceso de despliegue
Hasta este punto solo se ha preparado el terreno: el repositorio tiene definidos los entornos de Test y Producción, y cada uno dispone de las credenciales necesarias para poder desplegar contenido en Microsoft Fabric.
El siguiente paso consiste en conectar estos entornos con el proceso de despliegue, es decir, indicar a GitHub Actions en qué momento y bajo qué condiciones debe utilizar cada entorno.
Esto se realiza mediante uno o varios workflows de GitHub Actions, donde se define explícitamente el comportamiento de despliegue en función del estado del repositorio. En este escenario, el flujo de despliegue se articula a partir de la rama Main, que representa el estado aprobado del contenido.
El workflow se encarga de ejecutar automáticamente el despliegue al entorno de Test cuando una pull request desde la rama Dev es aprobada e integrada en la rama Main. Por su parte, el despliegue al entorno de Producción se define como una acción separada, asociada a su propio job y protegida mediante una aprobación explícita.
Cada job del workflow se asocia a su entorno correspondiente mediante la propiedad environment, lo que permite a GitHub aplicar automáticamente las reglas definidas para cada destino, como el uso de secretos específicos o la exigencia de aprobaciones manuales.
A partir de este momento, los entornos dejan de ser una configuración estática y pasan a formar parte activa del proceso de despliegue, integrándose directamente en la lógica del pipeline y reforzando la separación entre validación en Test y publicación en Producción.
Crear workflow de despliegue
En este paso se crea, por primera vez, el proceso de despliegue automático que conecta GitHub con Microsoft Fabric. Hasta ahora todo era preparación; a partir de aquí los entornos empiezan a utilizarse de forma efectiva dentro del flujo de CI/CD.
El objetivo de este primer workflow es concreto y deliberadamente acotado:
- Tomar el contenido aprobado en la rama Main
- Ejecutar automáticamente el despliegue al entorno de Test cuando se integra una pull request desde la rama Dev
- Utilizar el environment Test previamente configurado en el repositorio
El despliegue al entorno de Producción se trata como un paso independiente, protegido por una ejecución manual explícita, utilizando un workflow separado que se define a continuación.
Antes de entrar en el contenido del workflow, es necesario crear el fichero que va a definir este proceso de despliegue automático. En GitHub, todos los flujos de trabajo de GitHub Actions se almacenan dentro de la carpeta especial .github/workflows del repositorio.
En este caso, se crea un nuevo archivo YAML que contendrá la lógica de despliegue al entorno de Test. Este archivo debe residir en el repositorio para que GitHub pueda evaluarlo y ejecutarlo cuando se cumplan las condiciones definidas. El nombre del fichero no es relevante a nivel funcional, pero conviene que sea descriptivo para identificar claramente su propósito dentro del repositorio, por ejemplo deploy-test.yml, recuerda crearlo en la rama dev, no en la rama main.
El siguiente paso es definir el contenido del workflow, es decir, escribir el YAML que va a ejecutar el despliegue automático al entorno de Test utilizando GitHub Actions.
La responsabilidad de este workflow es clara y acotada: reaccionar a la aprobación e integración de una pull request desde la rama Dev a la rama Main y, a partir de ese momento, ejecutar el despliegue del contenido aprobado hacia el entorno de Test. No gestiona validaciones funcionales ni decisiones de negocio, únicamente automatiza el despliegue cuando se cumple la condición definida.
De este modo, el workflow no decide qué se despliega ni cuándo se aprueba el contenido, sino que se limita a materializar en Test el estado que ya ha sido validado y aceptado en el repositorio.
🚫 Acceso restringido
Para visualizar todo el contenido de este artículo, es necesario iniciar sesión.
Puedes hacerlo sin registrarte desde el lateral derecho o los comentarios, utilizando tu cuenta de Microsoft o Google.
Fin acceso restringido 🚫
Aunque el entorno de destino ya viene determinado por el workflow y por el environment configurado en GitHub, esta variable se mantiene por compatibilidad con la librería fabric-cicd y para facilitar futuras extensiones del script de despliegue sin depender del nombre del job o del workflow que lo invoque.
Una vez definido el workflow para el entorno de Test, se crea un segundo fichero independiente, por ejemplo deploy-prod.yml, destinado al despliegue en Producción. Este workflow no replica la lógica de ejecución del entorno de Test, ya que no está asociado a ningún evento automático del repositorio. Su única forma de ejecución es manual por lo que debes eliminar las lineas de la 3 a la 10 y la linea 14 if: github.event.pull_request.merged == true para evitar su ejecución automatica
El workflow de Producción se asocia a su propio environment de GitHub y utiliza las credenciales específicas de Prod. De este modo, el despliegue en Producción no depende de pull requests, merges ni otros eventos automáticos, sino que se ejecuta exclusivamente cuando se decide de forma explícita, manteniendo un control total sobre cuándo se publica el contenido en el entorno productivo.
Despliegue de artefactos
Una vez definida la estructura del repositorio y configurada la autenticación contra Microsoft Fabric, el siguiente paso es automatizar el despliegue de los artefactos almacenados en GitHub hacia el área de trabajo de destino.
Este proceso se apoya en la libreríafabric-cicd, que abstrae las llamadas a la API de Fabric y permite publicar, actualizar y limpiar objetos de forma declarativa a partir del contenido del repositorio.
El comportamiento del despliegue se controla mediante una serie de variables de entorno que se inyectan desde el workflow de GitHub Actions. Entre ellas destaca la variable MODE, que determina qué tipo de despliegue se va a realizar.
En este artículo se utiliza MODE: all, lo que indica que se desplegarán todos los artefactos presentes en el repositorio (pipelines, notebooks, lakehouses, dataflows, modelos semánticos, etc.), manteniendo el área de trabajo de destino sincronizada con el estado actual del código.
Aunque la librería permite otros modos más selectivos (por ejemplo, despliegues parciales orientados solo a reports), este enfoque completo simplifica el flujo y encaja perfectamente con un modelo de repositorio único y controlado, donde Git actúa como la única fuente de verdad.
Para ejecutar este despliegue, el workflow de GitHub Actions invoca un script Python incluido en el propio repositorio. En este ejemplo, el script de despliegue se almacena dentro de la carpeta scripts, siguiendo una estructura habitual que permite separar la lógica de automatización del resto del contenido versionado.
El repositorio se organiza de forma que la raíz contiene los artefactos de Microsoft Fabric (pipelines, notebooks, lakehouses, etc.), mientras que la carpeta scripts agrupa los elementos auxiliares necesarios para el proceso de CI/CD. El fichero deploy.py se almacena dentro de la carpeta scripts y es invocado desde el workflow de GitHub Actions. El script utiliza esta estructura para localizar, desde la raíz del repositorio, la carpeta fabric-items que contiene los artefactos a desplegar.
A continuación se muestra el contenido completo del script scripts/deploy.py, encargado de realizar el despliegue utilizando la librería fabric-cicd y las variables de entorno definidas en el workflow.
🚫 Acceso restringido
Para visualizar todo el contenido de este artículo, es necesario iniciar sesión.
Puedes hacerlo sin registrarte desde el lateral derecho o los comentarios, utilizando tu cuenta de Microsoft o Google.
Fin acceso restringido 🚫
Fichero de parametros
La librería fabric-cicd asume por diseño la existencia de un fichero de parámetros (parameter.yml) en el repositorio, ya que forma parte del flujo estándar de despliegue definido por la herramienta. Aunque en este escenario concreto no estemos utilizando todavía ningún parámetro dinámico ni sustituciones por entorno, es recomendable crear igualmente el fichero (aunque esté vacío o con una estructura mínima). De este modo se evita cualquier advertencia o error durante la ejecución del pipeline y se deja preparado el repositorio para futuras ampliaciones, como la parametrización de conexiones, nombres de recursos o configuraciones específicas por entorno.
Se debe crear en la raiz de la carpeta donde esten guardados los artefactos de fabric. En este ejemplo la raiz es la carpeta fabric-items y tiene el siguiente contenido:
find_replace: []
Estructura final del repositorio
A continuación se muestra la estructura final del repositorio, diseñada para soportar un modelo de control de código fuente y despliegue automatizado en Microsoft Fabric. La organización separa claramente los artefactos de Fabric exportados (fabric-items), los scripts de automatización (scripts) y los ficheros de configuración necesarios para el pipeline, como parameter.yml.
Esta estructura permite una trazabilidad completa de los cambios, facilita la gestión de despliegues entre entornos como Test y Producción, y deja el repositorio preparado para escalar el proceso de automatización sin introducir dependencias específicas del entorno en el código ni en los artefactos de Fabric.
Ejecución del workflow
En este escenario, el despliegue al entorno de Test no se ejecuta manualmente (aunque es posible), sino que se lanza de forma automática como consecuencia directa de una pull request desde la rama Dev a la rama Main. La pull request actúa como punto de validación y aprobación del contenido que se va a desplegar.
Una vez finalizado el trabajo en la rama Dev y realizados los pushes correspondientes, GitHub detecta que existen cambios pendientes de integrar y muestra un aviso en la página principal del repositorio. El primer paso consiste en hacer clic sobre la opción Compare & pull request, desde donde se inicia el proceso de creación de la pull request.
A partir de ese momento, se crea una pull request con destino a la rama Main. Tras revisar los cambios y aprobar la pull request, se procede a su integración. Este merge marca el momento en el que el contenido pasa a considerarse aprobado y listo para ser desplegado en otros entornos.
Una vez iniciada la creación de la pull request, GitHub muestra la pantalla de comparación de cambios entre ramas. En este punto es importante verificar que la rama base es Main y que la rama de comparación es Dev, ya que esta pull request es la que marcará qué cambios pasan a considerarse aprobados.
A continuación, se define un título para la pull request y, opcionalmente, una descripción que ayude a contextualizar los cambios incluidos. En este escenario no es necesario añadir información adicional, ya que la propia pull request actúa como mecanismo de validación del contenido desarrollado en Dev.
Tras crear la pull request, GitHub muestra el resumen de los commits incluidos y comprueba automáticamente si existen conflictos con la rama base. Si no hay conflictos y la integración es posible, se habilita la opción de realizar el merge.
El siguiente paso consiste en hacer clic sobre Merge pull request y confirmar la operación. En este momento, los cambios de la rama Dev se integran en la rama Main, que pasa a reflejar el nuevo estado aprobado del repositorio.
Tras completar el merge de la pull request, el workflow de despliegue a Test se ejecuta automáticamente, lo que puede verificarse desde la sección Actions del repositorio.
Una vez validado el contenido en el entorno de Test, el despliegue a Producción se ejecuta manualmente desde GitHub. Para ello, se accede a la pestaña Actions del repositorio, se selecciona el workflow de Producción y se lanza la ejecución utilizando la rama main, que representa el estado aprobado del código.
