bugzero

~/docs/getting-started

Pierwsze kroki

bugzero to agent AI do naprawiania bugów i centrum sterowania, z którego nim kierujesz. Gdy coś się zepsuje — a zgłosi to Sentry, PostHog albo twoja aplikacja przez webhook — agent uruchamia się w twoim własnym GitHub Actions i otwiera pull request z poprawką; ty sterujesz nim z jednego panelu. Twój kod nigdy nie opuszcza twojej infrastruktury. Oto wszystko, co trzeba skonfigurować, i dlaczego każdy krok ma znaczenie.

01 pętla

Jak błąd zamienia się w pull request.

02 wymagana konfiguracja

7 kroków do pierwszej poprawki.

[01]

Załóż konto

wymagany

Zarejestruj się, podając e-mail i hasło. Dostaniesz przestrzeń zespołu w planie Darmowym — 5 poprawek miesięcznie, bez karty.

// dlaczegoWszystko w bugzero należy do zespołu, więc później możesz zaprosić współpracowników i dzielić z nimi integracje, konfigurację agenta i płatności. Plan Darmowy pozwala zobaczyć prawdziwe poprawki, zanim cokolwiek zapłacisz.
załóż konto →
[02]

Połącz GitHub

wymagany

Na stronie Integracje zainstaluj GitHub App bugzero, wybierz konto lub organizację i zaznacz repozytoria, w których bugzero może uruchamiać poprawki.

// dlaczegoGitHub App bugzero nie ma dostępu do twojego kodu — jej jedyne uprawnienie to uruchamianie workflow bugzero w twoim własnym GitHub Actions. Poprawkę i pull request tworzy ten workflow, w twoim runnerze. Żaden merge ani deploy nie dzieje się automatycznie.
otwórz integracje →
[03]

Połącz źródło błędów

wymagany

W sekcji Integracje → Źródła błędów połącz narzędzie do śledzenia błędów, którego już używasz, i wybierz projekty, które bugzero ma obserwować — albo wysyłaj błędy z własnej aplikacji. Możesz korzystać z kilku źródeł naraz.

  • Sentry — połącz swoją organizację przez OAuth.
  • PostHog — wybierz region i wklej osobisty klucz API z uprawnieniami project:read, hog_function:write i query:read.
  • Własny webhook — utwórz endpoint dla każdej aplikacji i wysyłaj błędy na jego tajny URL z dowolnego języka lub narzędzia; zobacz Własny webhook poniżej.
// dlaczegoNowe błędy są wyzwalaczem wszystkiego, co robi bugzero. W przypadku Sentry i PostHog bugzero samo konfiguruje alert lub webhook dla każdego powiązanego projektu — bez ręcznego webhooka i sekretu do podpisywania. Własny webhook działa odwrotnie: to URL, który wywołujesz ty, gdy twoja aplikacja złapie błąd. Tak czy inaczej to ty decydujesz, co jest obserwowane, więc poprawki dotyczą usług, na których ci zależy.
otwórz integracje →
[04]

Powiąż każdy projekt z repozytorium

wymagany

Dla każdego obserwowanego projektu wybierz repozytorium GitHub, które agent ma naprawiać. Ustawiasz to tuż obok projektu, na stronie Integracje. Endpoint własnego webhooka dostaje repozytorium już przy tworzeniu.

// dlaczegoTo powiązanie sprawia, że cały mechanizm działa. bugzero musi wiedzieć, który kod należy do którego projektu — bez powiązania błędy przychodzą, ale żaden pull request nie powstaje. To krok, o którym najczęściej się zapomina.
otwórz integracje →
[05]

Dodaj workflow bugzero

wymagany

W sekcji Integracje → Konfiguracja runnera kliknij Dodaj workflow obok każdego repozytorium. GitHub otworzy się z wypełnionym plikiem .github/workflows/bugzero.yml — przejrzyj go i zrób commit do domyślnej gałęzi. Potem kliknij Sprawdź ponownie.

// dlaczegoTo właśnie ten workflow przeprowadza naprawę. Gdy pojawi się błąd, bugzero uruchamia go w twoim własnym runnerze GitHub Actions, gdzie agent czyta twój kod i otwiera pull request — więc twój kod źródłowy nigdy nie opuszcza twojej infrastruktury. Plik dodajesz ty, bo bugzero nie ma prawa zapisu w twoim repozytorium.
otwórz integracje →
[06]

Dodaj klucz AI jako sekret Actions

wymagany

W każdym połączonym repozytorium otwórz Settings → Secrets and variables → Actions i dodaj nowy sekret o nazwie ANTHROPIC_API_KEY (lub OPENAI_API_KEY) z twoim własnym kluczem AI.

// dlaczegoAgent używa tego klucza, działając w twoim runnerze GitHub Actions, więc płacisz dostawcy AI bezpośrednio, a bugzero nigdy nie widzi klucza. Pozostaje on sekretem GitHub Actions w twoim repozytorium i nigdy nie trafia na nasze serwery.
[07]

Pozwól Actions otwierać pull requesty

wymagany

W każdym połączonym repozytorium otwórz Settings → Actions → General, przewiń do Workflow permissions, zaznacz Allow GitHub Actions to create and approve pull requests i zapisz. Jeśli opcja jest wyszarzona, właściciel organizacji musi najpierw zezwolić na nią we własnych Settings → Actions → General organizacji.

// dlaczegoGitHub domyślnie ma tę opcję wyłączoną, a uprawnienie pull-requests: write w samym workflow jej nie nadpisuje. Bez niej agent nadal wypycha poprawkę na gałąź, ale GitHub odmawia otwarcia pull requesta — dostajesz gałąź zamiast PR-a.
03 opcjonalnie

Opcjonalne, ale zalecane.

[08]

Ogranicz do właściwych środowisk

opcjonalny

W każdym powiązaniu projektu zaznacz środowiska, na które agent ma reagować — na przykład tylko production. Jeśli nie zaznaczysz żadnego, obserwowane są wszystkie środowiska. Endpointy własnych webhooków mają ten sam opcjonalny filtr.

// dlaczegoZwykle nie chcesz poprawek dla szumu z local, dev czy staging. Ograniczenie do produkcji skupia uruchomienia na prawdziwych bugach, które dotykają użytkowników, i nie marnuje miesięcznego limitu na błędy bez znaczenia.
otwórz integracje →
[09]

Skonfiguruj agenta

opcjonalny

Na stronie Agent wybierz model i poziom wysiłku (najnowsze modele Claude lub GPT), napisz instrukcje z konwencjami twojego zespołu i ustaw dzienny limit bezpieczeństwa. Każda publikacja instrukcji tworzy nową wersję — porównuj wersje, sprawdzaj, jak radzi sobie każda z nich, i cofaj zmiany jednym kliknięciem.

// dlaczegoDzięki instrukcjom poprawki trzymają się twoich konwencji („używaj naszego loggera”, „dodaj test regresji”, pliki, których nie wolno ruszać), a model i wysiłek pozwalają wymienić szybkość i koszt na głębię. Klucza nie wpisujesz tutaj — zostaje sekretem Actions w twoim repo, więc bugzero decyduje tylko o tym, jak działa agent, a za tokeny nigdy nie płaci i ich nie widzi.
otwórz agenta →
[10]

Przejdź na Pro, kiedy zechcesz

opcjonalny

Plan Darmowy obejmuje 5 poprawek miesięcznie. Gdy potrzebujesz więcej, przejdź w Płatnościach na Pro — 9 USD miesięcznie za poprawki bez limitu, a subskrypcją zarządzaj lub anuluj ją w portalu klienta.

// dlaczegoTylko uruchomienia, które otwierają pull request, liczą się jako poprawka — za nieudane uruchomienia nigdy nie płacisz. Tokeny AI rozlicza twój dostawca bez marży, więc bugzero płacisz wyłącznie za plan.
otwórz płatności →
[11]

Odbierz pierwszą poprawkę

opcjonalny

Gdy w obserwowanym projekcie i środowisku pojawi się nowy błąd, bugzero rozpocznie uruchomienie zakończone pull requestem. Śledź postęp na stronie Uruchomienia, a potem otwórz PR, przeczytaj diff i podsumowanie przyczyny źródłowej i zrób merge, jeśli wszystko się zgadza.

// dlaczegoTo jest nagroda, a kontrola wciąż należy do ciebie: każda poprawka to pull request do przejrzenia — żaden merge ani deploy nie nastąpi, dopóki nie uznasz, że wszystko jest w porządku.
zobacz uruchomienia →
04 własny webhook

Wysyłaj błędy z czegokolwiek.

Błędy, których nie łapie twoje narzędzie — z workera, crona, skryptu — albo w ogóle nie używasz narzędzia do śledzenia błędów? Wysyłaj je prosto do bugzero: jedno żądanie HTTP z dowolnego języka lub narzędzia, bez SDK.

W sekcji Integracje → Źródła błędów dodaj endpoint typu Własny webhook dla każdej aplikacji: nazwę, repozytorium, które naprawia agent, jego gałąź bazową i opcjonalnie środowiska, na które ma reagować. Każdy endpoint dostaje własny tajny URL.

utwórz endpoint →

Uwierzytelnianie

Token na końcu URL-a endpointu go identyfikuje. Wywołaj URL w tej postaci albo wyślij token w nagłówku Authorization na stały URL — to lepsze, jeśli twoje narzędzia zapisują URL-e w logach.

request.http
# token w URL-u
POST https://bugzero.dev/api/webhooks/custom/bzc_…

# albo: token w nagłówku
POST https://bugzero.dev/api/webhooks/custom
Authorization: Bearer bzc_…

Payload

Wyślij obiekt JSON z Content-Type: application/json, maksymalnie 256 KB. Wymagane jest tylko message.

messagestring · wymagany
Treść błędu.
typestring
Klasa błędu, np. TypeError. Domyślnie: Error.
titlestring
Zastępuje domyślny tytuł, type: message.
stacktracestring | array
Tekst albo tablica linii lub ramek { file, line, column, function }, zaczynając od najnowszego wywołania.
environmentstring
Porównywane z filtrem środowisk endpointu. Zdarzenia bez środowiska zawsze przechodzą.
fingerprintstring
Grupuje zdarzenia tego samego błędu (zob. „Jedna poprawka na błąd” poniżej). Domyślnie: wyliczany z typu, komunikatu i najwyższej ramki stosu.
urlstring
Link do błędu w twoim systemie (http lub https), widoczny przy uruchomieniu i w pull requeście.
contextobject
Dowolne dodatkowe szczegóły dla agenta (żądanie, użytkownik, tagi…), wysyłane jako JSON i przycinane do 4000 znaków.
testboolean
Próba na sucho: pokazuje, co by się stało, i niczego nie uruchamia.

Nieznane pola są ignorowane, null oznacza brak wartości, a za długie teksty są przycinane.

Przykłady

Przez curl, z terminala lub skryptu:

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

Z Node.js, na przykład w bloku 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;
}

Jedna poprawka na błąd

Agent uruchamia się raz na błąd: po pierwszym zdarzeniu kolejne zdarzenia z tym samym fingerprint w tym samym endpoincie są pomijane, nawet jeśli tamto uruchomienie się nie powiodło. Jeśli tak się stało, popraw konfigurację (np. brakujący workflow lub klucz AI) i kliknij Ponów na stronie uruchomienia.

Domyślnie liczby i identyfikatory w komunikacie są ignorowane, więc „Nie znaleziono użytkownika 123” i „Nie znaleziono użytkownika 456” to ten sam błąd. Chcesz nowej poprawki, gdy błąd wróci w późniejszym wydaniu? Wyślij fingerprint zawierający wydanie, np. "send-receipt@2.4.1". Zastępuje on domyślny, więc resztę utrzymuj stałą — bez identyfikatorów i znaczników czasu.

Przetestuj

Dodaj "test": true, żeby sprawdzić URL i payload bez uruchamiania czegokolwiek. Odpowiedź powie ci, czy prawdziwe zdarzenie uruchomiłoby agenta, a jeśli nie — dlaczego:

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

Odpowiedzi

Każda odpowiedź to JSON. Ponawiaj tylko przy 5xx: ten sam błąd nigdy nie uruchomi agenta dwa razy, więc ponawianie jest bezpieczne.

202 outcome: "started"
Agent wystartował. Treść odpowiedzi zawiera runId i status uruchomienia.
200 outcome: "skipped"
Nic nie zostało uruchomione; reason mówi dlaczego (zob. niżej).
200 outcome: "test"
Próba na sucho; nic nie zostało uruchomione (zob. „Przetestuj”).
400 error: "invalid_json"
Treść nie jest poprawnym JSON-em.
400 error: "invalid_payload"
Brakuje pola albo ma ono zły typ; issues wymienia każdy problem wraz ze ścieżką.
401 error: "unauthorized"
Nieznany token: sprawdź URL — albo endpoint dostał nowy URL lub został usunięty.
413 error: "payload_too_large"
Treść przekracza 256 KB.
5xx
Coś poszło nie tak po naszej stronie. Możesz bezpiecznie ponowić.
reason: "duplicate"
Ten błąd został już obsłużony; runId to jego uruchomienie.
reason: "environment"
Środowiska zdarzenia nie ma w filtrze endpointu.
reason: "repo_not_connected"
Repozytorium endpointu nie jest zaznaczone na karcie GitHub.
reason: "limit"
Osiągnięto miesięczny limit planu Darmowego albo dzienny limit bezpieczeństwa; code to free_limit lub daily_cap.

Trzymaj token w tajemnicy

  • Wysyłaj zdarzenia tylko z serwera, nigdy z przeglądarki — tam każdy mógłby odczytać token.
  • Jeśli twoje proxy lub logi zapisują URL-e, wysyłaj token w nagłówku Authorization.
  • Jeśli URL wycieknie, wygeneruj nowy dla endpointu; stary natychmiast przestanie działać.
  • Wszystko, co wyślesz, jest zapisywane razem z uruchomieniem i pokazywane agentowi AI, więc nie wysyłaj haseł, kluczy ani danych osobowych.
05 rozwiązywanie problemów

Wszystko skonfigurowane, a pull requestów brak?

Prawie zawsze chodzi o jedną z tych rzeczy:

$ bugzero doctor[ 8 punktów do sprawdzenia ]
  • Brak powiązania projekt → repo (krok 04) — zdecydowanie najczęstsza przyczyna.
  • Workflow bugzero nie jest dodany do domyślnej gałęzi albo brakuje sekretu ANTHROPIC_API_KEY / OPENAI_API_KEY (kroki 05 i 06). Nieudane uruchomienia pokazują przyczynę na swojej stronie.
  • Poprawka trafiła na gałąź, ale pull request się nie otworzył — GitHub nie pozwala Actions ich tworzyć (krok 07).
  • Środowiska błędu nie ma na liście obserwowanych (krok 08).
  • Nie wystąpił jeszcze żaden nowy błąd — bugzero reaguje na nowe zgłoszenia, nie na historyczne.
  • W tym miesiącu wykorzystano już 5 poprawek z planu Darmowego albo osiągnięto dzienny limit bezpieczeństwa — sprawdź Panel.
  • Repozytorium nie jest zaznaczone na karcie GitHub (krok 02).
  • Wysyłasz błędy na własny webhook? Jego odpowiedź JSON mówi, dlaczego zdarzenie zostało pominięte; dodaj "test": true, żeby to sprawdzić bez uruchamiania czegokolwiek.
dalej

Zaczynamy?

Załóż konto i połącz pierwsze repozytorium — plan Darmowy obejmuje 5 poprawek miesięcznie.

co miesiąc 5 poprawek gratis →przejdź do integracji →