logo
icon

ghpool

Proxy de la API de GitHub que agrupa múltiples PAT para compartir el presupuesto de límite de tasa, almacena en caché las respuestas de lectura en memoria y pasa las mutaciones con la autenticación del propio cliente. Diseñado para configuraciones multi-agente (OpenAB, OpenClaw, coding agents personalizados) que comparten los mismos repos.

template cover
Implementado0 veces
EditorzeaburZeabur
Creado2026-05-29
SourceView Source
Mínimo1 Núcleos1 GB
Recomendado1 Núcleos1 GB
Etiquetas
Developer ToolsGitHubAI

Servicios

service icon

ghpool

ghcr.io/openabdev/ghpool:0.2.1

ghpool

ghpool es un proxy de la API de GitHub diseñado para configuraciones multi-agente donde varios coding agents (bots de OpenAB, workers de OpenClaw, agents personalizados) comparten los mismos repos y agotan los límites de tasa por token de GitHub.

Hace tres cosas:

  • Agrupa PATs para lecturas — cada solicitud GET se enruta a través de la identidad con más presupuesto de límite de tasa restante, así múltiples agents comparten un presupuesto combinado en lugar de cada uno alcanzar su propio techo
  • Cachea respuestas de lectura — los resultados de REST GET y GraphQL query se almacenan en caché en memoria con TTLs por recurso (PR view 30s, run list 15s, repo view 5min, etc.)
  • Pasa mutaciones a través — POST/PATCH/DELETE y mutaciones GraphQL requieren el header Authorization del cliente y se reenvían con ese token, así el log de auditoría de GitHub aún muestra qué agent hizo la escritura

Arquitectura

Esta plantilla despliega ghpool como un servicio solo interno:

  • No se enlaza dominio público — ghpool es accedido por servicios hermanos en el mismo proyecto Zeabur a través de la red de contenedores
  • El puerto 8080 se expone como TCP (sin Ingress, sin terminación TLS)
  • El reenvío de puertos está deshabilitado por defecto; habilítalo en la pestaña Networking si necesitas probar desde fuera

Los servicios hermanos se conectan usando estas variables de entorno (auto-expuestas):

VariableValor
GHPOOL_HOSTNAMEhostname del contenedor (p. ej. ghpool.zeabur.internal)
GHPOOL_BASE_URLURL base completa (p. ej. http://ghpool.zeabur.internal:8080)

Apuntar clientes a ghpool

Cómo enrutar un cliente a través de ghpool depende de qué sea:

Coding agents (Claude Code, Codex, agents personalizados): la mayoría honra GITHUB_API_BASE para sobrescribir el endpoint de la API de GitHub.

export GITHUB_API_BASE=${GHPOOL_BASE_URL}

gh CLI: usa el shim ghp que viene con ghpool — un reemplazo drop-in que enruta lecturas a través de ghpool y escrituras a través del gh real. El gh plano no soporta completamente las sobrescrituras de URL base (comandos integrados como gh issue list usan GraphQL internamente y la evitan); ghp es la ruta confiable.

HTTP directo:

curl ${GHPOOL_BASE_URL}/repos/owner/repo

Las escrituras siempre requieren el header Authorization del propio cliente — ghpool nunca inyecta uno para mutaciones, así que el log de auditoría de GitHub aún muestra qué agent hizo la escritura.

Añadir más PATs

La plantilla inicializa el pool con un PAT (GHPOOL_PAT_DEFAULT). Para añadir más:

  1. Abre la pestaña Variables del servicio ghpool
  2. Añade una nueva variable de entorno nombrada GHPOOL_PAT_<ID> (p. ej. GHPOOL_PAT_BOT_CLAUDE, GHPOOL_PAT_BOT_CODEX) con el PAT como valor — el <ID> se convierte en el nombre de la identidad reportado por /stats
  3. Reinicia el servicio para que la nueva identidad sea detectada

Cualquier variable de entorno que coincida con el prefijo GHPOOL_PAT_* se descubre automáticamente.

Endpoints

PathPropósito
GET /<github-api-path>GET proxy de la API REST de GitHub (agrupado + cacheado)
POST /graphqlGraphQL — queries agrupadas+cacheadas, mutaciones pasan con autenticación del cliente
GET /healthzVerificación de salud
GET /statsPresupuestos del pool, ratios de aciertos de caché, estadísticas por identidad

Notas de seguridad

  • Los PATs se mantienen solo en variables de entorno — nunca se escriben al disco dentro del contenedor
  • GHPOOL_ALLOWED_OWNERS se aplica: solicitudes a cualquier org/usuario no en esta lista devuelven 403, así un PAT filtrado solo expone los repos que listaste explícitamente
  • Las mutaciones siempre requieren un header Authorization del cliente (sin autenticación = 401), así el proxy no se puede usar como puerta de escritura anónima

Recursos

ghpool es un binario Rust único (imagen distroless) — extremadamente ligero. La memoria está dominada por la caché en memoria (max 10000 entradas por defecto). Si haces proxy de un volumen de solicitudes muy alto, aumenta la RAM proporcionalmente.

Enlaces y licencia