bugzero

~/docs/getting-started

Erste Schritte

bugzero ist ein KI-Agent, der Bugs behebt, samt Kontrollzentrum, um ihn zu steuern. Wenn etwas kaputtgeht – gemeldet von Sentry, PostHog oder deiner eigenen App über einen Webhook –, läuft der Agent in deinen eigenen GitHub Actions und öffnet einen Pull Request mit einem Fix; du steuerst alles von einem Dashboard aus. Dein Code verlässt nie deine Infrastruktur. Hier findest du alles, was du einrichten musst, und warum jeder Schritt wichtig ist.

01 der kreislauf

Wie aus einem Fehler ein Pull Request wird.

02 notwendige einrichtung

7 Schritte bis zu deinem ersten Fix.

[01]

Konto erstellen

pflicht

Registriere dich mit deiner E-Mail-Adresse und einem Passwort. Du bekommst einen Team-Workspace im Free-Plan – 5 Fixes pro Monat, keine Karte nötig.

// warumIn bugzero gehört alles zu einem Team, sodass du später Kolleginnen und Kollegen einladen und Integrationen, die Einrichtung des Agenten und die Abrechnung teilen kannst. Mit Free siehst du echte Fixes, bevor du irgendetwas bezahlst.
konto erstellen →
[02]

GitHub verbinden

pflicht

Installiere auf der Seite Integrationen die GitHub App von bugzero, wähle das Konto oder die Organisation und dann die Repositories aus, in denen bugzero Fixes starten darf.

// warumDie GitHub App von bugzero hat keinen Zugriff auf deinen Code – ihre einzige Berechtigung ist, den bugzero-Workflow in deinen eigenen GitHub Actions zu starten. Den Fix und den Pull Request erstellt dieser Workflow, in deinem Runner. Nichts wird automatisch gemergt oder deployt.
integrationen öffnen →
[03]

Fehlerquelle verbinden

pflicht

Verbinde unter Integrationen → Fehlerquellen den Error-Tracker, den du schon nutzt, und wähle die Projekte, die bugzero überwachen soll – oder sende Fehler aus deiner eigenen App. Du kannst mehr als eine Quelle nutzen.

  • Sentry – verbinde deine Organisation per OAuth.
  • PostHog – wähle deine Region und füge einen persönlichen API-Schlüssel mit den Scopes project:read, hog_function:write und query:read ein.
  • Eigener Webhook – lege für jede App einen Endpoint an und sende Fehler aus jeder Sprache und jedem Tool an seine geheime URL; siehe Eigener Webhook weiter unten.
// warumNeue Fehler sind der Auslöser für alles, was bugzero tut. Für Sentry und PostHog richtet bugzero den Alert bzw. Webhook für jedes verknüpfte Projekt selbst ein – kein manueller Webhook, kein Signing Secret. Ein eigener Webhook funktioniert andersherum: Er ist eine URL, die du selbst aufrufst, wann immer deine App einen Fehler abfängt. So oder so entscheidest du, was überwacht wird, damit sich die Fixes auf die Services konzentrieren, die dir wichtig sind.
integrationen öffnen →
[04]

Jedes Projekt mit einem Repository verknüpfen

pflicht

Wähle für jedes überwachte Projekt das GitHub-Repository, das der Agent fixen soll. Das legst du direkt neben dem jeweiligen Projekt auf der Seite Integrationen fest. Ein Endpoint für einen eigenen Webhook bekommt sein Repository schon beim Anlegen.

// warumDiese Verknüpfung bringt die ganze Pipeline zum Laufen. bugzero muss wissen, welche Codebasis zu welchem Projekt gehört – ohne Verknüpfung kommen Fehler zwar an, aber es gehen keine Pull Requests raus. Das ist der Schritt, der am häufigsten vergessen wird.
integrationen öffnen →
[05]

bugzero-Workflow hinzufügen

pflicht

Klicke unter Integrationen → Runner-Einrichtung neben jedem Repository auf Workflow hinzufügen. GitHub öffnet sich mit der vorausgefüllten Datei .github/workflows/bugzero.yml – prüfe sie und committe sie in deinen Standard-Branch. Klicke dann auf Erneut prüfen.

// warumDieser Workflow führt den Fix tatsächlich aus. Wenn ein Fehler auftritt, startet bugzero ihn in deinem eigenen GitHub-Actions-Runner, wo der Agent deinen Code liest und den Pull Request öffnet – so verlässt dein Quellcode nie deine Infrastruktur. Die Datei fügst du selbst hinzu, weil bugzero nicht in dein Repository schreiben kann.
integrationen öffnen →
[06]

KI-Schlüssel als Actions-Secret hinterlegen

pflicht

Öffne in jedem verbundenen Repository Settings → Secrets and variables → Actions und lege ein neues Secret namens ANTHROPIC_API_KEY (oder OPENAI_API_KEY) mit deinem eigenen KI-Schlüssel an.

// warumDer Agent nutzt diesen Schlüssel, während er in deinem GitHub-Actions-Runner läuft – so bezahlst du deinen KI-Anbieter direkt und bugzero sieht den Schlüssel nie. Er bleibt ein GitHub-Actions-Secret in deinem Repository und berührt nie unsere Server.
[07]

Actions Pull Requests öffnen lassen

pflicht

Öffne in jedem verbundenen Repository Settings → Actions → General, scrolle zu Workflow permissions, hake Allow GitHub Actions to create and approve pull requests an und speichere. Ist die Option ausgegraut, muss ein Inhaber der Organisation sie zuerst unter den eigenen Settings → Actions → General der Organisation erlauben.

// warumGitHub lässt die Option standardmäßig aus, und die Berechtigung pull-requests: write im Workflow selbst überschreibt das nicht. Ohne sie pusht der Agent seinen Fix trotzdem in einen Branch, aber GitHub verweigert das Öffnen des Pull Requests – du bekämst einen Branch statt eines PRs.
03 optional

Optional, aber empfohlen.

[08]

Auf die richtigen Umgebungen beschränken

optional

Hake bei jeder Projekt-Verknüpfung die Umgebungen an, auf die reagiert werden soll – zum Beispiel nur production. Lässt du alle leer, wird jede Umgebung überwacht. Endpoints für eigene Webhooks haben denselben optionalen Filter.

// warumFixes für Rauschen aus Local, Dev oder Staging willst du meist nicht. Wenn du auf Production beschränkst, konzentrieren sich die Läufe auf echte Bugs, die Nutzer treffen, und du verbrauchst dein monatliches Limit nicht für unwichtige Fehler.
integrationen öffnen →
[09]

Agent konfigurieren

optional

Wähle auf der Seite Agent Modell und Aufwand (die neuesten Modelle von Claude oder GPT), schreib Anweisungen mit den Konventionen deines Teams und lege ein tägliches Sicherheitslimit fest. Jedes Mal, wenn du Anweisungen veröffentlichst, entsteht eine neue Version – vergleiche Versionen, sieh, wie jede abschneidet, und setze mit einem Klick zurück.

// warumMit Anweisungen folgen Fixes den Konventionen deines Teams („nutze unseren Logger“, „füge einen Regressionstest hinzu“, Dateien, die tabu sind), und mit Modell und Aufwand tauschst du Tempo und Kosten gegen Tiefe. Deinen Schlüssel gibst du hier nicht ein – er bleibt ein Actions-Secret in deinem Repo; bugzero entscheidet also nur, wie der Agent läuft, und bezahlt oder sieht die Tokens nie.
agent öffnen →
[10]

Auf Pro upgraden, wenn du so weit bist

optional

Free enthält 5 Fixes pro Monat. Wenn du mehr brauchst, upgrade unter Abrechnung auf Pro – 9 $/Monat für unbegrenzte Fixes und verwalte oder kündige dein Abo über das Kundenportal.

// warumNur Läufe, die einen Pull Request öffnen, zählen als Fix – fehlgeschlagene Läufe werden dir nie angerechnet. Die KI-Tokens rechnet dein Anbieter direkt und ohne Aufschlag ab; an bugzero zahlst du also nur den Plan.
abrechnung öffnen →
[11]

Deinen ersten Fix erhalten

optional

Wenn ein neuer Fehler in einem überwachten Projekt und einer überwachten Umgebung auftritt, startet bugzero einen Lauf, der mit einem Pull Request endet. Verfolge den Fortschritt auf der Seite Läufe, öffne dann den PR, lies den Diff und die Zusammenfassung der Ursache und merge, wenn alles passt.

// warumDas ist der Lohn – und du behältst die Kontrolle: Jeder Fix ist ein Pull Request, den du prüfen kannst. Nichts wird gemergt oder deployt, bevor du entscheidest, dass es passt.
läufe ansehen →
04 eigener webhook

Sende Fehler von überall.

Fehler, die dein Tracker nicht erfasst – aus einem Worker, einem Cronjob, einem Skript – oder gar kein Error-Tracker? Schick sie selbst an bugzero: ein HTTP-Request aus jeder Sprache oder jedem Tool, kein SDK.

Lege unter Integrationen → Fehlerquellen für jede App einen Endpoint vom Typ Eigener Webhook an: einen Namen, das Repository, das der Agent fixt, seinen Basis-Branch und optional die Umgebungen, auf die reagiert werden soll. Jeder Endpoint bekommt seine eigene geheime URL.

endpoint anlegen →

Authentifizierung

Der Token am Ende der URL identifiziert den Endpoint. Ruf die URL so auf, wie sie ist, oder sende den Token stattdessen im Header Authorization an die feste URL – besser, wenn deine Tools URLs loggen.

request.http
# token in der URL
POST https://bugzero.dev/api/webhooks/custom/bzc_…

# oder: token im header
POST https://bugzero.dev/api/webhooks/custom
Authorization: Bearer bzc_…

Payload

Sende ein JSON-Objekt mit Content-Type: application/json, bis zu 256 KB. Nur message ist Pflicht.

messagestring · pflicht
Die Fehlermeldung.
typestring
Die Fehlerklasse, z. B. TypeError. Standard: Error.
titlestring
Ersetzt den Standardtitel type: message.
stacktracestring | array
Ein String oder ein Array aus Zeilen oder Frames { file, line, column, function }, der jüngste Aufruf zuerst.
environmentstring
Wird mit dem Umgebungsfilter des Endpoints abgeglichen. Events ohne Umgebung kommen immer durch.
fingerprintstring
Gruppiert Events desselben Fehlers (siehe „Ein Fix pro Fehler“ unten). Standard: abgeleitet aus dem Typ, der Meldung und dem obersten Stack-Frame.
urlstring
Ein Link zum Fehler in deinem System (http oder https), angezeigt beim Lauf und im Pull Request.
contextobject
Beliebige zusätzliche Details für den Agenten (Request, User, Tags…), als JSON gesendet und auf 4.000 Zeichen gekürzt.
testboolean
Ein Probelauf: meldet, was passieren würde, und startet nichts.

Unbekannte Felder werden ignoriert, null gilt als nicht vorhanden und langer Text wird gekürzt.

Beispiele

Mit curl, aus einem Terminal oder einem Skript:

$ 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" }
  }'

Aus Node.js, zum Beispiel in einem catch-Block:

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;
}

Ein Fix pro Fehler

Der Agent startet einmal pro Fehler: Nach dem ersten Event werden Events mit demselben fingerprint am selben Endpoint übersprungen, auch wenn dieser Lauf fehlgeschlagen ist. Ist er fehlgeschlagen, korrigiere die Einrichtung (etwa einen fehlenden Workflow oder KI-Schlüssel) und klicke auf der Seite des Laufs auf Erneut versuchen.

Standardmäßig werden Zahlen und IDs in der Meldung ignoriert, sodass „User 123 not found“ und „User 456 not found“ derselbe Fehler sind. Du willst einen neuen Fix, wenn ein Fehler in einem späteren Release wieder auftaucht? Sende einen fingerprint, der das Release enthält, z. B. "send-receipt@2.4.1". Er ersetzt den Standardwert, also halte den Rest stabil – keine IDs oder Zeitstempel.

Testen

Füge "test": true hinzu, um die URL und deinen Payload zu prüfen, ohne etwas zu starten. Die Antwort sagt dir, ob ein echtes Event den Agenten starten würde – und falls nicht, warum:

$ 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"
}

Antworten

Jede Antwort ist JSON. Wiederhole nur bei einem 5xx: Derselbe Fehler startet den Agenten nie zweimal, Wiederholen ist also sicher.

202 outcome: "started"
Der Agent wurde gestartet. Der Body enthält runId und status des Laufs.
200 outcome: "skipped"
Nichts gestartet; reason sagt, warum (siehe unten).
200 outcome: "test"
Ein Probelauf; nichts gestartet (siehe „Testen“).
400 error: "invalid_json"
Der Body ist kein gültiges JSON.
400 error: "invalid_payload"
Ein Feld fehlt oder hat den falschen Typ; issues listet jedes Problem mit seinem Pfad auf.
401 error: "unauthorized"
Unbekannter Token: Prüfe die URL – oder der Endpoint hat eine neue URL bekommen oder wurde gelöscht.
413 error: "payload_too_large"
Der Body ist größer als 256 KB.
5xx
Bei uns ist etwas schiefgelaufen. Wiederholen ist sicher.
reason: "duplicate"
Dieser Fehler wurde bereits behandelt; runId ist sein Lauf.
reason: "environment"
Die Umgebung des Events ist nicht im Filter des Endpoints.
reason: "repo_not_connected"
Das Repository des Endpoints ist in der GitHub-Karte nicht ausgewählt.
reason: "limit"
Das monatliche Free-Limit oder das tägliche Sicherheitslimit wurde erreicht; code ist free_limit oder daily_cap.

Halte den Token geheim

  • Sende Events nur von deinem Server, nie aus einem Browser – dort könnte jeder den Token auslesen.
  • Wenn deine Proxys oder Logs URLs aufzeichnen, sende den Token stattdessen im Header Authorization.
  • Wenn die URL nach außen gelangt, erzeuge eine neue für den Endpoint; die alte funktioniert sofort nicht mehr.
  • Alles, was du sendest, wird mit dem Lauf gespeichert und dem KI-Agenten gezeigt – lass also Passwörter, Schlüssel und personenbezogene Daten weg.
05 fehlerbehebung

Alles eingerichtet, aber keine Pull Requests?

Fast immer ist es einer dieser Punkte:

$ bugzero doctor[ 8 Punkte ]
  • Noch keine Verknüpfung Projekt → Repo (Schritt 04) – mit Abstand die häufigste Ursache.
  • Der bugzero-Workflow ist nicht im Standard-Branch, oder das Secret ANTHROPIC_API_KEY / OPENAI_API_KEY fehlt (Schritte 05 und 06). Bei fehlgeschlagenen Läufen steht der Grund auf der Seite des Laufs.
  • Der Fix wurde in einen Branch gepusht, aber es hat sich kein Pull Request geöffnet – GitHub erlaubt Actions nicht, welche zu erstellen (Schritt 07).
  • Die Umgebung des Fehlers ist nicht in deiner Liste überwachter Umgebungen (Schritt 08).
  • Es ist noch kein neuer Fehler aufgetreten – bugzero reagiert auf neue Issues, nicht auf alte.
  • Du hast die 5 Fixes von Free in diesem Monat aufgebraucht, oder das tägliche Sicherheitslimit wurde erreicht – sieh im Dashboard nach.
  • Das Repository ist in der GitHub-Karte nicht ausgewählt (Schritt 02).
  • Du sendest Fehler an einen eigenen Webhook? Seine JSON-Antwort sagt dir, warum ein Event übersprungen wurde; füge "test": true hinzu, um zu prüfen, ohne etwas zu starten.
weiter

Bereit für die Einrichtung?

Erstelle dein Konto und verbinde dein erstes Repository – Free enthält 5 Fixes pro Monat.

5 fixes pro monat gratis →zu den integrationen →