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.

A partir de ese marco teórico, en el artículo anterior a este bajamos a tierra el primero de esos escenarios con un ejemplo práctico completo: GitHub utilizado únicamente como sistema de control de versiones, delegando el despliegue entre entornos en las canalizaciones nativas de Microsoft Fabric.

En este nuevo post damos un paso más dentro de ese mismo contexto. Manteniendo una única rama en GitHub, veremos cómo GitHub 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 en otros entornos.

El objetivo es seguir trabajando con un escenario realista y comprensible, sin introducir complejidad innecesaria, mostrando paso a paso cómo aplicar este modelo en Microsoft Fabric y cuándo tiene sentido utilizarlo.

Escenario de partida

Partimos de un entorno en el que el área de desarrollo de Microsoft Fabric ya está vinculada a un repositorio de GitHub. Si todavía no tienes configurada esta integración, puedes consultar este otro artículo donde se explica el proceso paso a paso. La conexión se ha realizado utilizando una única rama, main, que actúa como referencia del contenido versionado.

En este modelo, Git se convierte en el único punto de aprobación y despliegue, eliminando cualquier dependencia del estado del área de desarrollo. Todo el contenido que llega a los entornos de pruebas y producción procede exclusivamente de la rama main, que actúa tanto como rama de trabajo como rama aprobada.

El área de desarrollo se utiliza únicamente como entorno de edición y validación inicial. Los cambios realizados en ella se sincronizan directamente con la rama main del repositorio, sin pasar por ramas intermedias. A partir de ese momento, cualquier despliegue a Test o Producción se ejecuta siempre desde GitHub, nunca desde el workspace.

Las canalizaciones de compilación y despliegue externas son las encargadas de recuperar el contenido definido en la rama main y, mediante las APIs de Microsoft Fabric, crear o actualizar los elementos correspondientes en las áreas de pruebas y producción. Fabric no promueve contenido entre entornos ni toma decisiones sobre qué se despliega; se limita a recibir el estado declarado en el repositorio.

En este enfoque, todo lo que está en main se considera aprobado. La disciplina del proceso se apoya en políticas de rama, revisiones obligatorias, validaciones automáticas y controles en el propio pipeline, en lugar de en una separación explícita de ramas. El resultado es un flujo más simple y directo, típico de estrategias trunk-based, pero que exige un mayor rigor en la gestión de cambios.

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 automáticamente cuando ocurre un evento en el repositorio, como un push a la rama main, la creación de una versión o la aprobación de un cambio. 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 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 workspace de desarrollo no participa en este proceso ni sirve como origen del despliegue.

Este enfoque refuerza la idea de Git como fuente única de verdad:

• Todo lo que se despliega procede del repositorio
• Todo lo que está en main se considera aprobado
• Todo 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.

Cuándo y cómo se despliega

En un modelo donde GitHub actúa como fuente de verdad y los despliegues se ejecutan mediante GitHub Actions, el momento de desplegar no debería estar ligado directamente a un simple push a la rama main. Aunque técnicamente es posible automatizarlo, hacerlo sin control introduce riesgos innecesarios.

La opción más equilibrada en este escenario es desplegar mediante una aprobación explícita, incluso aunque el proceso esté automatizado.

En la práctica, el flujo habitual es el siguiente: los cambios se confirman en la rama main, quedando así aprobados desde el punto de vista del control de versiones. A partir de ese momento, el despliegue a Test queda preparado, pero no se ejecuta hasta que una persona responsable lo autoriza e igualmente el paso posterior a Pro.

GitHub permite definir entornos protegidos, como Test y Producción, que requieren una aprobación manual antes de ejecutar cualquier acción sobre ellos. De este modo, la canalización puede estar completamente automatizada, pero el paso a Test y Pro queda bloqueado hasta que alguien valida que ese estado de main está listo para ser desplegado.

Este enfoque ofrece un buen equilibrio entre control y automatización:

• Git sigue siendo la única fuente de verdad del contenido desplegable
• El despliegue no se produce de forma accidental
• Queda registro de quién aprueba y cuándo se realiza el despliegue

Además, permite separar claramente dos conceptos que conviene no mezclar: aprobar un cambio en GitHub y decidir cuándo desplegarlo en un entorno concreto.

En equipos con mayor madurez, esta aprobación puede estar respaldada por validaciones automáticas previas, pero incluso en esos casos suele mantenerse una aprobación explícita para el entorno de Test como punto de control adicional.

Configuración de los entornos

En este modelo, los entornos de GitHub se utilizan principalmente para aislar credenciales y variables por entorno, no como mecanismo de automatización del despliegue.

Dado que los workflows se ejecutan únicamente de forma manual mediante workflow_dispatch, la aprobación del despliegue no depende de reglas automáticas ni de eventos del repositorio, sino de la decisión explícita de ejecutar el workflow correspondiente.

Los environments permiten, aun así, mantener separada la configuración de Test y Producción y garantizar que cada despliegue utiliza las credenciales adecuadas para el área de trabajo de destino.

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 a Test no depende de un filtro automático de ramas, sino de una aprobación explícita por parte de una persona responsable.

El control de qué versión se despliega ya está garantizado por el uso de una única rama (main) y por el propio workflow de GitHub Actions, por lo que 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 tras la aprobación manual y únicamente durante la ejecución del despliegue.

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 hemos preparado el terreno: el repositorio tiene definidos los entornos (Test y Producción) y cada uno dispone de las credenciales necesarias para poder desplegar en Microsoft Fabric.

El siguiente paso consiste en conectar esos entornos con el proceso de despliegue, es decir, indicar a GitHub Actions cómo debe utilizar cada entorno durante una ejecución manual.

Esto se hace mediante workflows independientes de GitHub Actions, uno por entorno, que se ejecutan de forma manual desde la rama main. Cada workflow define explícitamente el entorno de destino y utiliza las credenciales asociadas a dicho environment para realizar el despliegue.

En este modelo no existe un flujo automático ni encadenado entre entornos, ni jobs que promuevan contenido de Test a Producción. Cada despliegue se lanza de manera explícita cuando se considera oportuno, utilizando el workflow correspondiente al entorno deseado.

A partir de este momento, los entornos dejan de ser solo una configuración estática y pasan a formar parte activa del proceso de despliegue, proporcionando aislamiento de credenciales y control total sobre cuándo y dónde se publica el contenido.

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; aquí es donde los entornos empiezan a usarse de verdad.

El objetivo de este primer workflow es muy concreto y limitado:

• Tomar el contenido aprobado en la rama main
• Ejecutar un despliegue manual hacia un entorno concreto (Test o Producción), utilizando el workflow correspondiente.
• Utilizar el environment Test y Pro que ya hemos configurado

Antes de entrar en el contenido del workflow, es necesario crear el fichero que va a definir el 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, vamos a crear un nuevo archivo YAML directamente en la rama main, que contendrá la lógica de despliegue al entorno de Test. El nombre del archivo 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

El siguiente paso es definir el contenido del workflow, es decir, escribir el YAML que va a ejecutar el despliegue a Test usando GitHub Actions. Su única responsabilidad es decidir cuándo y en qué condiciones se lanza un despliegue a Test.

🚫 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 ya viene determinado por el workflow y el environment de GitHub, esta variable se mantiene por compatibilidad con la librería fabric-cicd y para facilitar futuras extensiones del script sin depender del nombre del job.

Para el entorno de Producción se crea un segundo workflow independiente, normalmente denominado deploy-prod.yml.

Aunque reutiliza el mismo script de despliegue y la misma estructura técnica que el workflow de Test, se trata de una ejecución completamente separada y lanzada de forma manual cuando se considera oportuno. En este workflow es necesario ajustar las variables y credenciales para que apunten al entorno de Producción, sustituyendo los valores utilizados en Test por los correspondientes al área de trabajo productiva.

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 ejecuta desde la raíz del repositorio y utiliza esa estructura para localizar y publicar el contenido correspondiente en el área de trabajo de destino.

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 de 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, facilita la ejecución controlada de despliegues en distintos entornos (Test, Producción, etc.) y deja el repositorio preparado para escalar el proceso de despliegue sin introducir dependencias específicas del entorno en el código.

Ejecución del workflow

En este escenario, el despliegue no se ejecuta de forma automática a partir de eventos del repositorio, sino que se lanza manualmente desde GitHub cuando se considera necesario. Este enfoque permite un control total sobre el momento del despliegue y resulta especialmente útil en modelos más simples o en fases iniciales de adopción de CI/CD.

Para ejecutar el despliegue manualmente, es necesario acceder al repositorio en GitHub y dirigirse a la pestaña Actions. En el panel lateral se muestran los workflows disponibles. Seleccionando el workflow de despliegue correspondiente, se habilita la opción Run workflow.

Desde esta pantalla se puede elegir la rama desde la que se ejecutará el workflow, aunque es nuestro ejemplo solo tenemos la rama main, y confirmar la ejecución. A partir de ese momento, GitHub lanza el pipeline definido, utilizando las credenciales y configuraciones asociadas al environment configurado en el workflow.

Al finalizar la ejecución, el estado del workflow queda visible en la pestaña Actions. Accediendo a la ejecución se pueden consultar en detalle los pasos y logs de cada fase del despliegue.