Principe de fonctionnement

FailTrace est un utilitaire en ligne de commande qui part d’une URL de run GitHub Actions échoué pour en extraire le job, le step et le commit exacts. Trois sous‑commandes sont proposées : inspect récupère les métadonnées et un extrait du log, plan génère un plan de reproduction sans exécuter quoi que ce soit, et repro lance la reproduction dans un conteneur Docker. L’outil ne nécessite aucune configuration préalable : il déduit automatiquement le label du runner, l’image Docker utilisée (ex. quay.io/prometheus/golang-builder:1.27-base), les variables d’environnement et les valeurs de matrice.

failtrace inspect https://github.com/owner/repo/actions/runs/123456789

Le résultat inclut le diagnostic (code de sortie, annotation d’erreur), le contexte du step (shell, répertoire de travail) et les notes de reproduction (services containers, secrets, runners macOS/Windows). Cette granularité contraste avec act, qui exécute l’ensemble du workflow.

Architecture et flux de données

FailTrace s’appuie sur l’API GitHub : il interroge d’abord l’endpoint /actions/runs/{run_id} pour obtenir le commit SHA, l’événement, le numéro d’essai et la liste des jobs. Ensuite il télécharge le fichier de workflow au même commit, le parse (YAML) afin de faire correspondre le job identifié dans les logs à sa définition, y compris les expansions de matrices (${{ matrix.tool }}). Le log complet du job est récupéré via l’API /logs, puis découpé autour de la première ligne d’erreur afin de réduire le bruit. Les informations de runner (ex. ubuntu-26.04 (20261116.202.1)) sont extraites du préambule du log et servent à choisir l’image Docker de reproduction.

Le plan généré par failtrace plan liste chaque étape avec son action sous‑jacente (checkout, setup‑python, composite actions) et les versions exactes des toolchains (ex. Python 3.11.18, uv 0.13.8). Il expose également les variables d’environnement et les secrets requis, ce qui permet de reproduire le contexte CI sans reconstituer l’intégralité du pipeline.

Analyse des limites et perspectives

Le projet est en « early development ». Actuellement, failtrace repro ne supporte que les jobs Linux dont le step échoué est de type run: ; les runners macOS, Windows ou les steps utilisant des services externes ne sont pas encore pris en charge. De plus, la reproduction dépend de la disponibilité du conteneur d’origine ; si l’image n’est plus publiée, la reproduction échoue. Les workflows dynamiques (générés à la volée) ou les logs expirés sont explicitement signalés, mais aucune alternative n’est proposée.

Sur le plan sécurité, l’outil requiert un token GitHub (variables GITHUB_TOKEN, GH_TOKEN ou gh auth token) même pour les dépôts publics, car l’API des logs est protégée. Le token donne uniquement un accès en lecture aux logs, mais il peut exposer des secrets affichés dans les logs si ceux‑ci ne sont pas masqués.

Les voies d’évolution mentionnées incluent le support des runners macOS/Windows, la prise en charge des steps uses: (actions composites) et l’ajout d’une classification « flaky » après plusieurs tentatives de reproduction. L’intégration avec des pipelines CI existants (ex. déclenchement automatique après un échec) pourrait automatiser le diagnostic et réduire le temps de résolution.