bugzero

~/docs/getting-started

Primeiros passos

O bugzero é um agente de IA que corrige bugs, com uma sala de controle para comandá-lo. Quando algo quebra — reportado pelo Sentry, pelo PostHog ou pelo seu próprio app via webhook —, o agente roda no seu próprio GitHub Actions e abre um pull request com a correção; você comanda tudo de um só painel. Seu código nunca sai da sua infraestrutura. Aqui está tudo o que você precisa configurar e por que cada passo importa.

01 o ciclo

Como um erro vira um pull request.

02 configuração obrigatória

7 passos até a sua primeira correção.

[01]

Crie sua conta

obrigatório

Cadastre-se com seu e-mail e uma senha. Você ganha um espaço de trabalho para a equipe no plano Grátis — 5 correções por mês, sem cartão.

// por quêTudo no bugzero pertence a uma equipe, então depois você pode convidar colegas e compartilhar integrações, a configuração do agente e a cobrança. O plano Grátis deixa você ver correções reais antes de pagar qualquer coisa.
criar sua conta →
[02]

Conecte o GitHub

obrigatório

Na página Integrações, instale o GitHub App do bugzero, escolha a conta ou organização e selecione os repositórios em que o bugzero pode iniciar correções.

// por quêO GitHub App do bugzero não tem acesso ao seu código — a única permissão dele é iniciar o workflow do bugzero no seu próprio GitHub Actions. A correção e o pull request são feitos por esse workflow, dentro do seu runner. Nada recebe merge ou deploy automaticamente.
abrir integrações →
[03]

Conecte uma fonte de erros

obrigatório

Em Integrações → Fontes de erros, conecte o monitor de erros que você já usa e escolha os projetos que o bugzero deve monitorar, ou envie erros do seu próprio app. Você pode usar mais de uma fonte.

  • Sentry — conecte sua organização via OAuth.
  • PostHog — escolha sua região e cole uma chave de API pessoal com os escopos project:read, hog_function:write e query:read.
  • Webhook personalizado — crie um endpoint para cada app e envie os erros para a URL secreta dele a partir de qualquer linguagem ou ferramenta; veja Webhook personalizado mais abaixo.
// por quêErros novos são o gatilho de tudo o que o bugzero faz. No Sentry e no PostHog, o próprio bugzero configura o alerta ou o webhook de cada projeto vinculado — sem webhook manual nem secret de assinatura. Um webhook personalizado funciona ao contrário: é uma URL que você mesmo chama sempre que o seu app captura um erro. De qualquer forma, você escolhe o que é monitorado, então as correções ficam nos serviços que importam para você.
abrir integrações →
[04]

Vincule cada projeto a um repositório

obrigatório

Para cada projeto monitorado, escolha o repositório do GitHub que o agente deve corrigir. Você define isso logo ao lado de cada projeto, na página Integrações. Um endpoint de webhook personalizado recebe o repositório quando você o cria.

// por quêÉ esse vínculo que faz todo o pipeline funcionar. O bugzero precisa saber qual base de código pertence a qual projeto — sem um vínculo, os erros chegam, mas nenhum pull request sai. É o passo mais esquecido.
abrir integrações →
[05]

Adicione o workflow do bugzero

obrigatório

Em Integrações → Configuração do runner, clique em Adicionar workflow ao lado de cada repositório. O GitHub abre com .github/workflows/bugzero.yml já preenchido — revise e faça o commit na sua branch padrão. Depois clique em Verificar de novo.

// por quêÉ esse workflow que de fato executa a correção. Quando um erro dispara, o bugzero o inicia no seu próprio runner do GitHub Actions, onde o agente lê o seu código e abre o pull request — assim, o seu código-fonte nunca sai da sua infraestrutura. Você mesmo adiciona o arquivo porque o bugzero não consegue escrever no seu repositório.
abrir integrações →
[06]

Adicione sua chave de IA como secret do Actions

obrigatório

Em cada repositório conectado, abra Settings → Secrets and variables → Actions e adicione um novo secret chamado ANTHROPIC_API_KEY (ou OPENAI_API_KEY) com a sua própria chave de IA.

// por quêO agente usa essa chave enquanto roda dentro do seu runner do GitHub Actions, então você paga o seu provedor de IA diretamente e o bugzero nunca vê a chave. Ela continua sendo um secret do GitHub Actions no seu repositório e nunca passa pelos nossos servidores.
[07]

Deixe o Actions abrir pull requests

obrigatório

Em cada repositório conectado, abra Settings → Actions → General, role até Workflow permissions, marque Allow GitHub Actions to create and approve pull requests e salve. Se a opção estiver acinzentada, um proprietário da organização precisa permiti-la antes nos próprios Settings → Actions → General da organização.

// por quêO GitHub deixa a opção desativada por padrão, e a permissão pull-requests: write do próprio workflow não a sobrescreve. Sem ela, o agente ainda envia a correção para uma branch, mas o GitHub se recusa a abrir o pull request — você ficaria com uma branch em vez de um PR.
03 opcional

Opcionais, mas recomendados.

[08]

Limite aos ambientes certos

opcional

Em cada vínculo de projeto, marque os ambientes aos quais reagir — por exemplo, só produção. Deixe todos desmarcados para monitorar todos os ambientes. Os endpoints de webhook personalizado têm o mesmo filtro opcional.

// por quêNormalmente você não quer correções para o ruído de local, dev ou staging. Restringir à produção mantém as execuções focadas em bugs reais, que afetam os usuários, e evita gastar o seu limite mensal com erros que não importam.
abrir integrações →
[09]

Configure o agente

opcional

Na página Agente, escolha o modelo e o esforço (os modelos mais recentes do Claude ou do GPT), escreva instruções com as convenções da sua equipe e defina um limite de segurança diário. Cada vez que você publica instruções, elas viram uma nova versão — compare versões, veja o desempenho de cada uma e reverta com um clique.

// por quêAs instruções fazem as correções seguirem as suas convenções (“use nosso logger”, “adicione um teste de regressão”, arquivos que não devem ser tocados), e o modelo e o esforço permitem trocar velocidade e custo por profundidade. Sua chave não é informada aqui — ela continua como secret do Actions no seu repo, então o bugzero só decide como o agente roda, sem nunca pagar nem ver os tokens.
abrir agente →
[10]

Mude para o Pro quando estiver pronto

opcional

O plano Grátis inclui 5 correções por mês. Quando precisar de mais, mude para o Pro — US$ 9/mês com correções ilimitadas — em Cobrança, e gerencie ou cancele pelo portal do cliente.

// por quêSó execuções que abrem um pull request contam como correção — execuções que falham nunca são cobradas. Os tokens de IA são cobrados pelo seu provedor a preço de custo, então o plano é tudo o que você paga ao bugzero.
abrir cobrança →
[11]

Receba sua primeira correção

opcional

Quando um erro novo acontece em um projeto e ambiente monitorados, o bugzero inicia uma execução que termina em um pull request. Acompanhe o progresso na página Execuções, depois abra o PR, leia o diff e o resumo da causa raiz e faça o merge se estiver certo.

// por quêEssa é a recompensa, e ela continua sob o seu controle: cada correção é um pull request que você pode revisar — nada recebe merge ou deploy até você decidir que está certo.
ver execuções →
04 webhook personalizado

Envie erros de qualquer lugar.

Erros que o seu monitor não captura — um worker, um cron job, um script — ou nenhum monitor de erros? Envie-os você mesmo para o bugzero: uma requisição HTTP de qualquer linguagem ou ferramenta, sem SDK.

Em Integrações → Fontes de erros, adicione um endpoint de Webhook personalizado para cada app: um nome, o repositório que o agente corrige, a branch base dele e, opcionalmente, os ambientes aos quais reagir. Cada endpoint ganha a sua própria URL secreta.

criar um endpoint →

Autenticação

O token no final da URL do endpoint o identifica. Chame a URL como ela é ou, em vez disso, envie o token no header Authorization para a URL fixa — melhor se as suas ferramentas registram URLs em log.

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

# ou: token em um header
POST https://bugzero.dev/api/webhooks/custom
Authorization: Bearer bzc_…

Payload

Envie um objeto JSON com Content-Type: application/json, de até 256 KB. Só message é obrigatório.

messagestring · obrigatório
A mensagem de erro.
typestring
A classe do erro, por exemplo TypeError. Padrão: Error.
titlestring
Substitui o título padrão, type: message.
stacktracestring | array
Uma string, ou um array de linhas ou de frames { file, line, column, function }, com a chamada mais recente primeiro.
environmentstring
Comparado com o filtro de ambientes do endpoint. Eventos sem ambiente sempre passam.
fingerprintstring
Agrupa eventos do mesmo erro (veja “Uma correção por erro” abaixo). Padrão: derivado do tipo, da mensagem e do frame do topo da stack.
urlstring
Um link para o erro no seu sistema (http ou https), exibido na execução e no pull request.
contextobject
Quaisquer detalhes extras para o agente (requisição, usuário, tags…), enviados como JSON e cortados em 4.000 caracteres.
testboolean
Uma simulação: informa o que aconteceria sem iniciar nada.

Campos desconhecidos são ignorados, null conta como ausente e textos longos são cortados.

Exemplos

Com curl, de um terminal ou de um 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" }
  }'

Do Node.js, por exemplo em um bloco 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;
}

Uma correção por erro

O agente é iniciado uma vez por erro: depois do primeiro evento, eventos com o mesmo fingerprint no mesmo endpoint são ignorados, mesmo que aquela execução tenha falhado. Se falhou, corrija a configuração (por exemplo, um workflow ou uma chave de IA faltando) e clique em Tentar de novo na página da execução.

Por padrão, números e IDs na mensagem são ignorados, então “Usuário 123 não encontrado” e “Usuário 456 não encontrado” são o mesmo erro. Quer uma nova correção quando um erro volta em uma release posterior? Envie um fingerprint que inclua a release, por exemplo "send-receipt@2.4.1". Ele substitui o padrão, então mantenha o resto estável — sem IDs nem timestamps.

Faça um teste

Adicione "test": true para verificar a URL e o seu payload sem iniciar nada. A resposta diz se um evento real iniciaria o agente e, se não, por quê:

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

Respostas

Toda resposta é JSON. Só tente de novo em caso de erro 5xx: o mesmo erro nunca inicia o agente duas vezes, então tentar de novo é seguro.

202 outcome: "started"
O agente foi iniciado. O corpo inclui o runId e o status da execução.
200 outcome: "skipped"
Nada foi iniciado; reason diz por quê (veja abaixo).
200 outcome: "test"
Uma simulação; nada foi iniciado (veja “Faça um teste”).
400 error: "invalid_json"
O corpo não é um JSON válido.
400 error: "invalid_payload"
Um campo está faltando ou tem o tipo errado; issues lista cada problema com o seu caminho.
401 error: "unauthorized"
Token desconhecido: confira a URL — ou o endpoint ganhou uma nova URL ou foi excluído.
413 error: "payload_too_large"
O corpo passa de 256 KB.
5xx
Algo falhou do nosso lado. Pode tentar de novo com segurança.
reason: "duplicate"
Este erro já foi tratado; runId é a execução dele.
reason: "environment"
O ambiente do evento não está no filtro do endpoint.
reason: "repo_not_connected"
O repositório do endpoint não está selecionado no card do GitHub.
reason: "limit"
O limite mensal do plano Grátis ou o limite de segurança diário foi atingido; code é free_limit ou daily_cap.

Mantenha o token em segredo

  • Envie eventos só do seu servidor, nunca de um navegador — lá qualquer pessoa poderia ler o token.
  • Se os seus proxies ou logs registram URLs, envie o token no header Authorization.
  • Se a URL vazar, gere uma nova para o endpoint; a antiga para de funcionar na hora.
  • Tudo o que você envia fica guardado com a execução e é mostrado ao agente de IA, então não inclua senhas, chaves nem dados pessoais.
05 solução de problemas

Configurou tudo, mas nenhum pull request apareceu?

Quase sempre é uma destas causas:

$ bugzero doctor[ 8 verificações ]
  • Ainda não há vínculo projeto → repo (passo 04) — de longe a causa mais comum.
  • O workflow do bugzero não está na branch padrão, ou falta o secret ANTHROPIC_API_KEY / OPENAI_API_KEY (passos 05 e 06). Execuções que falham mostram o motivo na página da execução.
  • A correção foi enviada para uma branch, mas nenhum pull request foi aberto — o GitHub não deixa o Actions criá-los (passo 07).
  • O ambiente do erro não está na sua lista de ambientes monitorados (passo 08).
  • Ainda não aconteceu nenhum erro novo — o bugzero reage a issues novas, não às antigas.
  • Você já usou as 5 correções do plano Grátis deste mês, ou o limite de segurança diário foi atingido — confira o Painel.
  • O repositório não está selecionado no card do GitHub (passo 02).
  • Enviando erros para um webhook personalizado? A resposta JSON dele diz por que um evento foi ignorado; adicione "test": true para verificar sem iniciar nada.
próximo passo

Pronto para configurar?

Crie sua conta e conecte seu primeiro repositório — o plano Grátis inclui 5 correções por mês.

5 correções grátis por mês →ir para integrações →