bugzero

~/docs/getting-started

Primeros pasos

bugzero es un agente de IA que corrige bugs, y la sala de control para dirigirlo. Cuando algo falla, ya sea que lo reporte Sentry, PostHog o tu propia app mediante un webhook, el agente se ejecuta en tus propias GitHub Actions y abre un pull request con la corrección; tú lo diriges desde un solo panel. Tu código nunca sale de tu infraestructura. Aquí tienes todo lo que necesitas configurar y por qué importa cada paso.

01 el ciclo

Cómo un error se convierte en un pull request.

02 configuración obligatoria

7 pasos hasta tu primera corrección.

[01]

Crea tu cuenta

obligatorio

Solo necesitas un correo electrónico y una contraseña. Tendrás un espacio de trabajo de equipo en el plan Gratis: 5 correcciones al mes, sin tarjeta.

// por quéTodo en bugzero pertenece a un equipo, así que más adelante puedes invitar a tus colegas y compartir las integraciones, la configuración del agente y la facturación. Con el plan Gratis ves correcciones reales antes de pagar nada.
crear tu cuenta →
[02]

Conecta GitHub

obligatorio

En la página Integraciones, instala la GitHub App de bugzero, elige la cuenta u organización y selecciona los repositorios en los que bugzero puede iniciar correcciones.

// por quéLa GitHub App de bugzero no tiene acceso a tu código: su único permiso es iniciar el workflow de bugzero en tus propias GitHub Actions. La corrección y el pull request los crea ese workflow, dentro de tu runner. Nunca se hace merge ni deploy de nada automáticamente.
abrir integraciones →
[03]

Conecta una fuente de errores

obligatorio

En Integraciones → Fuentes de errores, conecta el monitor de errores que ya usas y elige los proyectos que bugzero debe vigilar, o envía los errores desde tu propia app. Puedes usar más de una fuente.

  • Sentry: conecta tu organización mediante OAuth.
  • PostHog: elige tu región y pega una clave de API personal con los permisos project:read, hog_function:write y query:read.
  • Webhook personalizado: crea un endpoint para cada app y envía los errores a su URL secreta desde cualquier lenguaje o herramienta; consulta Webhook personalizado más abajo.
// por quéLos errores nuevos son el disparador de todo lo que hace bugzero. Con Sentry y PostHog, bugzero configura por sí mismo la alerta o el webhook de cada proyecto vinculado (sin webhooks manuales ni secretos de firma). Un webhook personalizado funciona al revés: es una URL a la que llamas tú cada vez que tu app captura un error. En cualquier caso, tú eliges qué se vigila, así que las correcciones se centran en los servicios que te importan.
abrir integraciones →
[04]

Vincula cada proyecto a un repositorio

obligatorio

Para cada proyecto que vigilas, elige el repositorio de GitHub que el agente debe corregir. Lo configuras justo al lado de cada proyecto, en la página Integraciones. Para un endpoint de webhook personalizado, eliges el repositorio al crearlo.

// por quéEsta vinculación es lo que hace funcionar todo el proceso. bugzero necesita saber qué código pertenece a qué proyecto: sin una vinculación, los errores llegan pero no sale ningún pull request. Es el paso que más se olvida.
abrir integraciones →
[05]

Agrega el workflow de bugzero

obligatorio

En Integraciones → Configuración del runner, haz clic en Agregar workflow junto a cada repositorio. GitHub se abre con .github/workflows/bugzero.yml ya completado: revísalo y haz commit en tu rama predeterminada. Luego haz clic en Verificar de nuevo.

// por quéEste workflow es el que realmente ejecuta la corrección. Cuando salta un error, bugzero lo inicia en tu propio runner de GitHub Actions, donde el agente lee tu código y abre el pull request: tu código fuente nunca sale de tu infraestructura. El archivo lo agregas tú porque bugzero no puede escribir en tu repositorio.
abrir integraciones →
[06]

Agrega tu clave de IA como secreto de Actions

obligatorio

En cada repositorio conectado, abre Settings → Secrets and variables → Actions y agrega un secreto nuevo llamado ANTHROPIC_API_KEY (o OPENAI_API_KEY) con tu propia clave de IA.

// por quéEl agente usa esta clave mientras se ejecuta dentro de tu runner de GitHub Actions, así que le pagas directamente a tu proveedor de IA y bugzero nunca ve la clave. Queda guardada como secreto de GitHub Actions en tu repositorio y nunca pasa por nuestros servidores.
[07]

Permite que Actions abra pull requests

obligatorio

En cada repositorio conectado, abre Settings → Actions → General, baja hasta Workflow permissions, marca Allow GitHub Actions to create and approve pull requests y guarda. Si la opción aparece atenuada, un propietario de la organización tiene que permitirla antes en los Settings → Actions → General de la propia organización.

// por quéGitHub lo deja desactivado por defecto, y el permiso pull-requests: write del propio workflow no lo anula. Sin él, el agente igualmente sube su corrección a una rama, pero GitHub se niega a abrir el pull request: tendrías una rama en lugar de un PR.
03 opcional

Opcionales, pero recomendados.

[08]

Elige los entornos adecuados

opcional

En cada vinculación de proyecto, marca los entornos a los que debe reaccionar; por ejemplo, solo producción. Si no marcas ninguno, se vigilan todos los entornos. Los endpoints de webhook personalizado tienen el mismo filtro opcional.

// por quéNormalmente no quieres correcciones por el ruido de local, dev o staging. Limitarte a producción centra las ejecuciones en bugs reales que afectan a los usuarios y evita gastar tu límite mensual en errores que no importan.
abrir integraciones →
[09]

Configura el agente

opcional

En la página Agente, elige el modelo y el esfuerzo (los modelos más recientes de Claude o GPT), escribe instrucciones con las convenciones de tu equipo y define un límite de seguridad diario. Cada vez que publicas instrucciones se crea una versión nueva: compara versiones, mira cómo rinde cada una y revierte con un clic.

// por quéLas instrucciones hacen que las correcciones sigan tus convenciones (“usa nuestro logger”, “agrega un test de regresión”, archivos que no se deben tocar), y el modelo y el esfuerzo te permiten cambiar velocidad y costo por profundidad. Tu clave no se configura aquí: sigue siendo un secreto de Actions en tu repo, así que bugzero solo decide cómo se ejecuta el agente; nunca paga ni ve los tokens.
abrir agente →
[10]

Pásate a Pro cuando lo necesites

opcional

El plan Gratis incluye 5 correcciones al mes. Cuando necesites más, pásate desde Facturación a Pro: correcciones ilimitadas por 9 US$ al mes, y administra o cancela tu suscripción en el portal de facturación.

// por quéSolo las ejecuciones que abren un pull request cuentan como corrección: las ejecuciones fallidas nunca se te cobran. Tu proveedor factura los tokens de IA a precio de costo, así que a bugzero solo le pagas el plan.
abrir facturación →
[11]

Recibe tu primera corrección

opcional

Cuando un error nuevo llega a un proyecto y entorno vigilados, bugzero inicia una ejecución que termina en un pull request. Sigue el progreso en la página Ejecuciones; después abre el PR, lee el diff y el resumen de la causa raíz, y haz merge si está bien.

// por quéEsta es la recompensa, y sigue bajo tu control: cada corrección es un pull request que puedes revisar; no se hace merge ni deploy de nada hasta que tú decidas que está bien.
ver ejecuciones →
04 webhook personalizado

Envía errores desde cualquier lugar.

¿Errores que tu monitor no captura (un worker, un cron job, un script) o no usas ningún monitor de errores? Envíalos directamente a bugzero: una petición HTTP desde cualquier lenguaje o herramienta, sin SDK.

En Integraciones → Fuentes de errores, agrega un endpoint de Webhook personalizado para cada app: un nombre, el repositorio que corrige el agente, su rama base y, opcionalmente, los entornos a los que debe reaccionar. Cada endpoint tiene su propia URL secreta.

crear un endpoint →

Autenticación

El token al final de la URL del endpoint lo identifica. Llama a la URL tal cual o, si tus herramientas registran las URL, envía el token en el encabezado Authorization a la URL fija.

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

# o bien: token en un encabezado
POST https://bugzero.dev/api/webhooks/custom
Authorization: Bearer bzc_…

Payload

Envía un objeto JSON con Content-Type: application/json, de hasta 256 KB. Solo message es obligatorio.

messagestring · obligatorio
El mensaje del error.
typestring
La clase del error, p. ej. TypeError. Predeterminado: Error.
titlestring
Reemplaza el título predeterminado, type: message.
stacktracestring | array
Un texto, o un array de líneas o de frames { file, line, column, function }, con la llamada más reciente primero.
environmentstring
Se compara con el filtro de entornos del endpoint. Los eventos sin entorno siempre pasan.
fingerprintstring
Agrupa los eventos del mismo error (consulta “Una corrección por error” más abajo). Predeterminado: se calcula a partir del tipo, el mensaje y el primer frame del stack trace.
urlstring
Un enlace al error en tu sistema (http o https), que se muestra en la ejecución y en el pull request.
contextobject
Cualquier detalle adicional para el agente (petición, usuario, etiquetas…), que se envía como JSON y se recorta a 4000 caracteres.
testboolean
Una prueba: indica qué pasaría sin iniciar nada.

Los campos desconocidos se ignoran, null cuenta como ausente y los textos largos se recortan.

Ejemplos

Con curl, desde una terminal o 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" }
  }'

Desde Node.js, por ejemplo en un bloque 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;
}

Una corrección por error

El agente se inicia una sola vez por error: tras el primer evento, los eventos con el mismo fingerprint en el mismo endpoint se omiten, aunque esa ejecución haya fallado. Si falló, corrige la configuración (por ejemplo, si falta el workflow o la clave de IA) y haz clic en Reintentar en la página de la ejecución.

De forma predeterminada, los números y los identificadores del mensaje se ignoran, así que “Usuario 123 no encontrado” y “Usuario 456 no encontrado” son el mismo error. ¿Quieres una nueva corrección cuando un error reaparece en una versión posterior? Envía un fingerprint que incluya la versión, p. ej. "send-receipt@2.4.1". Reemplaza al predeterminado, así que mantén fijo el resto: sin identificadores ni marcas de tiempo.

Pruébalo

Agrega "test": true para probar la URL y tu payload sin iniciar nada. La respuesta te indica si un evento real iniciaría el agente y, si no, 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"
}

Respuestas

Todas las respuestas son JSON. Reintenta solo ante un 5xx: el mismo error nunca inicia el agente dos veces, así que reintentar es seguro.

202 outcome: "started"
El agente se inició. El cuerpo incluye el runId y el status de la ejecución.
200 outcome: "skipped"
No se inició nada; reason indica por qué (ver abajo).
200 outcome: "test"
Una prueba: no se inició nada (consulta “Pruébalo”).
400 error: "invalid_json"
El cuerpo no es un JSON válido.
400 error: "invalid_payload"
Falta un campo o tiene un tipo incorrecto; issues enumera cada problema con su ruta.
401 error: "unauthorized"
Token desconocido: revisa la URL, o puede que el endpoint tenga una URL nueva o se haya eliminado.
413 error: "payload_too_large"
El cuerpo supera los 256 KB.
5xx
Algo falló de nuestro lado. Puedes reintentar sin problema.
reason: "duplicate"
Este error ya se procesó; runId es su ejecución.
reason: "environment"
El entorno del evento no está en el filtro del endpoint.
reason: "repo_not_connected"
El repositorio del endpoint no está seleccionado en la tarjeta de GitHub.
reason: "limit"
Se alcanzó el límite mensual del plan Gratis o el límite de seguridad diario; code es free_limit o daily_cap.

Mantén el token en secreto

  • Envía los eventos solo desde tu servidor, nunca desde un navegador: ahí cualquiera podría leer el token.
  • Si tus proxies o registros guardan las URL, envía el token en el encabezado Authorization.
  • Si la URL se filtra, genera una nueva para el endpoint; la anterior deja de funcionar de inmediato.
  • Todo lo que envías se guarda con la ejecución y lo ve el agente de IA, así que no incluyas contraseñas, claves ni datos personales.
05 solución de problemas

¿Lo configuraste todo y no aparece ningún pull request?

Casi siempre es por una de estas causas:

$ bugzero doctor[ 8 verificaciones ]
  • Aún no hay ninguna vinculación proyecto → repo (paso 04): es, con diferencia, la causa más común.
  • El workflow de bugzero no está en la rama predeterminada, o falta el secreto ANTHROPIC_API_KEY / OPENAI_API_KEY (pasos 05 y 06). Las ejecuciones fallidas muestran el motivo en su página.
  • La corrección se subió a una rama pero no se abrió ningún pull request: GitHub no deja que Actions los cree (paso 07).
  • El entorno del error no está en tu lista de entornos vigilados (paso 08).
  • Todavía no ha ocurrido ningún error nuevo: bugzero reacciona a incidencias nuevas, no a las antiguas.
  • Ya usaste las 5 correcciones del plan Gratis de este mes, o se alcanzó el límite de seguridad diario: revisa el Panel.
  • El repositorio no está seleccionado en la tarjeta de GitHub (paso 02).
  • ¿Envías errores a un webhook personalizado? Su respuesta JSON indica por qué se omitió un evento; agrega "test": true para comprobarlo sin iniciar nada.
siguiente

¿Todo listo para empezar?

Crea tu cuenta y conecta tu primer repositorio: el plan Gratis incluye 5 correcciones al mes.

5 correcciones gratis al mes →ir a integraciones →