Cloudflare Build Badge

¿Por qué existe?

¿Sabes ese badge de estado de build que GitHub Actions te deja meter en el README? Cloudflare Workers Builds no tiene uno. Si sincronizas un repo de GitHub con Cloudflare para que cada commit se construya y se despliegue solo usando Cloudflare Builds en lugar de GitHub Actions, no hay forma nativa de mostrar ese estado junto al resto de badges.

Me encontré con ese hueco en proyectos Astro que hosteo en Cloudflare. Sobre todo con Eminence Astro Starter, otro proyecto mío: publicar el README sin un badge de build creíble se sentía a medias. Nada de lo que había encajaba del todo con lo que necesitaba, así que lo hice yo.

¿Qué hace?

Te deja poner un badge en vivo del estado de Cloudflare Workers Builds en cualquier repo de GitHub, público o privado, desplegando tu propio Worker. Esa es la clave: tu GITHUB_TOKEN se queda en tu instancia. No le estás pasando credenciales a un servicio de badges de terceros.

Por debajo, cada petición llega al Worker, pregunta a la GitHub Checks API por el check más reciente de Cloudflare Workers & Pages en la rama que pediste (o la default), lo mapea a un badge de Shields.io y devuelve el SVG. La URL es /{username}/{repository}/status.svg, con rama opcional. Los query params de Shields.io (estilo, logo, colores, caché) se reenvían; el color y el mensaje de estado los calcula el Worker.

Puedes usar la instancia en vivo o copiar la plantilla Astro, poner tu dominio, un token de solo lectura y montar la tuya.

¿Cómo lo construí?

Partí de mi versión aún incompleta de Eminence Astro Starter: resolvía el problema del badge y, de paso, ponía el starter a prueba para ver qué le faltaba. También era un stack que ya dominaba lo suficiente como para sacar algo real.

Podría haber ido a lo mínimo: un Worker con Hono que solo sirviera el SVG, quizá un poco más ligero para ese único trabajo. No lo hice. Quería una UI decente para configurar badges, y quería montarla con herramientas que ya uso a diario. El mismo runtime en el edge para el sitio y para el endpoint del badge me pareció el equilibrio correcto para un proyecto de este tamaño.

Stack

• Astro 7 en Cloudflare Workers
• Svelte 5
• TypeScript
• Tailwind CSS 4
• Shields.io
• GitHub Checks API

Las partes difíciles

Empecé esto cuando Astro 3 y Cloudflare Pages eran lo que usaba para desplegar. La IA ya existía, pero no era lo bastante buena como para guiarme como lo haría ahora, así que tuve que pelearme con la documentación yo solo.

El primer muro fue averiguar dónde vivía el estado del build. Fui primero a la API de Cloudflare, porque ahí ocurría el build. En aquel momento podías disparar builds, no leerlos. Luego di vueltas por GitHub: commit statuses, la Status API, deployments. Nada encajó hasta que llegué a Check Suites y vi que podía sacar el check de Cloudflare por app/slug. Lo que aprendí: el estado no siempre está en la plataforma que ejecuta el build. A veces aparece como un check en el host de git, y esa API hay que aprenderla a base de ir a tientas.

Cuando ya tenía la API correcta, llegó la realidad: repos con muchos checks, paginación y rate limits. Tuve que recorrer páginas con cuidado para que “último build de Cloudflare” fuera el check correcto, haciendo las menos peticiones posibles. Cuando el rate limit igual te pilla, muestro ese error en lugar de fingir que el badge está bien. Lo que aprendí: los casos borde de “¿cuál check?” y “¿cuántas llamadas?” forman parte del diseño, no son restos.

Después se cayó Shields.io. No lo había previsto. Solo me di cuenta cuando el badge se rompió en un README. Ahora esos fallos caen a SVGs guardados para que siga mostrándose algo útil. Lo que aprendí: si dependes de un render externo, asume que fallará, y decide el fallback antes de que la producción te lo enseñe.

Por el camino saqué varias iteraciones, incluidas pruebas más delgadas solo con Hono. Cada una salía más limpia y eficiente que la anterior: de catch-alls desordenados a try/catch deliberados con mensajes de error precisos. Lo que ves ahora es el resultado pulido de ese camino, no la primera versión que funcionó.

Impacto

¿Sinceramente? Ahora mismo no sé de nadie más que lo use, así que es sobre todo una herramienta para mí. Aun así, es open source con licencia MIT. Si quieres usarlo, o te has topado con el mismo hueco que yo, puedes solucionarlo igual: despliega tu propia instancia y deja el token de GitHub de tu lado.