Saltar a contenido

Runbook — Portal de documentación

Deploy

Dónde corre: Cloudflare Pages, proyecto docs-compulandia. El deploy es automático: push a main de docs-portal o repository_dispatch desde cualquier repo del alcance.

Deploy manual (si hace falta forzar una reconstrucción):

# Opción A: desde GitHub — pestaña Actions → "Deploy portal" → Run workflow
# Opción B: local
pip install -r requirements.txt
mkdocs build --strict
npx wrangler pages deploy site --project-name=docs-compulandia

Verificar que salió bien: abrir https://docs.compulandia.com.py y buscar un término de un repo recién agregado (ej: rollback).

Logs

Qué Dónde Cómo verlos
Build del sitio GitHub Actions del repo docs-portal Pestaña Actions, workflow "Deploy portal"
Deploys y tráfico Dashboard Cloudflare Workers & Pages → docs-compulandia → Deployments
Accesos denegados Dashboard Cloudflare Zero Trust → Logs → Access

Rollback

Cloudflare Pages conserva todos los deploys anteriores:

  1. Dashboard → Workers & Pages → docs-compulandia → Deployments.
  2. Elegir el deploy anterior estable → menú ⋯ → Rollback to this deployment.

No hay migraciones ni estado: el rollback es instantáneo y sin condiciones.

Fallas frecuentes

1. El build falla después de que un repo del alcance pusheó a main

  • Diagnóstico: en Actions, el paso mkdocs build --strict muestra el error con el nombre del repo importado (link roto, markdown inválido, docs/ movido).
  • Resolución: el fix va en el repo de origen, no en el portal. Si urge publicar, comentar temporalmente la línea !import de ese repo en mkdocs.yml y descomentar cuando esté arreglado. El sitio publicado nunca se cae por un build fallido: queda la última versión buena.

2. La búsqueda no encuentra contenido que existe en un repo

  • Diagnóstico: verificar que el repo esté en el nav: de mkdocs.yml y que el último build en Actions haya sido posterior al push del contenido. Revisar que el documento esté dentro de docs/ del repo origen.
  • Resolución: si falta el !import, agregarlo. Si el build quedó viejo, disparar el workflow manualmente (Run workflow). Verificar además que el repo origen tenga el workflow notificar-portal.yml con su token vigente.

3. Un miembro del equipo no puede entrar al portal

  • Diagnóstico: Zero Trust → Logs → Access muestra el intento y la regla que lo bloqueó.
  • Resolución: agregar su email (o el grupo) a la política de Access del dominio docs.compulandia.com.py. Si el token de sesión quedó viejo, indicarle cerrar sesión de Access y volver a autenticarse.