Autoalojamiento de Sweep con Docker y credenciales privadas de GitHub App: Guía de ingeniería para la automatización local de código

Los equipos de ingeniería que operan en sectores con estrictos requisitos regulatorios —como finanzas, salud, defensa e infraestructura crítica— a menudo enfrentan una barrera insalvable al evaluar agentes autónomos de codificación: las políticas corporativas prohíben estrictamente enviar código fuente propietario a nubes públicas multiinquilino. Sweep (repositorio sweepai/sweep) resuelve este dilema mediante su arquitectura abierta y autocontenida. Al desplegar el backend de Sweep en una nube privada virtual (VPC) o en servidores locales mediante Docker y enlazarlo con una GitHub App privada dedicada, los ingenieros de DevOps pueden automatizar todo el ciclo de vida desde la apertura de un Issue hasta la creación de un Pull Request (PR), manteniendo el análisis sintáctico, la indexación de repositorios y las operaciones de Git íntegramente dentro del perímetro corporativo.

Esta guía detalla el diseño arquitectónico, el dimensionamiento de hardware, la configuración de permisos mínimos en GitHub App, la orquestación de contenedores y los procedimientos de mantenimiento sin tiempo de inactividad.

Visión general de la arquitectura: Cómo funciona Sweep autoalojado

Para operar Sweep de manera confiable en una infraestructura privada, es indispensable entender cómo interactúan sus componentes internos con GitHub y los proveedores de modelos de lenguaje (LLM):

[GitHub / GitHub Enterprise]
       |
       |  1. Carga útil de Webhook (issues, comentarios de PR)
       v
[Proxy inverso / Ingress (Terminación TLS y filtrado de IP)]
       |
       |  2. Reenvío a puerto HTTP 8080 (Firma HMAC-SHA256 validada)
       v
[Contenedor Sweep (`sweepai/sweep`)]
  ├── Receptor rápido de Webhooks (FastAPI / Uvicorn)
  ├── Cola de tareas y despachador (Redis embebido + Workers en segundo plano)
  ├── Motor de análisis de código (Ripgrep + GitHub Linguist + Parsers AST)
  └── Montaje persistente de caché (`/mnt/caches`)
       |
       |  3. Solo prompts con contexto mínimo y sanitizado
       v
[API corporativa de LLM (OpenAI / Anthropic / Pasarela interna)]
       |
       |  4. Síntesis de planes de acción y diffs de código
       v
[Motor Git de Sweep]
       |
       |  5. Generación de token con clave RSA, push de rama y creación de PR
       v
[Repositorio de GitHub (Nueva rama y Pull Request generado)]

1. Recepción segura de Webhooks: Cuando un desarrollador crea un Issue con el prefijo Sweep:, GitHub envía una notificación JSON al puerto 8080 del host de Sweep. La aplicación valida de inmediato la firma criptográfica HMAC-SHA256 incluida en las cabeceras HTTP mediante el secreto compartido WEBHOOK_SECRET.
2. Desacoplamiento mediante cola asíncrona: Dado que GitHub exige una respuesta HTTP en menos de 10 segundos para no declarar el webhook como fallido, Sweep encola la tarea en una instancia interna de Redis y responde de inmediato con HTTP 200 OK, delegando el procesamiento intensivo a trabajadores en segundo plano.
3. Indexación y búsqueda local: El contenedor incorpora herramientas nativas de alto rendimiento: ripgrep para búsquedas textuales y de símbolos, github-linguist para detección de lenguajes y parsers de tree-sitter para árboles de sintaxis abstracta (AST). El repositorio se clona temporalmente y los índices se conservan en /mnt/caches.
4. Orquestación con LLM y aislamiento de datos: Sweep empaqueta únicamente los fragmentos de código pertinentes e instrucciones en el prompt enviado a los extremos configurados (OPENAI_API_KEY o ANTHROPIC_API_KEY). Bajo acuerdos corporativos de retención cero de datos (Zero Data Retention), el código fuente íntegro jamás sale ni es almacenado por terceros.
5. Autenticación con GitHub App y operaciones Git: Utilizando el ID de la aplicación y la clave privada RSA (GITHUB_APP_PEM), Sweep genera dinámicamente tokens de acceso de instalación (Installation Access Tokens) de corta duración, crea una rama de trabajo sweep/..., aplica los parches generados, realiza commits firmados y abre el Pull Request correspondiente.

Requisitos de infraestructura y dimensionamiento

Sweep ejecuta tareas de alta concurrencia: clonación de repositorios, búsquedas con expresiones regulares sobre árboles de archivos y generación de parches. Se recomiendan las siguientes especificaciones:

Especificaciones de hardware recomendadas

• Sistema operativo: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS o Linux empresarial (RHEL 9 / Rocky Linux).
• CPU: Mínimo 4 vCPUs (se recomiendan 8 vCPUs para agilizar búsquedas intensivas con Ripgrep).
• Memoria RAM: Mínimo 32 GB RAM (configuraciones de 16 GB pueden experimentar fallos por falta de memoria [OOM] al parsear repositorios grandes).
• Almacenamiento: Mínimo 200 GB SSD o NVMe (el rendimiento de E/S de disco es crítico para clonaciones y persistencia de caché).
• Equivalencia en nube: AWS t3.xlarge, GCP e2-standard-8 o máquinas virtuales locales equivalentes.

Requisitos de red y software

• Docker Engine (v24.0+) y Docker Compose (v2.20+).
• Salida a Internet (Egress): Conectividad HTTPS saliente (puerto TCP 443) hacia las APIs de LLM (api.openai.com o api.anthropic.com).
• Entrada (Ingress): Accesibilidad HTTPS entrante para recibir webhooks de GitHub, provista mediante un proxy inverso con TLS o tráfico puramente intranet si se utiliza GitHub Enterprise Server (GHES).

Paso 1: Registrar y configurar la GitHub App privada

El uso de una GitHub App privada en lugar de tokens de acceso personal (PAT) garantiza el principio de privilegio mínimo y proporciona trazabilidad completa en las auditorías de seguridad.

1. Registrar la GitHub App

1. Inicie sesión en GitHub con permisos administrativos en su organización.
2. Diríjase a Settings de la organización > Developer settings > GitHub Apps > New GitHub App.
3. Ingrese los datos descriptivos:
   • GitHub App name: Un identificador corporativo (por ejemplo, Corp-Internal-Sweep).
   • Homepage URL: URL del portal interno o de la documentación del equipo.
   • Callback URL: Puede dejarse en blanco.

2. Configurar el Webhook

• Webhook URL: Dirección pública o de red interna resuelta por el proxy inverso (por ejemplo, https://sweep.internal.yourcorp.com/ o http://<IP_DEL_HOST>:8080 durante pruebas).
• Webhook secret: Genere una cadena aleatoria criptográficamente segura ejecutando openssl rand -hex 32 en su terminal.

3. Configurar permisos del repositorio (Repository permissions)

Asigne estrictamente los siguientes permisos:

4. Suscribirse a eventos de Webhook (Subscribe to events)

Marque las siguientes casillas:

• Issues (apertura, edición, asignación, etiquetado)
• Issue comment (comentarios en issues)
• Pull request (apertura, sincronización, solicitud de revisión)
• Pull request review comment (comentarios línea por línea en el diff del PR)
• Check run (finalización de pruebas de integración continua)

5. Generar la clave privada e instalar la aplicación

1. Establezca Where can this GitHub App be installed? en Only on this account (Privada para esta organización).
2. Haga clic en Create GitHub App.
3. En la página de configuración, anote el número de App ID (por ejemplo, 123456).
4. Desplácese hasta la sección Private keys y seleccione Generate a private key. Descargue el archivo .pem resultante.
5. En el menú lateral izquierdo, seleccione Install App, elija la organización y seleccione los repositorios específicos donde operará Sweep.

Paso 2: Configurar las variables de entorno (.env)

Cree el directorio de trabajo en su servidor, clone el código de Sweep y prepare el archivo de configuración:

mkdir -p /opt/sweep && cd /opt/sweep
git clone https://github.com/sweepai/sweep.git
cd sweep

Cree el archivo .env e incorpore los parámetros recopilados en el Paso 1:

# Parámetros de autenticación de GitHub App
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=su_secreto_webhook_aqui

# Clave privada RSA generada por GitHub App (en una línea con \n o bloque multilínea)
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Clave de licencia de Sweep
# Las claves de prueba tienen una validez de 14 días; para entornos definitivos se requiere contacto con el equipo de Sweep
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# Claves de proveedores de modelos de lenguaje (LLM)
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Ajustes del contenedor
PORT=8080
WORKERS=3

Nota técnica sobre la clave RSA: Si define GITHUB_APP_PEM como una cadena de una sola línea, reemplace los saltos de línea con \n. En scripts de despliegue automatizados, puede cargar el archivo directamente mediante GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)".

Paso 3: Desplegar Sweep mediante Docker Compose

Sweep incluye un archivo Dockerfile de múltiples etapas y una configuración predeterminada en docker-compose.yml.

El bloque central del servicio está configurado de la siguiente manera:

services:
  hosted:
    build:
      context: .
      dockerfile: Dockerfile
      target: base
    image: sweepai/sweep:local
    container_name: webhook
    env_file:
      - .env
    volumes:
      - .:/app
      - /mnt/caches:/mnt/caches
    ports:
      - "${PORT:-8080}:8080"
    restart: unless-stopped
    command: >
      sh -c ". bin/startup.sh"

Inicialización del contenedor

Cree el directorio de persistencia para las cachés en el host y levante el servicio:

sudo mkdir -p /mnt/caches
sudo chown -R 1000:1000 /mnt/caches

# Construir la imagen e iniciar en segundo plano
docker compose up --build -d hosted

Verifique el estado del contenedor y examine los registros de inicio:

# Comprobar estado de ejecución
docker ps -f name=webhook

# Inspeccionar logs en tiempo real
docker compose logs -f hosted

Observará la inicialización de redis-server, seguida por los procesos Uvicorn escuchando peticiones en 0.0.0.0:8080.

Paso 4: Configurar el proxy inverso y la seguridad perimetral

En un entorno de producción, nunca se debe exponer el puerto 8080 sin cifrado TLS. Se recomienda configurar Nginx en la zona desmilitarizada (DMZ) con terminación TLS y restricción de direcciones IP.

Configuración recomendada de Nginx

upstream sweep_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name sweep.internal.yourcorp.com;

    ssl_certificate /etc/ssl/certs/sweep.internal.yourcorp.com.crt;
    ssl_certificate_key /etc/ssl/private/sweep.internal.yourcorp.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Permitir únicamente rangos IP oficiales de webhooks de GitHub
    # Los rangos CIDR actualizados se obtienen en https://api.github.com/meta ("hooks")
    allow 192.30.252.0/22;
    allow 185.199.108.0/22;
    allow 140.82.112.0/20;
    allow 143.55.64.0/20;
    # Subred interna para pruebas de equipo
    allow 10.0.0.0/8;
    deny all;

    client_max_body_size 50M;

    location / {
        proxy_pass http://sweep_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

Nota para redes aisladas: Si su infraestructura utiliza GitHub Enterprise Server (GHES) alojado internamente, no requiere exponer ningún puerto a la red pública; la comunicación ocurre exclusivamente a través del enrutamiento interno.

Paso 5: Verificación del flujo de trabajo de extremo a extremo

Una vez que el servicio y la red estén en funcionamiento, valide el pipeline completo:

1. Creación del Issue de prueba: En uno de los repositorios autorizados, cree un Issue cuyo título comience con el prefijo Sweep:, por ejemplo:

   Title: Sweep: Agregar validación de tokens y casos de prueba en utils/auth.py
   Body: Por favor añada validaciones para tokens expirados y firmas corruptas en utils/auth.py junto con pruebas unitarias en pytest.
   

2. Inspección de logs del Webhook: En la consola del servidor, observe la actividad:

   docker compose logs -f hosted
   

   Sweep validará la firma del webhook, generará el token de instalación y comenzará el análisis del código.
3. Revisión del plan generado: Sweep responderá en el Issue con un comentario detallando los archivos afectados y la estrategia de modificación prevista.
4. Comprobación del Pull Request: Entre dos y cinco minutos después, Sweep subirá una rama nueva (sweep/token-validation...) y abrirá automáticamente un Pull Request con un resumen de los cambios.
5. Prueba de revisión interactiva: Deje un comentario de revisión sobre una línea de código específica en el PR (por ejemplo: "Sweep: utilice una constante global para el tiempo de expiración"). Sweep procesará la solicitud y añadirá un commit de ajuste en la misma rama.

Mantenimiento y operaciones del ciclo de vida

Dado que Sweep gestiona tareas prolongadas en segundo plano —como clonaciones de repositorios pesados y razonamiento de modelos—, ejecutar docker compose down abruptamente puede interrumpir operaciones en vuelo.

Despliegue sin tiempo de inactividad (Graceful Redeployment)

El repositorio incluye un script especializado para reiniciar el servicio de forma limpia:

# Obtener actualizaciones del repositorio o cambios locales
git pull origin main

# Ejecutar reinicio ordenado
bash bin/redeploy.sh

Este procedimiento garantiza que los trabajadores actuales finalicen sus tareas antes de sustituir los contenedores en ejecución.

Mantenimiento del disco y purga de caché

Con el tiempo, el volumen /mnt/caches acumulará árboles de trabajo antiguos. Establezca una tarea cron mensual en el sistema operativo:

# Eliminar directorios de caché con más de 30 días de inactividad
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# Eliminar capas de imágenes Docker huérfanas
docker image prune -f

Matriz comparativa: Autoalojado vs. Nube SaaS oficial

Recomendaciones para equipos DevOps

1. Selección del modelo de IA: El éxito de Sweep al modificar múltiples archivos depende directamente de la capacidad de razonamiento del LLM. Configure modelos líderes como Claude 3.5 Sonnet o GPT-4o. Modelos locales pequeños (7B/8B) tienden a fallar en la sintaxis de diffs unificados y generan errores frecuentes.
2. Horizonte de mantenimiento: Sweep introdujo este agente de automatización basado en GitHub de forma abierta, aunque posteriormente amplió su foco comercial hacia extensiones para entornos de desarrollo (IDE). Los equipos que adopten este backend deben considerarlo como una plataforma PaaS interna y prever recursos de ingeniería para su mantenimiento continuo.
3. Rotación periódica de credenciales: Establezca un ciclo de rotación de 90 días tanto para la clave privada RSA (.pem) de GitHub App como para el WEBHOOK_SECRET, cumpliendo con los estándares ISO 27001 y SOC 2.

Referencias

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• Self-Hosting Sweep via Docker
• Sweep Docker Compose Configuration
• Sweep Backend Dockerfile
• Registering a GitHub App - GitHub Docs