Documentación que se publica sola, después de que digo que sí

El problema de la documentación en un homelab no es escribirla. Es que la escritura nunca vale la pena en el momento en que tienes el contexto, y para cuando vale la pena ya no tienes el contexto.

Así que la pipeline funciona al revés, partiendo del artefacto. El sistema detecta un vacío — un servicio sin página, un respaldo sin restauración documentada, un monitor apuntando a nada — redacta la página y abre un pull request. Luego se detiene.

La cadena

detectar un vacío    -> un registro de propuesta, en un outbox en tiempo de ejecución, ignorado por git
preparar             -> una rama y un pull request borrador, nunca mergeado
yo reviso y mergeo   -> la página llega a main
publicar-al-mergear  -> la página mergeada aparece en la wiki

Cuatro pasos, y yo estoy en el paso tres. La herramienta del paso dos no tiene ninguna llamada para mergear — ni deshabilitada, ni marcada. La capacidad está ausente, lo cual es una garantía más fuerte que un interruptor apagado.

Publicar solo lee main

El publicador se niega a correr desde cualquier rama que no sea la rama por defecto. Esto suena a precaución extrema hasta que consideras para qué sirve una wiki: es la copia que la gente lee en lugar de leer el repo. Una página wiki publicada desde una rama no mergeada es una afirmación sobre el sistema que ninguna revisión aprobó, sentada justo donde la gente va cuando confía en algo.

Optar es por documento — una página lleva una bandera que dice que puede publicarse después del merge — y la republicación se deduplica por hash de contenido, así que un merge que no cambió la página no produce ninguna escritura en la wiki.

Tres cosas que la API de la wiki me enseñó a la mala

El contenido solo llega a través del endpoint de importación. Crear una página y actualizar una página aceptan un cuerpo y ambos lo ignoran silenciosamente. Así que republicar es realmente borrar, luego reimportar, lo que significa que la ruta de "actualizar" en mi publicador es una operación destructiva con un nombre amigable.

Y el borrado es un borrado duro. No hay papelera, ni bandera suave. La primera vez que lo aprendí fue sobre una página que quería conservar.

Las verificaciones de existencia necesitan una ruta, no un título. Mi primera verificación de duplicados preguntaba "¿existe una página con este título?" Varias de mis páginas se llaman legítimamente "Backup and Restore" — una por servicio, anidada debajo de él. La verificación las colisionó, y el publicador concluyó que no podía actualizar Markdown de forma segura. El reporte de bug decía "la página ya existe"; el defecto real fue que confundí un nombre de hoja con una identidad.

Ese último es un caso específico de un error que ya he cometido en cuatro subsistemas diferentes: un nombre no es una identidad. Dos hosts pueden correr ambos un contenedor llamado redis. Dos servicios pueden tener una página llamada Backup and Restore. Cualquier verificación que resuelva un nombre sin un ámbito eventualmente fusionará dos cosas que nunca fueron iguales.

Por qué no automatizé el merge

Porque el valor de este sistema es que detecta, y detectar es barato de verificar mientras que publicar es caro de revertir. Revisar una página generada me toma menos de un minuto — el diff es un archivo nuevo y las citas están en línea. Despublicar algo incorrecto de una wiki que la gente ya leyó toma considerablemente más tiempo, y no hay comando para la parte en que ya la leyeron.