Análisis · Resiliencia del pipeline de publicación¶
Disparador: dos incidentes en un mes con el mismo modo de falla — el build
estricto del portal abortado por links rotos en un repo importado
(2026-08: Integrador, RFC con links relativos a código; 2026-09:
EcommerceV2Backend, carpeta desarrollo menu CMS/ con 19 links a documentos
inexistentes). En ambos casos la publicación de todos los repos quedó
congelada de forma silenciosa hasta el diagnóstico manual.
Diagnóstico¶
El portal es un único build que importa 10 repos: cualquier repo con docs rotos bloquea las actualizaciones de todos. El sitio publicado no se cae (queda la última versión buena), pero nada nuevo sale y nadie se entera salvo que mire Actions. Es la consecuencia negativa anticipada en el ADR-0002; con 3 repos era tolerable, con 10 repos y varios devs empujando docs la frecuencia crece.
Agravante de diagnóstico: al abortar, el plugin multirepo lanza un traceback
fantasma (FileNotFoundError: temp_dir por doble limpieza) que tapa el error
real. El error real es siempre la línea Aborted with N warnings in strict
mode, y los WARNING previos nombran archivo y link exactos.
Propuesta: tres capas¶
Capa 1 — Validar en origen (elimina ~90% de los casos)¶
Modificar el template notificar-portal.yml de docs-standard: un job
previo corre mkdocs build --strict sobre los docs del propio repo (cada
repo ya tiene su mkdocs.yml) y el repository_dispatch al portal solo se
ejecuta si pasa. El dev ve el error en su repo, en el push que lo introdujo;
el portal nunca recibe ese estado roto. Los dos incidentes reales habrían
sido atajados por esta capa.
Pendiente de decisión: propagación del workflow nuevo a los ~9 repos ya importados (actualización manual repo por repo, o en una sola pasada).
Capa 2 — Señal inmediata cuando el portal falla igual¶
En deploy.yml del portal, step con if: failure() que abra un issue en
docs-portal (requiere permissions: issues: write; usa el GITHUB_TOKEN
del workflow) indicando el repo culpable extraído del log. Complemento
opcional: cron de rebuild (diario o semanal) para autocuración cuando el fix
ya entró y nadie redisparó el workflow.
Capa 3 — Diagnóstico limpio¶
Actualizar la falla frecuente n.º 1 del runbook: el
traceback de temp_dir es ruido del plugin; leer los WARNING. Opcional:
cleanup: false en la config del plugin (elimina el traceback fantasma;
temp_dir/ ya está en .gitignore).
Fuera de esta propuesta (correctivo puntual)¶
El desbloqueo del incidente 2026-09 va en EcommerceV2Backend@develop:
mover docs/desarrollo menu CMS/ a docs/_borradores/desarrollo-menu-cms/
(son working files según el triage del estándar) o completar los documentos
faltantes. Hasta entonces, la publicación del portal sigue congelada.