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:
dev_pr_review— lee el diff de un PR y publica una review + commit status.dev_story_review— analiza alcance, criterios de aceptación y documentación de una historia de usuario.dev_incident_fix— ante un error consulta logs (Sentry/Datadog), propone un fix y abre una PR.dev_support_escalation— desde el chat, clasifica la causa raíz (código / configuración / datos) y deriva.
Requisitos previos
- 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.
- Token del proveedor: un token de acceso de GitHub, GitLab o Bitbucket. Más abajo está la tabla de permisos por proveedor.
- 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ón | Tipo | Descripción |
|---|---|---|
list_prs | lectura | Lista PRs/MRs abiertos. |
get_pr | lectura | Detalle de un PR/MR. |
get_diff | lectura | Diff de un PR/MR. |
get_pr_files | lectura | Archivos cambiados de un PR/MR. |
get_file | lectura | Contenido de un archivo del repo. |
create_pr | escritura | Abre una PR/MR (no mergea). |
comment_pr | escritura | Publica un comentario en PR/issue. |
set_status | escritura | Setea commit status / check. |
commit_push | escritura | Crea una rama con los cambios y pushea. |
checkout | lectura | Clona 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:
run_tests— ejecuta un comando de tests sobre una copia aislada del repo, para validar el fix antes de abrir la PR.query_logs— consulta logs y errores de Sentry, Datadog o una API genérica.
{ "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):
| Campo | Default | Qué hace |
|---|---|---|
| Habilitado | Auto | Auto = se activa si hay un corpus de código; podés forzarlo a Sí o No. |
| Proveedor | GitHub | GitHub, GitLab o Bitbucket. |
| Repo por defecto | — | owner/repo (o group/project). Si se deja vacío, se infiere del corpus de código. |
| Rama base | main | Rama 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 PRs | Activado | Publicar comentarios y reviews automáticas. |
| Setear status | Activado | Marcar commit status / checks en el proveedor. |
| Crear PRs | Activado | Abrir 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:
| Proveedor | Qué configurar |
|---|---|
| GitHub | Token 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). |
| GitLab | Personal access token con scope api (o al menos read_api + write_repository). |
| Bitbucket | App 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:
| Proveedor | Ruta | Verificació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
- Nunca mergea: no existe acción de merge; la escritura se limita a crear PR, comentar, setear status y commit+push.
- Credenciales cifradas y acotadas a tu cuenta: cada token se usa solo en el contexto de tu workspace.
- Hosts permitidos: las URLs de proveedores y APIs de logs se validan contra los hosts oficiales (o los que agregues en el panel), para evitar que el token se envíe a un destino ajeno.
- Sin fugas de token: las credenciales se redactan de cualquier mensaje de error antes de mostrarse.
- Protección de rutas: los archivos que el agente toca se validan contra el repo, sin salir de él.
run_testsen sandbox aislado: los tests corren en un entorno controlado.
Cómo empezar
- Conectá tu repo como corpus de código.
- Creá el token del proveedor con los permisos de la tabla.
- Configurá el Dev Agent en Configuración → Integraciones → Dev Agent (Git).
- Registrá el webhook en el proveedor con el mismo secreto (URLs de la tabla).
- Probá: abrí o actualizá un PR y mirá la review en el proveedor.