FailTrace: qué es y por qué importa si tu CI falla
Un equipo de desarrollo mediano necesita alrededor de cinco rondas de CI por cada cambio que llega a producción, y cuando una de esas rondas falla tarda cerca de hora y media en volver a verde, según el reporte State of Software Delivery Pulse de CircleCI para el tercer trimestre de 2026 que recoge HackerNoon. Para un equipo pequeño, eso es tiempo de ingeniería pagado que se va en esperar y en adivinar. FailTrace es una herramienta de línea de comandos escrita en Go y publicada con licencia MIT que ataca esa parte del problema: le pasas la URL de un run fallido de GitHub Actions y te dice qué paso falló, por qué falló y cómo reproducirlo en tu máquina dentro de Docker.
El proyecto está en desarrollo temprano y su repositorio todavía no acumula estrellas ni forks, así que conviene tratarlo como una herramienta emergente y no como infraestructura crítica. Aun así, las tres órdenes que promete ya funcionan.
¿Qué hace FailTrace exactamente?
La herramienta gira alrededor de tres comandos que se encadenan:
¿Y esto cómo se aplica en tu negocio?
Dueños de negocio de Latinoamérica y España usan un agente de IA para ganar más y recuperar su tiempo. El Kit «tu mano derecha con IA» te muestra cómo en un video de 11 minutos, con una ficha para armar el tuyo. CAR está cerrada por ahora; al anotarte, te avisamos cuando abra.
👥 Quiero el Kit →failtrace inspect <run-url>responde \»por qué falló\». Encuentra el job y el paso que fallaron, los cruza con el archivo de workflow en ese commit exacto, extrae el error de los logs y explica qué te separa de reproducirlo.failtrace plan <run-url>responde \»cómo se reproduciría\». No ejecuta nada: imprime el plan con la imagen base, el commit exacto, las versiones de toolchain, las variables de entorno y los pasos a repetir.failtrace repro <run-url>responde \»reprodúcelo\». Construye el plan, lo corre en Docker y compara el resultado con el fallo de CI.
inspect acepta la URL del run completo, la de un job concreto o la de un intento específico de un re-run, y tiene tres banderas útiles: --json para scripts, -n para ampliar el contexto de log (25 líneas por defecto) y --job para inspeccionar un solo job. La salida con color se apaga sola cuando no hay terminal o cuando defines NO_COLOR.
Un detalle que sorprende: FailTrace necesita un token de GitHub incluso para repositorios públicos, porque la API de logs lo exige. Busca en orden GITHUB_TOKEN, GH_TOKEN y gh auth token, así que si ya usas el CLI de GitHub no tienes que configurar nada. También funciona con GitHub Enterprise Server.
¿En qué se diferencia de act?
La comparación inevitable es con nektos/act, que ejecuta workflows en local y lo hace bien. FailTrace responde una pregunta distinta: por qué falló este run en particular y si puedes hacer que falle igual en tu máquina.
- Arranca de un run fallido, no de un archivo de workflow. Obtiene el commit, el intento, el job, la combinación de matriz y el paso que falló sin que configures nada.
- Se concentra en el fallo. El objetivo es replicar solo lo que el paso fallido necesita, no el workflow completo.
- Entrega un veredicto. Ahora es un diagnóstico; la hoja de ruta apunta a sumar reproducido, no reproducido o flaky, y las diferencias entre CI y tu máquina.
¿Cómo construye el plan de reproducción?
El plan se apoya en cuatro decisiones que explican por qué muchos fallos no se reproducen en local:
- El log es la fuente de verdad de lo que corrió. Los scripts, los shells y el entorno salen de los encabezados que GitHub imprime, así que las expresiones ya vienen resueltas.
- El commit exacto que CI probó. En pull requests es un commit de merge que GitHub creó, no la cabeza de tu rama. Esa es una causa habitual de que el fallo desaparezca en tu máquina.
- Las versiones exactas de toolchain. Un \»3.11\» en el workflow se convierte en
3.11.18, leído de las rutas de caché del runner. Cuando el log no muestra versión, la busca engo.mod,.nvmrc,.python-version,.tool-versionsopackageManager. - La imagen base correcta. Si el job define un
container:, lo respeta; si no, elige la versión de Ubuntu que coincida con la imagen de runner que el job recibió.
El veredicto del plan es ready, partial o blocked, y este último aparece cuando el paso fallido es una action y no un script, algo que todavía no se puede replicar.
¿Qué te dice cuando el fallo se reproduce?
repro compara el resultado local con el de CI y devuelve uno de cinco veredictos: reproduced, different-failure, not-reproduced, diverged o flaky. Además clasifica el fallo en categorías como test, build, dependency, lint, generated-diff, timeout u out-of-memory, y detecta nombres de tests fallidos de Go, pytest, Jest, Vitest, Cargo y RSpec.
Hay tres banderas que valen oro en el día a día:
--runs 10repite el paso fallido dentro del mismo contenedor para determinar si el fallo es intermitente. En Go, además, desactiva la caché de tests (GOFLAGS=-count=1), porque si nogo testreproduciría un pase cacheado y escondería la flakiness.--shellabre una terminal dentro del contenedor en el paso fallido, con el mismo directorio, entorno, toolchains y servicios, e imprime el comando para volver a ejecutar el paso.--report repro.mdgenera un reporte en Markdown con el veredicto, la tabla CI contra local, las diferencias y la salida del paso fallido en ambos lados, listo para pegar en un issue o un pull request.
¿Cuánto cuesta y cómo se instala?
FailTrace es gratuito y de código abierto bajo licencia MIT. Se instala con un script que descarga el binario de tu plataforma y verifica su checksum SHA-256, con binarios precompilados para macOS, Linux y Windows en amd64 y arm64, con go install si tienes Go 1.24 o superior, o compilando desde el código fuente. Necesitas Docker y git.
Para un equipo en LATAM o España con presupuesto ajustado, la aritmética es simple: es una herramienta local, sin asientos ni suscripción, frente a las plataformas de runners de pago que dominan el mercado.
¿Qué no puede hacer todavía?
Las limitaciones están documentadas y se reportan en lugar de ignorarse:
- Un paso fallido que es una action y no un script no se puede replicar.
- Los jobs de Windows y macOS solo se aproximan en Linux.
- Los pasos corren como root, mientras que CI usa el usuario
runner. - No están todas las herramientas preinstaladas de la imagen de runner.
- Los jobs
linux/amd64se emulan en máquinas ARM: en un Mac con Apple silicon, una reproducción pasó de unos 40 segundos a cerca de 9 minutos, con el mismo veredicto. - Los artefactos generados por otros jobs no están disponibles.
En la hoja de ruta quedan pendientes la instalación por Homebrew, una extensión para el CLI de gh y traducir actions comunes como golangci-lint-action a los comandos que ejecutan.
¿Qué significa esto para tu startup?
El contexto importa: según el reporte de CircleCI que recoge HackerNoon, desde septiembre de 2025 los workflows activos en ramas de trabajo crecieron un 40% en un día típico, contra un 17% en la rama principal, y los fines de semana los agentes y bots explican cerca de una de cada cinco ramas en pruebas. Con agentes de IA abriendo decenas de pull requests al día, el CI se convierte en el cuello de botella, y el tiempo de recuperación, cerca de 86 minutos en el reporte, pesa más que la duración de un run exitoso.
Acciones concretas que puedes tomar esta semana:
- Mide antes de comprar. Antes de evaluar proveedores de runners como Blacksmith, Depot, Namespace o Avrea, corre
failtrace inspectsobre tus últimos runs fallidos y calcula cuánto de tu tiempo de CI se va en diagnosticar, no en ejecutar. Si el problema es el diagnóstico, un runner más rápido no lo arregla. - Estandariza el reporte de fallos. Adopta
--reportpara que cada issue de CI llegue con veredicto, comparación CI contra local y la salida del paso fallido. Reduce el ida y vuelta entre quien reporta y quien arregla. - Separa flaky de roto. Usa
--runs 10antes de asignar a alguien a arreglar un test que falla una de cada cinco veces. La diferencia entre un bug real y un test intermitente cambia por completo el costo de la tarea. - Trata la reproducción como ejecución de código no confiable.
reprocorre el código del repositorio, incluido el de un pull request, dentro de un contenedor. FailTrace no le da acceso a tu directorio personal ni al socket de Docker, y no recibe secretos salvo que los pases con--secret. Aun así, el contexto del sector lo justifica: en junio de 2026, investigadores de Novee Security escanearon unos 30.000 repositorios y confirmaron más de 300 como explotables por patrones de composición de workflows, según BleepingComputer. Reproduce solo runs cuyo código estés cómodo ejecutando.
La conclusión práctica: la velocidad de CI dejó de ser un problema de hardware. Con agentes generando cambios a un ritmo que ningún revisor humano sigue, el cuello de botella se movió al diagnóstico y a la recuperación. Herramientas gratuitas y locales como FailTrace no reemplazan a act ni a tu proveedor de runners: atacan el tramo del proceso donde hoy se pierden más horas de ingeniería.
Fuentes
- FailTrace – Reproduce a failed GitHub Actions run locally from its URL (fuente original)
- Avrea’s Faster Runners for GitHub Actions Reflect How AI Coding Is Changing CI
- The GitHub Actions Attack Pattern Your CI Security Scanners Miss
¿Y esto cómo se aplica en tu negocio?
Dueños de negocio de Latinoamérica y España usan un agente de IA para ganar más y recuperar su tiempo. El Kit «tu mano derecha con IA» te muestra cómo en un video de 11 minutos, con una ficha para armar el tuyo. CAR está cerrada por ahora; al anotarte, te avisamos cuando abra.
👥 Quiero el Kit →













