Visualizador de GitHub Actions

Bienvenido al Bosque de YAML

¿Cuántas líneas de largo tiene actualmente el archivo workflow.yml de tu equipo?

Por lo general, CI/CD comienza de manera muy inocente. “¡Solo lintear, probar y compilar!” Pero luego tu producto crece. De repente, alguien agrega una regla para notificar a Slack si fallan las pruebas E2E. Otra persona agrega una condición para omitir la implementación de ciertas ramas. Antes de que te des cuenta, has creado un monstruo YAML de cientos de líneas.

  build:
    needs: [test-frontend, test-backend, check-format]
  deploy:
    needs: [build, security-scan]

Recuerdo mirar inexpresivamente la pantalla en modo oscuro de GitHub, preguntándome: “Espera… ¿el trabajo de compilación del frontend realmente tiene que esperar a que terminen las pruebas del backend?” Me estaba perdiendo en un código que yo mismo había escrito. Los cerebros humanos simplemente no están programados para leer gráficos de dependencia profundamente anidados e interconectados a partir de texto plano.

Dibujando las Cuerdas Invisibles

“Ya no puedo mantener este árbol abstracto en mi cabeza. Necesito verlo físicamente”.

Esa frustración fue la chispa de este visualizador. El concepto era simple: pegas tu archivo YAML masivo y un poco de JavaScript inteligente se infiltra, analiza todos los parámetros needs:, toma las relaciones padre-hijo y las expulsa en un diagrama de flujo magníficamente organizado utilizando Mermaid.js.

La parte más sorprendentemente divertida de desarrollar fue el manejo de errores. YAML es un lenguaje notoriamente cruel: omites un espacio de sangría y todo explota. En lugar de simplemente lanzar un “Error de análisis genérico”, pasé un tiempo extra asegurándome de que la herramienta te grite con números de línea exactos para que puedas encontrar realmente el error tipográfico.

Hoy en día, nuestro equipo utiliza este visualizador como herramienta de documentación para incorporar a nuevos desarrolladores e ilustrar el flujo de CI. Si alguna vez sientes que estás perdiendo la cabeza mirando YAML, cópialo y pégalo aquí. Es posible que te alivie ver que tu lógica en realidad tiene una forma hermosa.

Una imagen cambia la conversación de la revisión

Cuando revisas YAML como texto, los comentarios derivan inevitablemente hacia detalles diminutos de sintaxis: “la sangría de aquí”, “este array de needs”. Pero muéstralo como diagrama y la conversación sube un nivel. “Espera, ¿no falta este análisis de seguridad en los requisitos del despliegue?”: empiezan a surgir de forma natural comentarios sobre el diseño en sí.

Lo mismo ocurre cuando alguien nuevo pregunta “¿cómo funciona nuestro CI?”. Mostrar un único diagrama de flujo es mejor que recorrer juntos cientos de líneas de YAML. Un diagrama es a la vez una herramienta para escribir código y un lenguaje común para explicarlo a las personas. Cuando tu CI empiece a parecer complejo, dibujarlo todo primero es el camino más rápido.

Preguntas frecuentes

¿El YAML del workflow que pego se envía a algún sitio?

No. El análisis del YAML y la generación del diagrama ocurren íntegramente en tu navegador. Aunque contenga definiciones internas de CI/CD, nombres de trabajos o destinos de despliegue, nada se envía a un servidor externo.

¿Qué tipo de diagrama produce needs?

Toma needs: y dibuja las relaciones padre-hijo entre trabajos como un grafo con flechas. De un vistazo ves qué se ejecuta en serie, qué en paralelo y si falta alguna dependencia: menos errores que leer el YAML de arriba abajo.

¿Puedo pegar el diagrama generado en GitHub?

Sí. Copia el código Mermaid generado y pégalo en un README o documentación. También funciona bien como material para explicar la estructura de tu CI a nuevos miembros del equipo.

¿Y si un error de YAML impide que se renderice el diagrama?

Lo habitual es un desliz de sangría. Como un solo espacio cambia la estructura en YAML, comprueba que el anidamiento de los trabajos esté alineado y que hayas sangrado con espacios en lugar de tabuladores. Empezar por la línea que indica el error es el camino más rápido.