Réponse rapide : Pour corriger un échec de CI à l'aide d'un agent IA, envoyez l'événement d'échec de la CI à un webhook, laissez un agent de code vérifier s'il est capable de traiter l'erreur, la reproduire localement dans un worktree propre, puis pousser un correctif sur une branche sous forme de draft pull request. Un humain se charge de la revue et de la fusion. Sans reproduction locale, aucun push n'est effectué.
Un build dans le rouge à 16 h coûte bien plus cher que sa simple correction. Quelqu'un doit interrompre son travail, ouvrir les logs, faire défiler 900 lignes d'initialisation pour finalement tomber sur une erreur de lint ou un snapshot obsolète. Le correctif prend deux minutes. Le changement de contexte en prend vingt.
C'est précisément là qu'un agent de code prend toute sa valeur. Vous utilisez sans doute déjà Claude Code, Codex ou un autre agent sur votre poste. La pièce manquante, c'est l'agencement : un mécanisme capable de détecter l'échec, de le transmettre à l'agent avec le contexte approprié, tout en évitant qu'il ne pousse des suppositions hasardeuses sur votre dépôt. Ce guide vous montre comment mettre en place cette mécanique avec GitHub Actions et une Automation Sharkly. Cette approche fonctionne d'ailleurs avec n'importe quel système de CI capable d'envoyer une requête HTTP.
Ce qu'un agent IA corrige efficacement dans la CI (et ce qu'il ne sait pas faire)
Un agent excelle sur les pannes reproductibles sur une machine locale et nécessitant un correctif ciblé et vérifiable. En revanche, il montre vite ses limites face aux problèmes d'infrastructure, de variables secrètes ou de services tiers. Triez avant d'automatiser :
| Type d'erreur | Pertinence de l'agent | Raison |
|---|---|---|
| Erreurs de lint et de formatage | Excellente | Déterministe, le linter valide le correctif |
| Erreurs de typage | Excellente | Le compilateur valide le correctif |
| Snapshot cassé suite à une modification voulue de l'interface | Bonne | Facile à reproduire, mais un humain doit confirmer que le changement était bien intentionnel |
| Test instable (flaky test) | Moyenne | La reproduction nécessite plusieurs exécutions ; le correctif implique souvent de corriger une véritable condition de course (race condition) |
| Test unitaire en échec suite à une modification logique | Moyenne | Le test peut être valide et le code en cause |
| Disque du runner saturé, timeouts réseau | Faible | Rien à corriger dans le dépôt |
| Secrets manquants ou expirés, erreurs de permissions | Jamais | L'agent ne doit jamais manipuler d'identifiants |
La règle qui découle de ce tableau est simple : l'agent ne propose un correctif que s'il a vu le statut passer du rouge au vert sur son propre Computer. Un article de conception publié par l'équipe DeepSeek Harness sur X qualifie ce modèle de « reproduction et correction silencieuses » (silently reproduce and fix) : un déclencheur écoute les événements, reste discret par défaut et ne remonte qu'un correctif simple et vérifié. Cet article présente un prototype et non un produit finalisé, mais le principe reste valable pour toute architecture que vous mettriez en place vous-même.
Fonctionnement de la boucle de correction CI
La boucle repose sur cinq étapes : un événement d'échec, un webhook signé, un filtre économe, une reproduction isolée et une validation humaine obligatoire.
- Votre CI termine une exécution sur un échec.
- Un workflow léger envoie un corps JSON signé à l'URL d'un webhook.
- L'agent analyse le corps de la requête et ignore tout ce qui sort de son périmètre, comme un autre dépôt ou un échec sur une branche de release.
- L'agent crée une tâche, extrait le code dans un worktree dédié, reproduit l'échec et le corrige.
- Il pousse une branche et ouvre une draft pull request. Un humain la valide et la fusionne, ou la ferme.
Les étapes 3 et 4 s'exécutent sous forme d'Automation Sharkly. Une Automation est un ensemble d'instructions enregistrées associé à l'Agent ou à la Crew qui les exécute, déclenché par un événement : une planification, un changement de statut de tâche, une expression en commentaire ou un webhook.
Étape 1 : Envoyer l'échec de CI à un webhook
GitHub Actions propose un événement workflow_run qui se déclenche lorsqu'un autre workflow se termine. Il s'active quelle que soit l'issue de l'exécution, vous devez donc filtrer sur failure à l'aide d'une condition au niveau du job. Un détail important souligné dans la documentation de GitHub : le fichier du workflow doit obligatoirement être présent sur la branche par défaut, sans quoi il ne se déclenchera jamais.
Ce workflow écoute les exécutions d'un workflow nommé CI, construit un payload JSON succinct, le signe et l'envoie :
name: Report CI failure
on:
workflow_run:
workflows: [CI]
types: [completed]
jobs:
notify:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
steps:
- name: Send signed webhook
env:
WEBHOOK_URL: ${{ secrets.SHARKLY_WEBHOOK_URL }}
SIGNING_SECRET: ${{ secrets.SHARKLY_SIGNING_SECRET }}
REPO: ${{ github.repository }}
RUN_ID: ${{ github.event.workflow_run.id }}
RUN_URL: ${{ github.event.workflow_run.html_url }}
BRANCH: ${{ github.event.workflow_run.head_branch }}
SHA: ${{ github.event.workflow_run.head_sha }}
run: |
BODY=$(jq -nc --arg repo "$REPO" --arg run_id "$RUN_ID" \
--arg url "$RUN_URL" --arg branch "$BRANCH" --arg sha "$SHA" \
'{event:"ci_failure",repo:$repo,run_id:$run_id,run_url:$url,branch:$branch,sha:$sha}')
TS=$(date +%s)
SIG=$(printf '%s\n%s' "$TS" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -binary | base64)
curl -fsS -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: v1=$SIG" \
--data-raw "$BODY"
Les noms de branches pouvant provenir de contributeurs externes, le workflow les transmet via env et jq plutôt que de les injecter directement dans le script shell. Enregistrez ces deux valeurs sous forme de secrets de dépôt chiffrés, jamais en clair dans le fichier.
Étape 2 : Créer l'Automation et son déclencheur webhook
Dans votre Space, créez une Automation, assignez-la à l'Agent chargé des corrections et ajoutez un déclencheur Webhook. Sharkly n'affiche l'URL complète qu'une seule fois, lors de la création ou de la régénération du déclencheur ; copiez-la donc directement dans votre secret GitHub.
Activez un secret de signature. Sans cela, l'URL fait office de token porteur (bearer) : quiconque la possède peut lancer une exécution. En activant la signature, conformément à la documentation des Automations, chaque requête doit comporter un en-tête X-Webhook-Signature préfixé par v1= suivi du HMAC-SHA256 en Base64 calculé sur l'horodatage, un saut de ligne et le corps brut de la requête, signé avec le secret whsec_. Sharkly rejette les horodatages décalés de plus de 300 secondes et n'accepte une signature donnée qu'une seule fois sur une fenêtre de 10 minutes, empêchant toute attaque par rejeu.
Le déclencheur doit être activé et l'Automation au statut Active pour qu'une requête valide puisse lancer une exécution. Testez d'abord la configuration avec « Run now ».
Étape 3 : Rédiger des instructions pour filtrer d'abord, corriger ensuite
Une exécution d'Automation déclenchée par un webhook ne crée pas de tâche de manière automatique. Comme elle n'est rattachée à aucune tâche, vos instructions doivent en ouvrir une. Cela permet de conserver un historique pour chaque échec, d'offrir un fil de discussion pour d'éventuelles questions et d'afficher un statut visible par toute l'équipe. Placez les vérifications rapides et peu coûteuses au début pour que la majorité des événements se traitent en quelques secondes :
You receive a CI failure webhook. The trigger payload is JSON with
event, repo, run_id, run_url, branch, sha.
1. Stop with no output unless event == "ci_failure" and repo is
acme/web. Stop if branch starts with "release/".
2. Search open tasks for run_id. If one exists, stop.
3. File a task titled "CI fix: <repo> run <run_id>" with run_url in
the body. Do all further work under that task.
4. Read the failed steps: gh run view <run_id> --log-failed
5. If the cause is a secret, permission, runner, or network problem,
comment the diagnosis on the task and stop. Change nothing.
6. Check out sha in a fresh worktree. Run the failing command and
confirm it fails the same way. If it does not reproduce, comment
what you tried and stop. Never push an unreproduced fix.
7. Make the smallest change that fixes it. Do not edit CI config,
lockfiles, or tests you were not asked to fix. Rerun the command
and the nearest test suite.
8. Push to branch ci-fix/<TASK-ID> and open a draft PR with
gh pr create --draft, task ID in the title. Comment the PR link
on the task and hand it to a human for review.
Deux détails ont leur importance ici. À l'heure actuelle, les déclencheurs basés sur le statut ou les commentaires s'appliquent à l'échelle de toute l'organisation, raison pour laquelle la documentation préconise de valider les paramètres au sein même des instructions. Bien qu'un webhook soit restreint à son URL propre, l'étape 1 offre une protection supplémentaire contre les requêtes mal acheminées. De plus, l'identifiant de tâche (task ID) présent dans le nom de la branche joue un rôle déterminant : grâce à l'intégration GitHub, la présence du task ID dans la branche, le titre ou la description de la PR permet de relier directement la pull request à la tâche correspondante.
Étape 4 : L'exécuter sur un Computer dans un worktree isolé
Un Computer désigne la machine hôte connectée sur laquelle tourne votre Agent, avec ses propres Runtimes, ses fichiers et ses identifiants Git. Configurez le dépôt de l'Agent en mode « Temporary » afin que chaque exécution dispose de son propre répertoire de tâche et d'un worktree indépendant. De cette manière, deux échecs survenus à une minute d'intervalle ne risquent pas d'écraser mutuellement leurs fichiers. Pour le détail du fonctionnement, consultez l'article sur les agents en parallèle dans des worktrees isolés ainsi que la documentation de git worktree.
Les accès Git proviennent du Computer lui-même et non de la GitHub App. Si l'intégration permet de lier les pull requests et de synchroniser les issues, le clonage et le push s'appuient toujours sur la clé SSH, le token HTTPS ou la session gh configurée sur cette machine hôte. N'accordez à ces identifiants que les droits de push sur les branches secondaires et protégez votre branche par défaut afin d'exiger une revue avant toute fusion.
Coûts et garde-fous
Chaque exécution est facturée sur l'abonnement propre au Runtime. Sharkly ne vend pas de tokens : le coût d'une correction de CI correspond simplement à ce que vous coûterait une session Claude Code ou Codex d'une durée équivalente. Le filtre rapide de l'étape 1 constitue votre principal levier de maîtrise des coûts : un événement filtré dès cette première étape ne consomme que quelques centaines de tokens, au lieu d'une reproduction complète.
La concurrence constitue le second garde-fou. Chaque Computer possède une limite de tâches simultanées, et les exécutions en répertoires temporaires sont configurées par défaut à la moitié de ce plafond. Lorsque la capacité maximale est atteinte, les exécutions excédentaires sont mises en file d'attente au lieu d'engorger une seule machine. Une matinée difficile avec 30 builds dans le rouge se traduit alors par une simple file d'attente plutôt que par un blocage complet du système.
Le reste relève de règles à définir une bonne fois pour toutes :
- Uniquement des draft PRs. L'agent ne fusionne jamais de lui-même. Consultez l'article sur les agents de code avec intervention humaine (human-in-the-loop) pour déterminer où positionner l'étape de validation.
- Une seule tentative par exécution. Si le premier correctif échoue lors de sa propre réexécution, l'agent laisse un commentaire et s'arrête.
- Une liste d'exclusion (deny list) : configuration CI, secrets, fichiers de lock (lockfiles), migrations.
- Mettez l'Automation en pause depuis sa page dès que vous modifiez ses instructions, puis réactivez-la après un test avec « Run now ».
Vérifiez avant de faire confiance. La boucle planifier, observer, vérifier s'applique pleinement ici : analysez une semaine d'historique d'exécutions avant d'élargir la liste des dépôts pris en charge.
Alternatives
Au lieu d'une Automation basée sur un webhook, vous pouvez créer une tâche pour chaque échec. Configurez le workflow pour appeler un script exécutant sharkly task create, puis laissez l'Agent assigné s'en charger. Vous obtiendrez ainsi une tâche pour chaque build en échec, y compris ceux que l'agent devrait ignorer ; cette solution est donc plutôt adaptée aux dépôts à faible volume. Les équipes qui gèrent déjà leurs tickets via GitHub peuvent également s'appuyer sur l'approche consistant à assigner une issue GitHub à un agent IA.
Commencer avec un seul dépôt
Choisissez le dépôt qui rencontre le plus d'erreurs de lint et de typage, intégrez le workflow ci-dessus et lancez l'Automation manuellement à trois reprises avant de laisser le webhook se déclencher automatiquement. Lorsque vous serez prêt à passer à l'échelle supérieure, l'article expliquant comment exécuter 10 agents de code IA simultanément vous guidera pour la suite. Sharkly est gratuit pour démarrer : connectez un Computer et laissez votre agent actuel prendre en charge le prochain build dans le rouge.
FAQ
Un agent IA peut-il corriger des builds de CI en échec de manière autonome ?
Il peut corriger les erreurs de lint, de typage et de snapshot qu'il parvient à reproduire localement. En revanche, il ne doit pas fusionner son travail lui-même. Limitez sa production à une draft PR et laissez un humain la valider.
Comment déclencher un agent IA en cas d'échec sur GitHub Actions ?
Ajoutez un workflow configuré sur l'événement workflow_run avec types: [completed] et une condition de job sur conclusion == 'failure'. Ce job enverra une requête signée à l'URL du webhook de l'agent.
Qu'est-ce qui empêche l'agent de pousser un correctif erroné ?
La règle de reproduction. L'agent doit constater l'échec localement, apporter une modification et vérifier que la même commande réussit. S'il n'y a pas de reproduction, il se contente de commenter la tâche sans effectuer le moindre push.
L'intégration GitHub de Sharkly ouvre-t-elle des pull requests ?
Non. Elle relie les pull requests aux tâches et synchronise les issues. C'est l'agent qui ouvre la PR en utilisant les identifiants Git et gh configurés sur son Computer.
Qu'en est-il des tests instables (flaky tests) ?
Demandez à l'agent de réexécuter le test défaillant plusieurs fois avant de prendre une décision. Si le test passe sur certaines exécutions et échoue sur d'autres, l'agent doit signaler l'instabilité sur la tâche plutôt que de bricoler un correctif.
Combien coûte une exécution de correction de CI ?
Le coût correspond aux tokens consommés par votre Runtime pendant la session. Les exécutions Sharkly sont directement facturées sur votre abonnement Claude Code, Codex ou API.
