Cloudflare Build Badge
Servicio de badges autoalojado · uso personal por ahora
- Astro
- Svelte
- TypeScript
- Tailwind CSS
- Cloudflare Workers
Resumen
Cloudflare Build Badge es un Worker open source que genera badges SVG con el estado de build de cualquier repositorio desplegado con Cloudflare Workers Builds. Está pensado para incrustarse en READMEs de GitHub o en sitios web, sin configuración extra en el repositorio destino.
Lo construí y mantengo en solitario. El servicio está en vivo y abierto a cualquiera, aunque de momento soy su único usuario habitual: es una herramienta nicho que nació en junio de 2026 para cubrir una necesidad concreta.
Contexto
GitHub ofrece badges nativos para GitHub Actions, pero no para los checks de Cloudflare Workers & Pages. La mayoría de mis sitios viven en Cloudflare Workers, así que en los READMEs faltaba esa señal visual de “el último deploy fue bien o mal”.
No había un hueco de producto grande: solo molestaba no poder mostrar el estado de build como ya se hace con Actions.
Por qué
El detonante real no fue el badge en abstracto. Estaba montando eminence-astro-starter, una plantilla Astro orientada a desplegar en Cloudflare Workers, y no quería publicar ese starter sin un badge de build creíble en el README.
Cloudflare Build Badge existe para desbloquear ese proyecto (y el resto de mis repos en Workers) con el mismo patrón que ya usa todo el mundo con Shields.io.
Enfoque
Cada petición de badge hace cuatro pasos en el edge: llega al Worker, consulta la GitHub Checks API por el check más reciente de Cloudflare Workers & Pages en la rama pedida (o la default), mapea el estado a un badge de Shields.io y devuelve el SVG. La URL se vuelve a evaluar en cada request, así que el badge se actualiza solo.
La forma de la URL es /{username}/{repository}/status.svg o con rama explícita. Cualquier query param de Shields.io (estilo, logo, colores, caché) se reenvía; el color y el mensaje de estado los calcula el Worker.
También lo empaqueté como plantilla Astro desplegable: cualquiera puede copiarla, poner su dominio, un GITHUB_TOKEN de solo lectura y tener su propia instancia.
Stack
- Astro 7 en SSR sobre Cloudflare Workers: sitio + endpoint del badge en el mismo borde.
- Svelte 5: UI del configurador de badges.
- TypeScript y Tailwind CSS 4: tipado estricto y estilos del sitio.
- Cloudflare Workers: runtime y despliegue continuo vía Workers Builds.
- Shields.io y la GitHub Checks API (fuera del frontmatter): render del badge y fuente de verdad del estado.
Retos
La Checks API pagina resultados; había que recorrer esa paginación con cuidado para no quedarse con un check viejo o equivocado.
Usar Shields.io añade un punto de fallo externo, a cambio de estilos que la gente ya conoce. Lo acepté a sabiendas.
Para errores propios del servicio (incluido cuando falla Shields.io) no podía depender de Shields otra vez: acabé sirviendo SVGs guardados para esos estados, de modo que el badge siga mostrando algo útil.
Impacto
Hoy el impacto es personal y pequeño: puedo poner badges de build reales en mis READMEs de Workers. El proyecto es MIT y público; cualquiera puede usar la instancia en vivo o desplegar la suya. No hay métricas de adopción todavía — y no las invento.
Aprendizajes
Para un servicio tan delgado, la decisión “depender de Shields vs. dibujar todo el SVG” importa más de lo que parece: el estilo gana adopción, pero obliga a un plan B cuando el render externo falla.
La próxima vez documentaría antes la paginación de Checks y los estados de error del badge como parte del diseño, no como remiendos al final.
Enlaces
- Sitio en vivo
- Repositorio
- eminence-astro-starter (relacionado; puede no estar publicado aún)