Skip to content

Blog

Cómo Resolver Divergencias en Git: Sincronizando Ramas Local y Remota

El Problema

Al intentar hacer git pull, te encuentras con el siguiente error:

hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only

Este mensaje indica que tu rama local y la rama remota han divergido: ambas tienen commits únicos que la otra no tiene. Git necesita que decidas cómo combinar estos cambios.

¿Por Qué Ocurre?

La divergencia sucede cuando:

  1. Trabajas localmente y realizas commits en tu rama main
  2. Mientras tanto, cambios se fusionan en el remoto (por ejemplo, a través de Pull Requests)
  3. Ambas ramas tienen commits exclusivos que la otra no posee

Ejemplo visual:

Local:   A---B---C---L1
                      ^(tu commit local)
Remote:  A---B---C---R1---R2---R3
                      ^(commits del remoto vía PR)

Análisis: Identificar la Divergencia

Antes de resolver, es crucial entender qué ha divergido.

Paso 1: Sincronizar con el Remoto

git fetch origin main --tags

Este comando descarga los cambios del remoto sin fusionarlos.

Paso 2: Comparar Commits

Verifica qué commits están únicamente en cada lado:

# Commits que tienes localmente pero no están en el remoto
git log origin/main..main --oneline

# Commits que están en el remoto pero no tienes localmente
git log main..origin/main --oneline

Paso 3: Revisar los HEADs

# Ver el commit actual local
git rev-parse HEAD

# Ver el commit actual remoto
git rev-parse origin/main

Ejemplo Real

En nuestro caso, obtuvimos:

--- Commits en local, no en remoto ---
81e3b93 feat: add new feature for data processing

--- Commits en remoto, no en local ---
9d3e3e9 Merge pull request #42 from team/feature/update-docs
285a538 Complete documentation review - all documents validated
000b9cb Fix configuration and add new parameters
a7694d3 Initial implementation plan

Interpretación: El remoto tiene un PR fusionado con 4 commits que no tenemos localmente, y nosotros tenemos 1 commit local que el remoto no tiene.

Estrategias de Resolución

Existen tres estrategias principales:

1. Merge (Recomendado para Trabajo Colaborativo)

Cuándo usarlo: Cuando trabajas con un equipo y quieres preservar toda la historia, incluyendo los merge commits de PRs.

Ventajas:

  • ✅ Preserva la historia completa (incluidos merge commits)
  • ✅ Muestra claramente cuándo se integraron features
  • ✅ Más seguro: no reescribe historia

Desventajas:

  • ⚠️ Crea un commit de merge adicional
  • ⚠️ Historia no completamente lineal

Comando:

git merge origin/main --no-edit

Si prefieres revisar/editar el mensaje de merge:

git merge origin/main

2. Rebase (Para Historia Lineal)

Cuándo usarlo: Cuando trabajas solo o en una feature branch que aún no has compartido públicamente.

Ventajas:

  • ✅ Historia completamente lineal
  • ✅ Más limpia para revisar con git log

Desventajas:

  • ⚠️ Reescribe commits locales (cambian sus SHAs)
  • ⚠️ Puede causar problemas si ya compartiste estos commits
  • ⚠️ Pierdes el contexto de cuándo se integró el PR remoto

Comando:

git rebase origin/main

3. Fast-Forward Only (Restrictivo)

Cuándo usarlo: Cuando quieres asegurarte de que solo hagas pull si no hay divergencia.

Comando:

git config pull.ff only
git pull

Si hay divergencia, fallará y tendrás que decidir merge o rebase manualmente.

Solución Paso a Paso (Merge)

1. Analizar la Situación

# Sincronizar con remoto
git fetch origin main --tags

# Ver divergencias
echo "--- Commits locales únicos ---"
git log origin/main..main --oneline

echo "--- Commits remotos únicos ---"
git log main..origin/main --oneline

2. Decidir Estrategia

Para equipos colaborativos con PRs, merge es la opción más segura:

git merge origin/main --no-edit

3. Resolver Conflictos (Si Ocurren)

Si hay conflictos, Git te lo indicará:

Auto-merging some-file.md
CONFLICT (content): Merge conflict in some-file.md
Automatic merge failed; fix conflicts and then commit the result.

Pasos para resolver:

a) Abre el archivo con conflictos:

<<<<<<< HEAD
Tu versión local
=======
Versión del remoto
>>>>>>> origin/main

b) Edita manualmente para quedarte con el contenido correcto

c) Marca como resuelto:

git add some-file.md

d) Completa el merge:

git commit -m "Merge origin/main into main"

4. Verificar el Resultado

# Ver el log reciente
git log --oneline --graph -10

Deberías ver algo como:

*   3e1ed57 (HEAD -> main) Merge remote-tracking branch 'origin/main' into main
|\
| * 9d3e3e9 (origin/main) Merge pull request #42
| * 285a538 Complete documentation review
| * 000b9cb Fix configuration parameters
| * a7694d3 Initial implementation plan
* | 81e3b93 feat: add new feature for data processing
|/
* d140dce feat: improved monthly workflow

5. Empujar los Cambios

git push origin main

Salida esperada:

Enumerating objects: 15, done.
Counting objects: 100% (12/12), done.
Delta compression using up to 8 threads
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 1.08 KiB | 1.08 MiB/s, done.
Total 7 (delta 5), reused 0 (delta 0)
remote: Resolving deltas: 100% (5/5), completed with 4 local objects.
To https://github.com/tu-usuario/tu-repositorio.git
   9d3e3e9..3e1ed57  main -> main

Verificación Post-Merge

Comprobar Archivos Críticos

Si tienes workflows de CI/CD u otros archivos críticos, verifica su integridad:

# Buscar un patrón específico en un archivo
grep -n "specific_pattern" .github/workflows/deploy.yml

# O leer el archivo completo
cat .github/workflows/deploy.yml

Confirmar Sincronización

# Ambos deberían apuntar al mismo commit ahora
git rev-parse HEAD
git rev-parse origin/main

Configuración Permanente

Si quieres establecer una estrategia por defecto para futuros git pull:

Para Merge (Recomendado)

git config pull.rebase false

Para Rebase

git config pull.rebase true

Global (Todos tus Repos)

Añade --global:

git config --global pull.rebase false

Mejores Prácticas

✅ Hacer Fetch Frecuentemente

# Ejecutar cada mañana o antes de empezar a trabajar
git fetch origin

Esto te mantiene informado de cambios remotos sin afectar tu trabajo local.

✅ Trabajar en Feature Branches

En lugar de trabajar directamente en main:

git checkout -b feature/my-feature
# ... hacer commits ...
git push origin feature/my-feature
# Abrir PR en GitHub

Esto evita divergencias en main.

✅ Pull Antes de Push

git fetch origin
git status
# Si hay cambios remotos, decide merge o rebase
git pull
# Ahora puedes pushear
git push

⚠️ Evitar Force Push en Ramas Compartidas

# ❌ NUNCA en main compartido
git push --force origin main

# ✅ OK solo en tus feature branches
git push --force origin feature/my-feature

Casos Especiales

Si Hiciste Rebase por Error y Quieres Revertir

# Ver el reflog (historial de cambios de HEAD)
git reflog

# Volver a un estado anterior
git reset --hard HEAD@{2}

Si Quieres Descartar Tus Commits Locales

# ⚠️ CUIDADO: Esto descarta tus commits locales permanentemente
git reset --hard origin/main

Si Quieres Preservar Cambios Locales Sin Commit

# Guardar cambios temporalmente
git stash

# Sincronizar con remoto
git pull

# Recuperar tus cambios
git stash pop

Resumen: Checklist Rápido

  • Fetch: git fetch origin main --tags
  • Analizar: git log origin/main..main --oneline y git log main..origin/main --oneline
  • Decidir: Merge (preservar historia) vs Rebase (lineal)
  • Ejecutar: git merge origin/main o git rebase origin/main
  • Resolver: Conflictos si los hay
  • Verificar: git log --graph --oneline -10
  • Push: git push origin main
  • Confirmar: Archivos críticos intactos

Conclusión

La divergencia de ramas es un escenario común en equipos colaborativos. La clave está en:

  1. Entender qué ha divergido (análisis con git log)
  2. Elegir la estrategia correcta (merge para equipos, rebase para trabajo local)
  3. Verificar el resultado antes de hacer push

En entornos colaborativos con Pull Requests, merge es generalmente la opción más segura ya que preserva la historia completa y evita reescribir commits que otros pueden estar usando como base.

Referencias

Azure DevOps Pipelines: environments, approvals y seguridad de secretos

Resumen

Azure DevOps Pipelines permite CI/CD seguro con environments, approvals y gestión avanzada de secretos. Este post va directo: cómo definir environments, configurar approvals, proteger secretos y auditar despliegues.

¿Qué es Pipelines avanzado?

  • Environments para dev, test, prod
  • Approvals y checks antes de despliegue
  • Secure secrets (Key Vault, variable groups)
  • Auditoría y compliance
  • Integración con Azure Monitor

Arquitectura / Cómo funciona

flowchart LR
    Dev[Dev] --> Repo[Repo]
    Repo --> Pipeline[Pipeline]
    Pipeline --> Env1[Environment: Dev]
    Pipeline --> Env2[Environment: Prod]
    Pipeline -.-> KeyVault[Key Vault]
    Pipeline -.-> Monitor[Azure Monitor]

Definir environments y approvals

  1. Crear environment: 

    # Portal: Pipelines > Environments > New environment
# Ejemplo: "prod-env"

  2. Configurar approval: 

    environments:
  - name: prod-env
    resourceType: VirtualMachine
    approval:
      steps:
        - script: echo "Aprobado por admin"

  3. Checks avanzados:

  4. Deployment gates (Azure Monitor, REST API, Query Work Item)

Seguridad de secretos

  • Usar Azure Key Vault: 

    variables:
- group: kv-secrets
steps:
- task: AzureKeyVault@2
  inputs:
    azureSubscription: 'MySub'
    KeyVaultName: 'kv-prod'
    SecretsFilter: 'DbPassword,ApiKey'
    RunAsPreJob: true

  • Variable groups (portal): 

    # Pipelines > Library > Variable groups > Link secrets

  • Secure files (certificados, pfx): 

    # Pipelines > Library > Secure files

Auditoría y compliance

  • Auditar deployments: 

    az pipelines runs list --pipeline-name "prod-pipeline"

  • Monitorizar cambios: 

    az monitor activity-log list --resource-group $RESOURCE_GROUP

  • Alertas por cambios no aprobados: 

    az monitor metrics alert create --name alert-unapproved --resource-group $RESOURCE_GROUP --scopes /subscriptions/$SUB_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.DevOps/pipelines/prod-pipeline --condition "total UnapprovedDeployments > 0" --window-size 5m --action $ACTION_GROUP_ID

Buenas prácticas

  • Usar environments y approvals en todos los despliegues a prod
  • Proteger secretos en Key Vault o variable groups
  • Auditar deployments y cambios semanalmente
  • Integrar alertas con Monitor y Sentinel
  • Usar secure files para certificados

Costes

  • Azure DevOps: gratis hasta 1,800 min/mes
  • Key Vault: ~$0.03/secret/mes
  • Monitor: ~$2.30/GB

Referencias

20251020 azure service bus mensajeria

Resumen

Azure Service Bus es el servicio de mensajería empresarial de Azure. Permite desacoplar aplicaciones y servicios mediante colas y topics, ideal para arquitecturas distribuidas y microservicios. Este post va directo a admins y DevOps que necesitan integrar sistemas de forma fiable y segura.

¿Qué es Azure Service Bus?

Azure Service Bus es un servicio PaaS de mensajería que ofrece:

  • Colas (Queues) para comunicación punto a punto
  • Topics y subscriptions para pub/sub
  • Entrega garantizada y ordenada
  • Soporte para mensajes transaccionales y sesiones
  • Integración con RBAC y Managed Identities

Arquitectura / Cómo funciona

flowchart LR
  App1[Productor] -- Envia mensaje --> SB[Service Bus Queue]
  SB -- Recibe mensaje --> App2[Consumidor]
  SB -. Dead-letter .-> DLQ[Dead Letter Queue]
  • El productor envía mensajes a la cola
  • El consumidor los procesa de forma asíncrona
  • Mensajes fallidos van a la Dead Letter Queue

Uso práctico: crear y usar una cola

1. Crear un Service Bus Namespace y una cola

# Variables
RESOURCE_GROUP="my-rg"
LOCATION="westeurope"
SB_NAMESPACE="my-sb-namespace"
QUEUE="myqueue"

# Crear namespace
az servicebus namespace create \
  --resource-group $RESOURCE_GROUP \
  --name $SB_NAMESPACE \
  --location $LOCATION

# Crear cola
az servicebus queue create \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $SB_NAMESPACE \
  --name $QUEUE

2. Enviar y recibir mensajes (Python, passwordless recomendado)

import asyncio
from azure.servicebus.aio import ServiceBusClient
from azure.servicebus import ServiceBusMessage
from azure.identity.aio import DefaultAzureCredential

FULLY_QUALIFIED_NAMESPACE = "<namespace>.servicebus.windows.net"
QUEUE_NAME = "myqueue"

async def send_message():
  credential = DefaultAzureCredential()
  async with ServiceBusClient(FULLY_QUALIFIED_NAMESPACE, credential) as client:
    sender = client.get_queue_sender(QUEUE_NAME)
    async with sender:
      msg = ServiceBusMessage("Hola Azure Service Bus!")
      await sender.send_messages(msg)
    await credential.close()

async def receive_message():
  credential = DefaultAzureCredential()
  async with ServiceBusClient(FULLY_QUALIFIED_NAMESPACE, credential) as client:
    receiver = client.get_queue_receiver(QUEUE_NAME)
    async with receiver:
      async for msg in receiver:
        print("Mensaje recibido:", str(msg))
        await receiver.complete_message(msg)
    await credential.close()

# Ejecutar
asyncio.run(send_message())
asyncio.run(receive_message())

Más detalles y ejemplos oficiales:

Buenas prácticas / Seguridad

  • Usa Managed Identities en vez de connection strings
  • Activa el cifrado con claves gestionadas por el cliente (CMK) si es necesario
  • Configura reglas de red y firewall
  • Usa colas de dead-letter para mensajes no procesables
  • Monitoriza con Azure Monitor y alertas

Referencias

Terraform en Azure: detección y corrección de drift

Resumen

Cómo detectar y corregir drift en recursos Azure gestionados con Terraform. Post directo para admins y DevOps: comandos prácticos y ejemplos reproducibles.

¿Qué es el drift?

  • Cambios fuera de Terraform (portal, scripts, etc)
  • Recursos "fuera de sync" con el estado deseado
  • Impacto: errores, inseguridad, compliance roto

Arquitectura / Funcionamiento

flowchart LR
    TF[Terraform State] --> Azure[Azure Resource]
    Azure -.-> Portal[Portal]
    Azure -.-> Script[Script]
    TF -.-> Drift[Drift Detection]

Detección de drift

  1. Comprobar estado: 

    terraform plan

  2. Usar azurerm_resource_drifts: 

    resource "azurerm_resource_drifts" "example" {
  resource_id = azurerm_virtual_machine.example.id
}

  3. Validar con Azure Policy: 

    az policy state list --resource-group $RG --policy-assignment $POLICY

Corrección de drift

  1. Aplicar cambios: 

    terraform apply

  2. Forzar recreación: 

    terraform taint azurerm_virtual_machine.example
terraform apply

  3. Reimportar recursos: 

    terraform import azurerm_virtual_machine.example /subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.Compute/virtualMachines/xxx

Buenas prácticas

  • Auditar drift semanalmente
  • Usar Policy para detectar cambios manuales
  • Documentar excepciones
  • Validar con MCP y Terraform Registry

Referencias

Azure AD PIM: Just-In-Time y alertas avanzadas

Resumen

Cómo usar Privileged Identity Management (PIM) en Azure AD para acceso JIT y alertas de seguridad. Post directo para admins y arquitectos cloud.

¿Qué es PIM JIT?

  • Acceso Just-In-Time (JIT) a roles privilegiados
  • Alertas por uso sospechoso
  • Auditoría y compliance

Arquitectura / Funcionamiento

flowchart LR
    User[Usuario] --> PIM[PIM]
    PIM --> Role[Rol Privilegiado]
    PIM --> Alertas[Alertas]
    PIM --> Audit[Auditoría]

Configuración rápida

  1. Activar PIM: 

    az ad pim role assignment list

  2. Configurar alertas: 

    az ad pim alert list --role "Global Administrator"

  3. Acceso JIT: 

    az ad pim role assignment activate --role "Global Administrator" --duration 1

Auditoría y compliance

  • Revisar logs: 

    az ad pim audit list

  • Alertas automáticas: 

    az monitor metrics alert create --name alert-pim --resource-group $RG --scopes /subscriptions/$SUB_ID/resourceGroups/$RG/providers/Microsoft.Authorization/roleAssignments --condition "total SuspiciousPIMActivations > 0" --window-size 5m --action $ACTION_GROUP_ID

Buenas prácticas

  • Usar PIM para todos los roles críticos
  • Configurar alertas y auditoría
  • Revisar logs semanalmente
  • Validar con MCP

Referencias

  • in Power BI
  • 4 min read

Power BI On-Premises Data Gateway: guía práctica (instalación estándar)

Resumen

Esta entrada explica de forma práctica qué es el Power BI On-Premises Data Gateway Standard, su arquitectura básica, y cómo realizar una instalación estándar y configurarlo para refrescos y conexiones seguras desde el servicio de Power BI. Está orientada a administradores y responsables de plataforma que necesiten conectar fuentes de datos locales a Power BI sin usar soluciones de red avanzadas (no cubre la instalación en Virtual Network Data Gateway ni escenarios sovereign).

¿Qué es el On-Premises Data Gateway?

El On-Premises Data Gateway es un componente que actúa como puente entre los servicios cloud de Microsoft (por ejemplo, Power BI, Power Automate, Power Apps) y tus datos que residen en la red local o en entornos no accesibles públicamente. Proporciona un canal saliente seguro (TLS) para permitir conexiones desde la nube hacia los orígenes de datos on‑premises sin abrir puertos entrantes en tu red.

Principales funciones:

  • Habilitar refrescos programados de datasets de Power BI.
  • Soportar consultas en vivo (DirectQuery/Live Connection) hacia orígenes compatibles.
  • Permitir que flujos y aplicaciones en cloud accedan a bases de datos y servicios internos.

Arquitectura básica

  • Gateway instalado en uno o varios servidores dentro de la red local.
  • El servicio gateway establece conexiones salientes a los endpoints de Microsoft (no requiere inbound).
  • En producción, se recomienda desplegar gateways en modo cluster (alta disponibilidad) y definir data sources centralizados en el panel de administración de Power BI.

Diagrama (simplificado)

flowchart LR
  PB["Power BI Service"]
  AZ["Azure Relay / Service Bus"]
  GW["On-Premises Gateway"]
  DB["Origen de datos"]
  DB --> GW
  GW --> | TLS saliente | AZ
  AZ --> PB

Arquitectura: Gateway en cluster (alta disponibilidad)

flowchart LR
  subgraph Cloud["Servicio Cloud"]
    PB["Power BI Service"]
  end

  subgraph Cluster["Cluster de Gateways (HA)"]
    GW1["Gateway - Nodo 1"]
    GW2["Gateway - Nodo 2"]
    GW3["Gateway - Nodo N"]
  end

  subgraph OnPrem["Red On-Premises"]
    DB["(Origen de datos)"]
  end
  AZ["Azure Relay / Service Bus"]


  GW1 --- GW2
  GW2 --- GW3
  AZ --> PB
  Cluster --> | TLS saliente | AZ
  DB --> Cluster

Note

Físicamente el Gateway establece conexiones salientes TLS hacia los servicios de Azure (Azure Service Bus / Azure Relay). Las solicitudes brokered se mantienen gracias a las conexiones salientes iniciadas por el gateway.

Instalación (instalación estándar)

Los pasos siguientes describen una instalación típica y segura de un Gateway estándar:

  1. Descargar el instalador oficial

  2. Descargar el instalador del gateway desde el sitio oficial de Microsoft.

  3. Ejecutar el instalador en el servidor destinado

  4. Ejecuta el instalador con privilegios de administrador.

  5. Acepta los términos y elige la instalación estándar cuando se solicite.

  6. Iniciar sesión y registrar el gateway

  7. Al finalizar la instalación se abrirá un asistente que solicita iniciar sesión con una cuenta organizativa (Entra ID).

  8. Registra el gateway en tu tenant y proporciona un nombre descriptivo para el gateway.

  9. Definir la clave de recuperación

  10. El asistente pedirá que crees una "recovery key". Guárdala en un lugar seguro: es necesaria para migrar o restaurar el gateway.

  11. Elegir cuenta de servicio (opcional)

  12. Puedes ejecutar el servicio con la cuenta de sistema local por defecto o configurar una cuenta de dominio/service account con los permisos mínimos necesarios para acceder a los orígenes de datos.

  13. Verificar conectividad

  14. Asegúrate de que el servidor puede establecer conexiones TLS salientes a los endpoints de Microsoft (comprobar reglas de firewall/proxy si existen).

  15. (Opcional) Agregar nodos al cluster

  16. Para alta disponibilidad, instala el gateway en otro servidor y en lugar de registrar un nuevo gateway selecciona unirte al cluster existente.

Configuración en el servicio Power BI

  1. Abrir el portal de Power BI y acceder a "Manage gateways" (Administrar gateways).
  2. Crear y/o revisar Data Sources dentro del gateway: especifica el tipo de origen (SQL Server, Analysis Services, etc.), cadena de conexión, y credenciales.
  3. En los datasets de Power BI: configurar el dataset para usar el gateway correspondiente y programar refrescos.
  4. Para DirectQuery/Live connection: asegúrate de que el data source esté correctamente configurado y que el usuario tenga permisos adecuados.

Consejos prácticos:

  • Centraliza la definición de data sources para facilitar el mantenimiento.
  • Usa credenciales de tipo "service principal" o cuentas administradas cuando el origen lo permita y por seguridad.

Buenas prácticas y seguridad

  • Alta disponibilidad: despliega gateways en cluster para evitar puntos únicos de fallo.
  • Mínimos privilegios: la cuenta que use el gateway solo debería tener los permisos necesarios en los orígenes de datos.
  • Key management: guarda la recovery key en un almacén seguro y documenta el proceso de recuperación.
  • Parches y mantenimiento: aplica actualizaciones del sistema operativo y del gateway según las políticas de tu organización.
  • Monitorización: habilita logs y métricas para detectar problemas de rendimiento y errores en los refrescos.
  • Red y firewall: permite únicamente el tráfico saliente necesario hacia los endpoints de Microsoft y evita abrir puertos entrantes.

Monitorización y diagnóstico

  • Revisa el panel de estado del gateway en Power BI Service para incidentes y estado de los nodos.
  • Examina los registros locales del gateway (ubicación estándar indicada por el instalador) para errores detallados.
  • Utiliza contadores de rendimiento (CPU, memoria, latencia de red) en el servidor para diagnosticar cuellos de botella.
  • Para problemas de refresco: revisa el historial de refrescos del dataset en Power BI y los detalles del error proporcionados por el servicio.

Referencias y lecturas recomendadas

  • Documentación oficial de Microsoft (Power BI - On-premises data gateway): https://learn.microsoft.com/power-bi/connect-data/service-gateway-onprem

Documentar con EPAC

EPAC tiene una opción muy útil llamada "Document All Assignments" que genera Markdown y CSV con todas las asignaciones de policy. Pero hay dos detalles importantes que conviene saber:

1) Antes no se podían excluir tipos enteros de scope (por ejemplo: todas las subscriptions o resourceGroups) desde la configuración.

2) He subido una PR para solucionarlo: https://github.com/Azure/enterprise-azure-policy-as-code/pull/1056

Aquí lo que cambia, rápido y claro.

Problema

Si usas documentAllAssignments y quieres evitar documentar todo lo que hay a nivel de suscripción o de resource groups, la versión anterior obligaba a listar cada id con skipPolicyAssignments o a procesar el CSV resultante. En entornos grandes eso resulta muy tedioso y genera mucho ruido en los informes.

Qué hace la PR #1056

  • Añade excludeScopeTypes en la configuración de documentAllAssignments. Con esto se puede indicar que no se documenten assignments que estén en subscriptions o en resourceGroups.

  • Añade StrictMode (switch) en los scripts. Por defecto está activado. Si lo desactivas (-StrictMode:$false) el script no aborta cuando falta alguna definición; registra avisos y continúa. Útil en pipelines de prueba.

  • Mejora el parsing y el manejo de skipPolicyAssignments/skipPolicyDefinitions (funcionan mejor con arrays u objetos) y corrige bugs menores (p. ej. convertir markdownMaxParameterLength a entero).

PR: https://github.com/Azure/enterprise-azure-policy-as-code/pull/1056

Antes / Después (ejemplo práctico)

Antes tenías que usar algo así:

{
  "documentAssignments": {
    "documentAllAssignments": [
      {
        "pacEnvironment": "EPAC-Prod",
        "skipPolicyAssignments": [],
        "skipPolicyDefinitions": ["/providers/.../policySetDefinitions/..."]
      }
    ]
  }
}

Después basta con añadir excludeScopeTypes:

{
  "documentAssignments": {
    "documentAllAssignments": [
      {
        "pacEnvironment": "EPAC-Prod",
        "excludeScopeTypes": ["subscriptions", "resourceGroups"],
        "skipPolicyAssignments": [],
        "skipPolicyDefinitions": ["/providers/.../policySetDefinitions/..."]
      }
    ]
  }
}

Y si quieres pruebas rápidas sin que el pipeline falle por referencias rotas:

./Build-PolicyDocumentation.ps1 -StrictMode:$false

Recomendaciones prácticas

  • Usa excludeScopeTypes para reducir ruido cuando necesites una vista global.

  • No confundas excludeScopeTypes con exemptions: esto solo evita que se documente; no evita que la policy se aplique. Para eso usa exemptions.

  • Mantén StrictMode activado en producción (ayuda a detectar referencias rotas).

  • Usa skipPolicyAssignments para exclusiones puntuales que conozcas por id.

Cierre

La mejora es pequeña pero práctica: menos limpieza manual, informes más útiles. Si quieres puedo:

  • Añadir un ejemplo real con IDs/outputs.
  • Hacer build local del sitio y comprobar cómo queda el Markdown final.

PR de referencia: https://github.com/Azure/enterprise-azure-policy-as-code/pull/1056