← Volver al blog
Dev Agent · Git

Dev Agent: revisa PRs, analiza historias y propone fixes — sin mergear

12 min de lectura

El Dev Agent es el agente de desarrollo de Lumentia: lee tu repositorio, revisa pull requests, analiza historias de usuario y, ante un error, propone un fix abriendo una PR que un humano valida. Funciona con GitHub, GitLab y Bitbucket y la regla de oro es una sola: Lumentia nunca mergea.

Qué puede hacer

Cuatro flujos precargados cubren el ciclo completo de desarrollo:

Requisitos previos

  1. Repositorio conectado: Lumentia necesita un corpus de código de tu repo. Es el requisito de entrada: sin él, el agente queda deshabilitado y de ahí se infiere el repo por defecto.
  2. Token del proveedor: un token de acceso de GitHub, GitLab o Bitbucket. Más abajo está la tabla de permisos por proveedor.
  3. Secreto de webhook (recomendado): si querés recibir eventos entrantes (PRs, issues, errores). Sin él, los webhooks se rechazan con 401.

La herramienta git

La herramienta git ejecuta una acción por llamada, definida desde el paso del flujo. Funciona sobre el proveedor y el repo que configuraste en el panel.

AcciónTipoDescripción
list_prslecturaLista PRs/MRs abiertos.
get_prlecturaDetalle de un PR/MR.
get_difflecturaDiff de un PR/MR.
get_pr_fileslecturaArchivos cambiados de un PR/MR.
get_filelecturaContenido de un archivo del repo.
create_prescrituraAbre una PR/MR (no mergea).
comment_prescrituraPublica un comentario en PR/issue.
set_statusescrituraSetea commit status / check.
commit_pushescrituraCrea una rama con los cambios y pushea.
checkoutlecturaClona el repo a disco (para run_tests).

La herramienta git se invoca desde un paso del flujo indicando la acción y sus parámetros:

// Paso: leer el diff de un PR
{ "type": "execute_tool", "tool_id": "",
  "parameters": { "action": "get_diff", "number": "{{pr_number}}" } }

// Paso: abrir una PR con un fix
{ "type": "execute_tool", "tool_id": "",
  "parameters": { "action": "create_pr", "title": "fix: …", "head": "fix/x", "base": "main" } }

Herramientas de apoyo

Además de git, el Dev Agent trae dos herramientas extra:

{ "type": "run_tests",
  "config": { "provider": "github", "repo": "{{repo}}", "command": "pytest -q",
              "timeout": 300, "memory_limit_mb": 1024 } }

{ "type": "query_logs", "config": { "source": "sentry", "org": "mi-org", "project": "api" } }
{ "type": "query_logs", "config": { "source": "datadog" } }
{ "type": "query_logs", "config": { "source": "generic", "url": "https://logs.miempresa.com/search" } }

Configuración

Todo se configura desde Configuración → Integraciones → Dev Agent (Git):

CampoDefaultQué hace
HabilitadoAutoAuto = se activa si hay un corpus de código; podés forzarlo a Sí o No.
ProveedorGitHubGitHub, GitLab o Bitbucket.
Repo por defecto—owner/repo (o group/project). Si se deja vacío, se infiere del corpus de código.
Rama basemainRama base contra la que se abren las PRs.
Hosts permitidos—Hosts extra para instancias self-hosted o APIs de logs (vacío = solo los oficiales).
Repos permitidos—Qué repos (corpus de código) puede tocar el agente, con toggle por repo (máx. 10). Vacío = todos.
Comentar en PRsActivadoPublicar comentarios y reviews automáticas.
Setear statusActivadoMarcar commit status / checks en el proveedor.
Crear PRsActivadoAbrir la PR con el fix. Si lo apagás, el agente propone el cambio pero no abre la PR.
Secreto del webhook—Secreto compartido con el proveedor para verificar los webhooks entrantes.

Permisos del token

El token que conectes le da al agente exactamente lo que necesita para leer, comentar, setear status y crear PRs — nunca para mergear:

ProveedorQué configurar
GitHubToken clásico con scope repo (repos privados), o token fine-grained con acceso a Contents (lectura/escritura), Pull requests (lectura/escritura), Commit statuses (lectura/escritura) e Issues (lectura/escritura).
GitLabPersonal access token con scope api (o al menos read_api + write_repository).
BitbucketApp password con permisos Repository (read + write), Pull requests (read + write) e Issues (read + write).

Ejemplos de flujos

dev_pr_review lee el diff de un PR, redacta la review y publica comentario + commit status:

{"id": "leer_diff", "type": "execute_tool", "tool_id": "",
 "parameters": {"action": "get_diff", "number": "{{pr_number}}"}},

{"id": "revisar", "type": "llm_extract",
 "prompt": "Analizá el diff y redactá una code review. Devolvé 'review' y 'verdict' (success | failure | pending)."},

{"id": "comentar", "type": "execute_tool", "tool_id": "",
 "parameters": {"action": "comment_pr", "number": "{{pr_number}}", "body": "{{review}}"}},

{"id": "status", "type": "execute_tool", "tool_id": "",
 "parameters": {"action": "set_status", "sha": "{{head_sha}}", "state": "{{verdict}}"}}

dev_incident_fix es el más ilustrativo: de un error a una PR. Consulta logs, propone un fix, hace commit_push y abre la PR:

{"id": "consultar_logs", "type": "execute_tool", "tool_id": "",
 "parameters": {"query": "{{error}} {{service}}"}},

{"id": "diagnosticar", "type": "llm_extract",
 "prompt": "Con el error y los logs, proponé un fix. Devolvé 'archivo', 'fix', 'mensaje', 'rama' y 'titulo_pr'."},

{"id": "commit", "type": "execute_tool", "tool_id": "",
 "parameters": {"action": "commit_push", "branch": "{{rama}}", "base": "{{base_branch}}",
                "message": "{{mensaje}}", "files": [{"path": "{{archivo}}", "content": "{{fix}}"}]}},

{"id": "abrir_pr", "type": "execute_tool", "tool_id": "",
 "parameters": {"action": "create_pr", "title": "{{titulo_pr}}", "head": "{{rama}}",
                "base": "{{base_branch}}"}}

El flujo dev_support_escalation clasifica la causa raíz (código / configuración / datos) y deriva al flujo correcto usando un subflujo: así un chat puede componer al Dev Agent (Widget → detección → fix → PR).

Webhooks por proveedor

Registrá la URL en tu proveedor con el mismo secreto que configuraste en el panel. Los eventos se verifican fail-closed (sin secreto → 401) y se deduplican para no procesar dos veces el mismo evento. En {tu-cuenta} va tu ID de cuenta; la URL completa, ya resuelta, la ves en el botón Webhooks (Dev Agent) de la sección Corpus:

ProveedorRutaVerificación
GitHub/api/v1/git/webhooks/github/{tu-cuenta}HMAC-SHA256 en X-Hub-Signature-256
GitLab/api/v1/git/webhooks/gitlab/{tu-cuenta}token plano en X-Gitlab-Token
Bitbucket/api/v1/git/webhooks/bitbucket/{tu-cuenta}HMAC-SHA256 en X-Hub-Signature
Error/api/v1/git/webhooks/error/{tu-cuenta}X-Lumentia-Signature o X-Hub-Signature-256

GitHub y Bitbucket firman el body con HMAC-SHA256; GitLab manda el secreto tal cual en X-Gitlab-Token.

Seguridad

Cómo empezar

  1. Conectá tu repo como corpus de código.
  2. Creá el token del proveedor con los permisos de la tabla.
  3. Configurá el Dev Agent en Configuración → Integraciones → Dev Agent (Git).
  4. Registrá el webhook en el proveedor con el mismo secreto (URLs de la tabla).
  5. Probá: abrí o actualizá un PR y mirá la review en el proveedor.
El límite es humano. El agente propone, documenta y deja la PR lista; el botón de merge sigue siendo tuyo.