Módulo 7: Monitoring, Notifications y Advanced Patterns

1. Introducción: Monitoring, Notifications y Advanced Patterns

Descripción

Tu pipeline funciona. Hace lint, corre tests, ejecuta AI checks, buildea Docker, pushea al registry, y despliega a staging y production con approval gates. Técnicamente, es un pipeline completo. Pero hay tres problemas que nadie menciona hasta que duelen:

Problema 1: Visibilidad. El pipeline falló a las 2am porque OpenAI cambió el rate limit de la API. ¿Quién se enteró? Nadie. El developer lo descubrió 8 horas después cuando un compañero preguntó por qué staging tenía una versión vieja. No había alerta, no había notificación, no había forma de saber que algo estaba roto sin entrar manualmente a la pestaña Actions de GitHub.

Problema 2: Automatización temporal. Tu prompt regression baseline tiene 3 semanas. OpenAI actualizó gpt-4o-mini silenciosamente — los outputs cambiaron, tu baseline ya no refleja el comportamiento actual, y tu próximo PR va a fallar prompt regression por razones que no tienen nada que ver con tu código. Necesitas un scheduled job que recalcule baselines periódicamente, pero no lo tienes porque "no era urgente."

Problema 3: Mantenibilidad. Tienes 3 microservicios AI que comparten el mismo flujo de CI: lint → test → AI checks. Son 3 copias del mismo YAML con pequeñas variaciones. Cuando necesitas actualizar la versión de Python de 3.11 a 3.12, tienes que modificar 3 archivos en 3 repos. Uno se te olvida, y ese repo corre CI con la versión vieja durante semanas.

Este módulo resuelve los tres problemas. No son features opcionales — son lo que separa un pipeline funcional de un pipeline production-grade.

Contexto: ¿Dónde estamos en la guía?

Has completado 6 módulos. Tu pipeline tiene todas las capabilities core:

✅ Módulo 1: Workflow básico con GitHub Actions
✅ Módulo 2: Testing automatizado (pytest, matrix, caching)
✅ Módulo 3: AI-specific checks (prompt regression, cost estimation)
✅ Módulo 4: Secrets management (API keys, environments)
✅ Módulo 5: Docker build y push automatizado
✅ Módulo 6: Deployment pipelines (staging → approval → production)

Módulo	Qué aprenderás
Módulo 7	Monitoring, notifications, scheduled workflows, reusable patterns
Módulo 8	Proyecto integrador — pipeline production-grade completo

El Módulo 7 agrega la capa operacional: visibilidad, automatización temporal, y mantenibilidad. El Módulo 8 integra todo en un pipeline final.

Objetivo del módulo

Al completar este módulo serás capaz de:

✅ Analizar el historial de workflow runs para identificar patterns de failures recurrentes
✅ Configurar notificaciones a Slack cuando un pipeline falla (no cuando tiene éxito — eso es spam)
✅ Crear scheduled workflows con cron syntax para health checks nocturnos y baselines periódicas
✅ Diseñar reusable workflows con workflow_call que múltiples repos pueden usar
✅ Construir composite actions que encapsulan steps comunes en una sola action reutilizable
✅ Implementar matrix strategies avanzadas con include, exclude, y fail-fast
✅ Combinar notifications + scheduled workflows + reusable patterns en un pipeline operacional

Prerequisitos

Conocimiento requerido

✅ Módulos 1-6 completados: Tienes un pipeline funcional con CI, Docker, y deployment
✅ YAML fluido: Puedes escribir workflows sin errores de indentación
✅ GitHub Actions cómodo: Sabes navegar la UI de Actions, leer logs, debuggear failures

Opcional pero útil

Una cuenta de Slack donde puedes crear webhooks (free tier funciona)
Experiencia con cron jobs en Linux/macOS

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

¿Tu pipeline de los módulos anteriores corre exitosamente en GitHub Actions?
¿Sabes qué es un webhook?
¿Puedes crear un workflow YAML con múltiples jobs y dependencies (needs)?

Si respondiste "no" a alguna

Pipeline no funciona: Revisa el proyecto del Módulo 6 y asegúrate de que corre end-to-end
No sé qué es un webhook: Es simplemente una URL a la que envías un HTTP POST con datos. Slack te da una URL, tú envías un JSON con el mensaje, Slack lo muestra en un canal. Eso es todo.
No domino YAML con dependencies: Revisa las cápsulas 03 y 04 del Módulo 1

Contenido del módulo

Estas son las 8 cápsulas que componen este módulo:

Cápsula 02: Pipeline Monitoring

Cómo analizar el historial de workflow runs, identificar patterns de failures recurrentes, y usar el dashboard de GitHub Actions para entender la salud de tu pipeline. Antes de automatizar alertas, necesitas saber qué buscar manualmente.

Cápsula 03: Notifications — Slack y Email

Configura notificaciones inteligentes: Slack webhooks para failures, email como fallback, y la regla más importante — notifica failures, no successes. Incluye el workflow completo con slackapi/slack-github-action.

Cápsula 04: Scheduled Workflows y Cron

Cron syntax, scheduled workflows para AI systems: nightly prompt regression baselines, weekly cost reports, health checks periódicos. Los LLM providers actualizan modelos silenciosamente — scheduled checks detectan cambios antes de que rompan tu pipeline.

Cápsula 05: Reusable Workflows

workflow_call como trigger, inputs y secrets, cómo llamar un workflow desde otro repo. DRY para múltiples microservicios AI que comparten el mismo flujo de CI. Cuándo usar reusable workflows vs cuándo inline es suficiente.

Cápsula 06: Composite Actions

Custom actions que encapsulan múltiples steps en una sola action reutilizable. Estructura de action.yml, inputs, outputs. Cuándo usar composite actions vs reusable workflows (steps individuales vs workflows completos).

Cápsula 07: Matrix Strategies Avanzadas

include para combinaciones específicas, exclude para omitir combinaciones, fail-fast para control de failures. Ejemplo concreto: testear en Python 3.10+3.11+3.12 pero buildear Docker solo para 3.12.

Cápsula 08: Proyecto — Advanced CI/CD

Proyecto integrador del módulo. Agregas Slack notifications + scheduled nightly check + un reusable workflow al pipeline existente. El resultado es un pipeline operacional con visibilidad, automatización temporal, y componentes reutilizables.

Conexión con el proyecto de la guía

Este módulo agrega la capa operacional que tu pipeline necesita para ser production-grade:

Módulo 1: Workflow básico
    ↓
Módulo 2: + Testing automatizado
    ↓
Módulo 3: + AI-specific checks
    ↓
Módulo 4: + Secrets management
    ↓
Módulo 5: + Docker build & push
    ↓
Módulo 6: + Deployment staging → production
    ↓
Módulo 7: + Notifications, scheduling, reusable patterns  ← ESTÁS AQUÍ
    ↓
Módulo 8: Pipeline integrador production-grade

Sin este módulo, tu pipeline funciona pero es un sistema cerrado: nadie se entera cuando falla, no se mantiene solo, y no escala a múltiples repos. Con este módulo, tu pipeline se convierte en un sistema operacional: visible, automatizado, y mantenible.

Los tres pilares de este módulo

Pilar 1: Visibilidad

ANTES (sin monitoring/notifications):
  Pipeline falla → Nadie lo sabe → Horas perdidas → Usuario reporta bug

DESPUÉS (con monitoring/notifications):
  Pipeline falla → Slack alert en 30 segundos → Developer investiga → Fix en minutos

Visibilidad no es solo "ver que falló." Es saber qué falló, cuándo, con qué frecuencia, y si es un pattern recurrente. El dashboard de Actions te da el historial. Las notifications te dan la alerta en tiempo real.

Pilar 2: Automatización temporal

ANTES (sin scheduled workflows):
  OpenAI actualiza gpt-4o-mini → Tu baseline se desactualiza → 
  Próximo PR falla prompt regression → Developer confundido: "No cambié nada"

DESPUÉS (con scheduled workflows):
  Nightly: Re-ejecuta prompt baselines → Detecta cambio de modelo → 
  Actualiza baseline automáticamente → PRs siguen pasando

Los LLM providers actualizan modelos sin avisarte. Un prompt que costaba $0.02 ayer puede costar $0.05 hoy. Scheduled workflows detectan estos cambios antes de que afecten tu flujo de desarrollo.

Pilar 3: Mantenibilidad

ANTES (sin reusable workflows):
  3 repos × mismo CI YAML = 3 copias → Actualización = 3 PRs → 1 se olvida

DESPUÉS (con reusable workflows):
  1 workflow central → 3 repos lo llaman → Actualización = 1 PR → Propagación automática

Reusable workflows y composite actions eliminan duplicación. No es solo DRY por estética — es DRY por operabilidad. Cuando necesitas cambiar la versión de Python o agregar un step de security scanning, lo haces en un lugar y se propaga a todos los repos.

Un día con un pipeline operacional

Para entender qué construirás, este es un día típico con el pipeline que tendrás al final de este módulo:

6:00 AM — Scheduled nightly run
  Pipeline corre: health check → prompt regression → cost estimation
  Todo OK → No notification (solo silencio = buena señal)

9:15 AM — Developer hace push a feature branch
  Pipeline corre: lint → test → AI checks
  AI checks fallan: prompt regression detecta drift
  → Slack notification en #ci-cd-alerts:
    "❌ AI Checks failed on feature/update-prompts
     Job: prompt-regression
     Details: https://github.com/..."
  Developer investiga, actualiza baseline, re-push
  Pipeline pasa ✅ → No notification

2:30 PM — PR merge a main
  Pipeline corre: lint → test → AI checks → Docker build → deploy staging
  Todo OK ✅ → Deploy staging notification (opcional):
    "🚀 Deployed to staging: sha-abc1234"

3:00 PM — Approval gate aprobado
  Pipeline continúa: deploy production → health check
  Todo OK ✅ → Production deploy notification:
    "✅ Production deploy: sha-abc1234 (approved by @lead-dev)"

11:00 PM — Otro developer hace push
  Pipeline corre: lint → test → AI checks
  Docker build falla: Dockerfile tiene error de syntax
  → Slack notification:
    "❌ Docker Build failed on main
     Step: docker build
     Error: syntax error at line 14"

Todo esto funciona sin intervención manual. El equipo sabe qué está pasando sin tener que revisar GitHub Actions constantemente.

Analogía: El pipeline como una planta industrial

Piensa en tu pipeline como una línea de producción en una fábrica:

Fábrica	Pipeline
Sensores en máquinas	Pipeline monitoring
Alarmas cuando algo falla	Slack notifications
Mantenimiento programado	Scheduled workflows
Manuales de operación estandarizados	Reusable workflows
Piezas modulares intercambiables	Composite actions
Pruebas en múltiples condiciones	Matrix strategies

Una fábrica sin sensores ni alarmas produce defectos que nadie detecta hasta que llegan al cliente. Una fábrica sin mantenimiento programado funciona hasta que algo se rompe. Una fábrica sin estándares depende de que cada operario "sepa cómo" — y cuando se va, el conocimiento se pierde.

Tu pipeline es igual. Las herramientas de este módulo convierten tu pipeline artesanal en una operación industrial.

Setup técnico

Lo que necesitas para este módulo

# Verifica que tu pipeline de módulos anteriores funciona
# Ve a tu repo → Actions → verifica que el último run pasó

# Verifica gh CLI (necesario para métricas del pipeline)
gh --version
# Si no lo tienes: brew install gh (macOS) o sudo apt install gh (Ubuntu)

# Verifica que tienes los secrets configurados
# Settings → Secrets → Actions:
#   ✅ OPENAI_API_KEY
#   ✅ SLACK_WEBHOOK_URL (la crearás en este módulo si no la tienes)

Crear un Slack workspace (si no tienes uno)

Si no tienes un workspace de Slack, puedes crear uno gratis en slack.com/get-started. Solo necesitas:

Un workspace (puede ser personal)
Un canal para notifications (ej: #ci-cd-alerts)
Un Incoming Webhook (lo configurarás en la cápsula 03)

Si prefieres no usar Slack, puedes seguir las cápsulas con email notifications nativas de GitHub. Pero Slack es la recomendación — es instantáneo y todo el equipo lo ve.

Estructura mínima del proyecto

Tu proyecto de los módulos anteriores debería tener al menos:

mi-proyecto-ai/
├── .github/
│   └── workflows/
│       ├── ci.yml            ← Pipeline CI existente
│       └── deploy.yml        ← Pipeline deploy existente (Módulo 6)
├── scripts/
│   ├── evaluate_prompts.py   ← Prompt regression (Módulo 3)
│   └── estimate_costs.py     ← Cost estimation (Módulo 3)
├── src/
│   ├── main.py
│   └── utils.py
├── tests/
│   ├── test_main.py
│   ├── test_utils.py
│   └── prompt_test_cases.json
├── Dockerfile                ← Docker config (Módulo 5)
├── requirements.txt
└── pyproject.toml

Si te faltan archivos, revisa los proyectos de los módulos anteriores. Todo lo que construyas en este módulo se agrega sobre esta base.

Qué NO cubre este módulo

❌ Monitoring de la aplicación en runtime: Eso es la guía #18 (Monitoring & Observability). Este módulo monitorea el pipeline, no la app.
❌ PagerDuty, OpsGenie, o alerting platforms: Solo cubrimos Slack y email — suficiente para el scope de esta guía.
❌ Self-hosted runners: Usamos GitHub-hosted runners. Self-hosted runners son un tema de infrastructure.
❌ GitHub Apps para cross-repo automation: Cubrimos reusable workflows, no GitHub Apps con installation tokens.
❌ Complex orchestration (Argo Workflows, Tekton): GitHub Actions es nuestra plataforma exclusiva.

Evidencia de éxito

Al terminar este módulo, deberías poder:

Analizar el historial de runs de tu pipeline e identificar el job que más falla
Recibir una notificación en Slack cuando tu pipeline falla
Tener un scheduled workflow que corre health checks nocturnos
Crear un reusable workflow que otro repo puede llamar
Crear una composite action que encapsula tu setup de Python + dependencias
Configurar una matrix strategy con include para builds específicos
Explicar cuándo usar composite action vs reusable workflow

Si marcas todos los checks → estás listo para el Módulo 8.

Errores comunes al empezar este módulo

Antes de arrancar, estos son los errores más frecuentes que he visto:

Error 1: Notificar todo

❌ Notificar: build passed, tests passed, lint passed, deploy passed
   Resultado: 20 notificaciones al día → el canal se convierte en ruido → todos lo silencian

✅ Notificar: failures + production deploys
   Resultado: 1-2 notificaciones al día → cuando suena, es importante

La regla es simple: si todo va bien, silencio. Si algo falla, alerta inmediata. Las notificaciones de success solo tienen sentido para production deploys.

Error 2: Scheduled workflows sin propósito claro

❌ "Vamos a correr el pipeline completo cada noche"
   → Gasta minutos de Actions sin razón
   → Los failures nocturnos confunden porque no hubo cambios

✅ "Nightly: re-evaluar prompt baselines para detectar drift de modelo"
   → Propósito claro: detectar cambios en LLM providers
   → Si falla, sabes exactamente qué investigar

Cada scheduled workflow debe responder una pregunta específica. Si no puedes articular la pregunta, no necesitas el schedule.

Error 3: Reusable workflows prematuros

❌ Crear un reusable workflow cuando solo tienes 1 repo
   → Over-engineering → Más complejidad sin beneficio

✅ Crear un reusable workflow cuando 2+ repos comparten el mismo CI
   → DRY real → Beneficio tangible en mantenimiento

No extraigas un reusable workflow "por si acaso." Espera hasta que tengas duplicación real. Refactorizar después es más fácil que mantener abstracciones prematuras.

Qué construirás al final del módulo

Al completar el proyecto de la cápsula 08, tu pipeline tendrá estas capabilities nuevas:

Pipeline con Módulos 1-6:
  push → lint → test → AI checks → Docker → deploy staging → approve → deploy prod

Pipeline con Módulo 7 (lo que agregas aquí):
  push → lint → test → AI checks → Docker → deploy staging → approve → deploy prod
    │                                                                        │
    ├─► Failure en cualquier stage → Slack notification con detalles         │
    │                                                                        │
    └─► Deploy success → Slack confirmation                                  │
                                                                             │
  Nightly (scheduled):                                                       │
    health check → prompt regression → cost estimation                       │
    └─► Si detecta drift → Slack alert + artifact con diff                   │
                                                                             │
  Reusable CI workflow:                                                      │
    Cualquier otro repo puede llamar a tu CI con workflow_call               │
    └─► Mismo lint + test + AI checks, sin copiar YAML                      │

La diferencia entre "funcional" y "operacional" se siente cuando dejas de revisar GitHub Actions manualmente y el pipeline te dice lo que necesitas saber.

Siguiente módulo

El Módulo 8 (Proyecto Integrador — Production AI Pipeline) toma todos los componentes de los módulos 1-7 y los integra en un solo pipeline production-grade: lint → test → AI checks → Docker build → push → deploy staging → smoke tests → approval → deploy production — con notifications en cada stage, rollback automático, y monitoring del pipeline completo. La transición es directa: "Tienes todas las piezas individuales → ahora construyamos el pipeline completo."

Recursos adicionales

GitHub Actions Monitoring - Documentación oficial de monitoring
Slack Incoming Webhooks - Cómo crear webhooks en Slack
GitHub Actions Reusable Workflows - Documentación de workflow_call
GitHub Actions Composite Actions - Documentación de composite actions
Cron Expression Generator - Herramienta para crear expresiones cron
GitHub Actions Matrix Strategy - Documentación de matrix strategies

← Anterior8. Proyecto — Staging Deploy Pipeline Siguiente →2. Pipeline Monitoring