bugzero

~/docs/getting-started

Premiers pas

bugzero est un agent IA qui corrige les bugs, et la salle de contrôle pour le piloter. Quand quelque chose casse — signalé par Sentry, PostHog ou votre propre app via un webhook — l’agent s’exécute dans vos propres GitHub Actions et ouvre une pull request avec un correctif ; vous le pilotez depuis un seul tableau de bord. Votre code ne quitte jamais votre infrastructure. Voici tout ce qu’il faut configurer, et pourquoi chaque étape compte.

01 la boucle

Comment une erreur devient une pull request.

02 configuration requise

7 étapes jusqu’à votre premier correctif.

[01]

Créez votre compte

obligatoire

Inscrivez-vous avec votre e-mail et un mot de passe. Vous obtenez un espace d’équipe sur le forfait Gratuit — 5 correctifs par mois, sans carte bancaire.

// pourquoiDans bugzero, tout est rattaché à une équipe : vous pourrez inviter des collègues plus tard et partager les intégrations, la configuration de l’agent et la facturation. Le forfait Gratuit vous permet de voir de vrais correctifs avant de payer quoi que ce soit.
créer votre compte →
[02]

Connectez GitHub

obligatoire

Sur la page Intégrations, installez la GitHub App de bugzero, choisissez le compte ou l’organisation, puis sélectionnez les dépôts dans lesquels bugzero peut lancer des correctifs.

// pourquoiLa GitHub App de bugzero n’a aucun accès à votre code — sa seule permission est de lancer le workflow bugzero dans vos propres GitHub Actions. Le correctif et la pull request sont produits par ce workflow, dans votre runner. Rien n’est mergé ni déployé automatiquement.
ouvrir les intégrations →
[03]

Connectez une source d’erreurs

obligatoire

Dans Intégrations → Sources d’erreurs, connectez l’outil de suivi des erreurs que vous utilisez déjà et choisissez les projets que bugzero doit surveiller, ou envoyez des erreurs depuis votre propre app. Vous pouvez utiliser plusieurs sources.

  • Sentry — connectez votre organisation via OAuth.
  • PostHog — choisissez votre région et collez une clé d’API personnelle avec les scopes project:read, hog_function:write et query:read.
  • Webhook personnalisé — créez un endpoint par app et envoyez les erreurs à son URL secrète depuis n’importe quel langage ou outil ; voir Webhook personnalisé plus bas.
// pourquoiLes nouvelles erreurs sont le déclencheur de tout ce que fait bugzero. Pour Sentry et PostHog, bugzero configure lui-même l’alerte ou le webhook de chaque projet associé — pas de webhook manuel ni de secret de signature. Un webhook personnalisé fonctionne dans l’autre sens : c’est une URL que vous appelez vous-même chaque fois que votre app intercepte une erreur. Dans tous les cas, c’est vous qui choisissez ce qui est surveillé, pour que les correctifs portent sur les services qui comptent pour vous.
ouvrir les intégrations →
[04]

Associez chaque projet à un dépôt

obligatoire

Pour chaque projet surveillé, choisissez le dépôt GitHub que l’agent doit corriger. Ce réglage se fait juste à côté de chaque projet, sur la page Intégrations. Un endpoint de webhook personnalisé reçoit son dépôt dès sa création.

// pourquoiC’est le lien qui fait fonctionner toute la chaîne. bugzero doit savoir quelle base de code correspond à quel projet — sans association, les erreurs arrivent mais aucune pull request ne sort. C’est l’étape la plus souvent oubliée.
ouvrir les intégrations →
[05]

Ajoutez le workflow bugzero

obligatoire

Dans Intégrations → Configuration du runner, cliquez sur Ajouter le workflow à côté de chaque dépôt. GitHub s’ouvre avec .github/workflows/bugzero.yml prérempli — relisez-le et commitez-le sur votre branche par défaut. Cliquez ensuite sur Vérifier à nouveau.

// pourquoiC’est ce workflow qui exécute réellement le correctif. Quand une erreur survient, bugzero le lance dans votre propre runner GitHub Actions, où l’agent lit votre code et ouvre la pull request — votre code source ne quitte donc jamais votre infrastructure. C’est vous qui ajoutez le fichier, car bugzero ne peut pas écrire dans votre dépôt.
ouvrir les intégrations →
[06]

Ajoutez votre clé d’IA en secret Actions

obligatoire

Dans chaque dépôt connecté, ouvrez Settings → Secrets and variables → Actions et ajoutez un nouveau secret nommé ANTHROPIC_API_KEY (ou OPENAI_API_KEY) contenant votre propre clé d’IA.

// pourquoiL’agent utilise cette clé pendant son exécution dans votre runner GitHub Actions : vous payez donc directement votre fournisseur d’IA et bugzero ne voit jamais la clé. Elle reste un secret GitHub Actions dans votre dépôt et ne passe jamais par nos serveurs.
[07]

Autorisez Actions à ouvrir des pull requests

obligatoire

Dans chaque dépôt connecté, ouvrez Settings → Actions → General, descendez jusqu’à Workflow permissions, cochez Allow GitHub Actions to create and approve pull requests puis enregistrez. Si l’option est grisée, un propriétaire de l’organisation doit d’abord l’autoriser dans les Settings → Actions → General de l’organisation.

// pourquoiGitHub la laisse désactivée par défaut, et la permission pull-requests: write du workflow lui-même ne la contourne pas. Sans elle, l’agent pousse tout de même son correctif sur une branche, mais GitHub refuse d’ouvrir la pull request — vous obtenez une branche au lieu d’une PR.
03 facultatif

Facultatif, mais recommandé.

[08]

Limitez aux bons environnements

facultatif

Sur chaque association de projet, cochez les environnements à prendre en compte — par exemple production uniquement. Laissez tout décoché pour surveiller tous les environnements. Les endpoints de webhook personnalisé disposent du même filtre facultatif.

// pourquoiEn général, vous ne voulez pas de correctifs pour le bruit du local, du dev ou de la préprod. Se limiter à la production concentre les exécutions sur les vrais bugs qui touchent les utilisateurs et évite d’épuiser votre limite mensuelle sur des erreurs sans importance.
ouvrir les intégrations →
[09]

Configurez l’agent

facultatif

Sur la page Agent, choisissez le modèle et l’effort (les derniers modèles Claude ou GPT), rédigez des instructions reprenant les conventions de votre équipe et définissez un plafond de sécurité quotidien. Chaque publication d’instructions crée une nouvelle version — comparez les versions, voyez les résultats de chacune et revenez en arrière en un clic.

// pourquoiLes instructions font respecter vos conventions par les correctifs (« utiliser notre logger », « ajouter un test de régression », fichiers à ne pas toucher), et le modèle et l’effort vous permettent d’arbitrer entre vitesse, coût et profondeur. Votre clé ne se saisit pas ici — elle reste un secret Actions dans votre repo : bugzero décide seulement comment l’agent s’exécute, sans jamais payer ni voir les tokens.
ouvrir l’agent →
[10]

Passez à Pro le moment venu

facultatif

Le forfait Gratuit inclut 5 correctifs par mois. Quand il vous en faut plus, passez à Pro — 9 $US/mois pour des correctifs illimités — depuis Facturation, et gérez ou résiliez votre abonnement via le portail client.

// pourquoiSeules les exécutions qui ouvrent une pull request comptent comme un correctif — les exécutions échouées ne vous sont jamais décomptées. Les tokens d’IA sont facturés au prix coûtant par votre fournisseur : le forfait est donc tout ce que vous payez à bugzero.
ouvrir la facturation →
[11]

Obtenez votre premier correctif

facultatif

Quand une nouvelle erreur touche un projet et un environnement surveillés, bugzero lance une exécution qui aboutit à une pull request. Suivez la progression sur la page Exécutions, puis ouvrez la PR, lisez le diff et le résumé de la cause racine, et mergez si c’est bon.

// pourquoiC’est l’aboutissement, et vous gardez la main : chaque correctif est une pull request à relire — rien n’est mergé ni déployé tant que vous ne l’avez pas validé.
voir les exécutions →
04 webhook personnalisé

Envoyez des erreurs depuis n’importe où.

Des erreurs que votre outil de suivi ne capte pas — un worker, une tâche cron, un script — ou pas d’outil de suivi du tout ? Envoyez-les vous-même à bugzero : une seule requête HTTP, depuis n’importe quel langage ou outil, sans SDK.

Dans Intégrations → Sources d’erreurs, ajoutez un endpoint Webhook personnalisé pour chaque app : un nom, le dépôt que l’agent corrige, sa branche de base et, si besoin, les environnements à prendre en compte. Chaque endpoint reçoit sa propre URL secrète.

créer un endpoint →

Authentification

Le token à la fin de l’URL de l’endpoint l’identifie. Appelez l’URL telle quelle, ou envoyez plutôt le token dans l’en-tête Authorization vers l’URL stable — préférable si vos outils journalisent les URL.

request.http
# token dans l’URL
POST https://bugzero.dev/api/webhooks/custom/bzc_…

# ou : token dans un en-tête
POST https://bugzero.dev/api/webhooks/custom
Authorization: Bearer bzc_…

Payload

Envoyez un objet JSON avec Content-Type: application/json, jusqu’à 256 Ko. Seul message est obligatoire.

messagestring · obligatoire
Le message d’erreur.
typestring
La classe d’erreur, p. ex. TypeError. Par défaut : Error.
titlestring
Remplace le titre par défaut, type: message.
stacktracestring | array
Une chaîne, ou un tableau de lignes ou de frames { file, line, column, function }, l’appel le plus récent en premier.
environmentstring
Comparé au filtre d’environnements de l’endpoint. Les événements qui n’en ont pas passent toujours.
fingerprintstring
Regroupe les événements d’une même erreur (voir « Un correctif par erreur » plus bas). Par défaut : dérivé du type, du message et de la première frame de la stack trace.
urlstring
Un lien vers l’erreur dans votre système (http ou https), affiché sur l’exécution et dans la pull request.
contextobject
Tout détail supplémentaire pour l’agent (requête, utilisateur, tags…), envoyé en JSON et tronqué à 4 000 caractères.
testboolean
Un essai à blanc : indique ce qui se passerait, sans rien lancer.

Les champs inconnus sont ignorés, null équivaut à une absence et les textes trop longs sont tronqués.

Exemples

Avec curl, depuis un terminal ou un script :

$ curl
curl -X POST "$BUGZERO_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "order.customer is undefined",
    "type": "TypeError",
    "environment": "production",
    "stacktrace": [
      { "file": "src/orders/receipt.ts", "line": 42, "function": "sendReceipt" },
      { "file": "src/orders/checkout.ts", "line": 88, "function": "completeOrder" }
    ],
    "url": "https://logs.example.com/errors/8812",
    "context": { "orderId": "ord_8812", "plan": "pro" }
  }'

Depuis Node.js, par exemple dans un bloc catch :

report-error.js[ node 18+ ]
export async function reportError(error, context = {}) {
  await fetch(process.env.BUGZERO_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      type: error.name,
      message: error.message || String(error),
      stacktrace: error.stack,
      environment: process.env.NODE_ENV,
      context,
    }),
    signal: AbortSignal.timeout(5000),
  }).catch(() => {});
}

try {
  await completeOrder(order);
} catch (error) {
  await reportError(error, { orderId: order.id });
  throw error;
}

Un correctif par erreur

L’agent ne se lance qu’une fois par erreur : après le premier événement, les événements portant le même fingerprint sur le même endpoint sont ignorés, même si cette exécution a échoué. Dans ce cas, corrigez la configuration (par exemple, un workflow ou une clé d’IA manquants) et cliquez sur Réessayer sur la page de l’exécution.

Par défaut, les nombres et les identifiants présents dans le message sont ignorés : « Utilisateur 123 introuvable » et « Utilisateur 456 introuvable » sont donc la même erreur. Vous voulez un nouveau correctif quand une erreur réapparaît dans une version ultérieure ? Envoyez un fingerprint qui inclut la version, p. ex. "send-receipt@2.4.1". Il remplace celui par défaut : gardez donc le reste stable — pas d’identifiants ni d’horodatages.

Testez-le

Ajoutez "test": true pour vérifier l’URL et votre payload sans rien lancer. La réponse vous indique si un vrai événement lancerait l’agent et, sinon, pourquoi :

$ curl[ test ]
curl -X POST "$BUGZERO_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"message": "order.customer is undefined", "test": true}'
{
  "ok": true,
  "outcome": "test",
  "wouldStart": true,
  "fingerprint": "5d0c41a7e2b9f8c3a1d6e4b2c9f07a18",
  "title": "Error: order.customer is undefined"
}

Réponses

Chaque réponse est en JSON. Ne réessayez qu’en cas de 5xx : une même erreur ne lance jamais l’agent deux fois, réessayer est donc sans risque.

202 outcome: "started"
L’agent a démarré. Le corps inclut le runId et le status de l’exécution.
200 outcome: "skipped"
Rien n’a été lancé ; reason indique pourquoi (voir ci-dessous).
200 outcome: "test"
Un essai à blanc ; rien n’a été lancé (voir « Testez-le »).
400 error: "invalid_json"
Le corps n’est pas du JSON valide.
400 error: "invalid_payload"
Un champ est manquant ou n’a pas le bon type ; issues liste chaque problème avec son chemin.
401 error: "unauthorized"
Token inconnu : vérifiez l’URL — ou bien l’endpoint a reçu une nouvelle URL ou a été supprimé.
413 error: "payload_too_large"
Le corps dépasse 256 Ko.
5xx
Une erreur s’est produite de notre côté. Vous pouvez réessayer sans risque.
reason: "duplicate"
Cette erreur a déjà été traitée ; runId est son exécution.
reason: "environment"
L’environnement de l’événement ne figure pas dans le filtre de l’endpoint.
reason: "repo_not_connected"
Le dépôt de l’endpoint n’est pas sélectionné dans la carte GitHub.
reason: "limit"
La limite mensuelle du forfait Gratuit ou le plafond de sécurité quotidien a été atteint ; code vaut free_limit ou daily_cap.

Gardez le token secret

  • Envoyez les événements uniquement depuis votre serveur, jamais depuis un navigateur — n’importe qui pourrait y lire le token.
  • Si vos proxys ou vos logs enregistrent les URL, envoyez plutôt le token dans l’en-tête Authorization.
  • Si l’URL fuite, générez-en une nouvelle pour l’endpoint ; l’ancienne cesse immédiatement de fonctionner.
  • Tout ce que vous envoyez est stocké avec l’exécution et montré à l’agent IA : n’y mettez ni mots de passe, ni clés, ni données personnelles.
05 dépannage

Tout est configuré, mais aucune pull request ?

C’est presque toujours l’une de ces causes :

$ bugzero doctor[ 8 vérifications ]
  • Aucune association projet → dépôt pour l’instant (étape 04) — de loin la cause la plus fréquente.
  • Le workflow bugzero n’est pas sur la branche par défaut, ou le secret ANTHROPIC_API_KEY / OPENAI_API_KEY est manquant (étapes 05 et 06). Les exécutions échouées affichent le motif sur leur page.
  • Le correctif a été poussé sur une branche mais aucune pull request ne s’est ouverte — GitHub n’autorise pas Actions à en créer (étape 07).
  • L’environnement de l’erreur ne fait pas partie de votre liste surveillée (étape 08).
  • Aucune nouvelle erreur ne s’est encore produite — bugzero réagit aux nouvelles issues, pas aux anciennes.
  • Vous avez épuisé vos 5 correctifs gratuits du mois, ou le plafond de sécurité quotidien a été atteint — consultez le tableau de bord.
  • Le dépôt n’est pas sélectionné dans la carte GitHub (étape 02).
  • Vous envoyez des erreurs à un webhook personnalisé ? Sa réponse JSON indique pourquoi un événement a été ignoré ; ajoutez "test": true pour vérifier sans rien lancer.
et ensuite

Envie de vous lancer ?

Créez votre compte et connectez votre premier dépôt — le forfait Gratuit inclut 5 correctifs par mois.

5 correctifs gratuits/mois →aller aux intégrations →