Sweep per Docker und privaten GitHub-App-Anmeldedaten selbst hosten: Der Engineering-Leitfaden für sichere On-Premises-Code-Automatisierung

Entwicklungsteams in stark regulierten Branchen – wie Finanzdienstleistungen, Gesundheitswesen, Verteidigung und kritische Infrastrukturen – stoßen bei der Einführung autonomer KI-Coding-Agenten oft auf eine strikte Compliance-Hürde: Unternehmensrichtlinien verbieten es kategorisch, proprietären Quellcode an mandantenfähige Cloud-Plattformen von Drittanbietern zu übertragen. Der Open-Source-Agent Sweep (Repository sweepai/sweep) bietet mit seiner containerbasierten Architektur eine bewährte Lösung für dieses Dilemma. Durch die Bereitstellung des Sweep-Backends in einer privaten Virtual Private Cloud (VPC) oder auf On-Premises-Servern mittels Docker und die Anbindung einer dedizierten, privaten GitHub App können DevOps-Teams den gesamten Lebenszyklus vom GitHub-Issue bis zum Pull Request (PR) automatisieren – während Code-Indizierung, Git-Befehle und Repositorium-Geheimnisse vollständig innerhalb der Unternehmens-Firewall verbleiben.

Dieser Leitfaden beschreibt das architektonische Design, die Hardware-Dimensionierung, die Least-Privilege-Konfiguration der GitHub App, die Container-Orchestrierung sowie Best Practices für den unterbrechungsfreien Betrieb.

Architekturüberblick: Funktionsweise des selbst gehosteten Sweep

Um Sweep in einer On-Premises-Infrastruktur zuverlässig zu betreiben, ist ein Verständnis der Interaktion zwischen den internen Container-Diensten, GitHub und den Large-Language-Model-(LLM)-Schnittstellen unerlässlich:

[GitHub / GitHub Enterprise]
       |
       |  1. Webhook-Payload (Issues, PR-Kommentare)
       v
[Reverse-Proxy / Ingress (TLS-Terminierung & IP-Filterung)]
       |
       |  2. Weiterleitung an HTTP-Port 8080 (HMAC-SHA256 validiert)
       v
[Sweep-Container (`sweepai/sweep`)]
  ├── Schneller Webhook-Empfänger (FastAPI / Uvicorn)
  ├── Asynchrone Aufgabenwarteschlange (Integriertes Redis + Background-Worker)
  ├── Code-Intelligence-Engine (Ripgrep + GitHub Linguist + AST-Parser)
  └── Persistentes Cache-Volume (`/mnt/caches`)
       |
       |  3. Ausschließlich bereinigte Prompt-Ausschnitte
       v
[Unternehmens-LLM-API (OpenAI / Anthropic / Privates Gateway)]
       |
       |  4. Rückgabe von Aktionsplan und Code-Diffs
       v
[Sweep Git-Engine]
       |
       |  5. Token-Generierung via RSA-Schlüssel, Branch-Push & PR-Erstellung
       v
[Ziel-GitHub-Repository (Neuer Branch und automatisierter Pull Request)]

1. Sicherer Webhook-Empfang: Wenn Entwickler ein Issue mit dem Präfix Sweep: anlegen, sendet GitHub eine JSON-Benachrichtigung an Port 8080 der Sweep-Instanz. Der Container validiert unverzüglich die HMAC-SHA256-Signatur im HTTP-Header mithilfe des konfigurierten WEBHOOK_SECRET.
2. Entkopplung durch asynchrone Warteschlange: GitHub verlangt eine HTTP-Bestätigung innerhalb von 10 Sekunden. Sweep reiht die Aufgabe unmittelbar in die interne Redis-Warteschlange ein, antwortet mit HTTP 200 OK und überlässt die rechenintensive Code-Analyse im Hintergrund laufenden Workern.
3. Lokale Code-Indizierung: Im Container sind performante Werkzeuge integriert: ripgrep für blitzschnelle Symbol- und Textrecherchen, github-linguist zur Spracherkennung und Tree-sitter für die Syntaxbaumanalyse (AST). Repositories werden temporär geklont, und Arbeitsindizes werden im Host-Pfad /mnt/caches persistiert.
4. LLM-Orchestrierung und Datenschutz: Sweep isoliert ausschließlich die für das Issue relevanten Codeabschnitte und Anweisungen im Prompt und sendet sie an die konfigurierten Endpunkte (OPENAI_API_KEY oder ANTHROPIC_API_KEY). Bei Verwendung von Unternehmenskonten mit Zero-Data-Retention-Vereinbarungen verbleibt der vollständige Quellcode sicher im eigenen Netzwerk.
5. Authentifizierung via GitHub App und Git-Automatisierung: Sweep generiert dynamisch kurzlebige Installation Access Tokens mithilfe der App-ID und des privaten RSA-Schlüssels (GITHUB_APP_PEM). Es erstellt den Arbeitszweig sweep/..., wendet den synthetisierten Patch an, signiert Commits unter der Bot-Identität und eröffnet den Pull Request.

Hardware-Dimensionierung und Systemvoraussetzungen

Sweep führt simultan ressourcenintensive Vorgänge aus – darunter Git-Klonvorgänge, parallele Regex-Suchen über Verzeichnisbäume und AST-Analysen. Es wird folgende Mindestausstattung empfohlen:

Empfohlene Hardware

• Betriebssystem: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS oder Enterprise Linux (RHEL 9 / Rocky Linux).
• Prozessor: Mindestens 4 vCPUs (8 vCPUs empfohlen für schnellere Suchvorgänge bei großen Repositories).
• Arbeitsspeicher: Mindestens 32 GB RAM (bei 16 GB kann es bei umfangreichen Codebases während der AST-Erstellung zu Out-of-Memory-Abbrüchen [OOM] kommen).
• Festplattenspeicher: Mindestens 200 GB SSD oder NVMe (hohe I/O-Geschwindigkeit ist entscheidend für Git-Vorgänge und Cache-Persistenz).
• Referenz-Instanzen: AWS t3.xlarge, GCP e2-standard-8 oder entsprechende lokale Virtualisierungs-Hosts.

Software- und Netzwerkbedingungen

• Docker Engine (v24.0+) und Docker Compose (v2.20+).
• Ausgehende Verbindung (Egress): Port TCP 443 freigeschaltet für LLM-APIs (api.openai.com oder api.anthropic.com).
• Eingehende Verbindung (Ingress): HTTPS-Erreichbarkeit für GitHub-Webhooks über einen Reverse-Proxy mit TLS oder rein interne Intranetanbindung bei Nutzung eines On-Premises GitHub Enterprise Server (GHES).

Schritt 1: Private GitHub App registrieren und konfigurieren

Die Nutzung einer dedizierten GitHub App anstelle persönlicher Zugriffstoken (PAT) erzwingt das Least-Privilege-Prinzip und gewährleistet revisionssichere Audit-Protokolle.

1. GitHub App registrieren

1. Melden Sie sich bei GitHub mit Administratorrechten für Ihre Organisation an.
2. Navigieren Sie zu Settings der Organisation > Developer settings > GitHub Apps > New GitHub App.
3. Pflegen Sie die Basisdaten:
   • GitHub App name: Eindeutiger Name (z. B. Corp-Internal-Sweep).
   • Homepage URL: URL des internen Portals oder der Systemdokumentation.
   • Callback URL: Kann leer bleiben.

2. Webhook-Konfiguration

• Webhook URL: Die durch den Reverse-Proxy geschützte HTTPS-Adresse (z. B. https://sweep.internal.yourcorp.com/ oder testweise http://<HOST_IP>:8080).
• Webhook secret: Erzeugen Sie eine kryptografisch sichere Zufallszeichenfolge mittels openssl rand -hex 32 im Terminal und sichern Sie diese.

3. Repository-Berechtigungen festlegen (Repository permissions)

Vergeben Sie exakt folgende Berechtigungen:

4. Webhook-Ereignisse abonnieren (Subscribe to events)

Aktivieren Sie folgende Ereignisse:

• Issues (Erstellung, Bearbeitung, Labels, Zuweisung)
• Issue comment (Kommentare in Issues)
• Pull request (Erstellung, Aktualisierung, Review-Anforderung)
• Pull request review comment (Zeilenbezogene Review-Kommentare im PR)
• Check run (Abschluss von CI-Pipeline-Läufen)

5. Privaten Schlüssel erzeugen und App installieren

1. Setzen Sie Where can this GitHub App be installed? auf Only on this account (Privat für diese Organisation).
2. Klicken Sie auf Create GitHub App.
3. Notieren Sie auf der Übersichtsseite die numerische App ID (z. B. 123456).
4. Navigieren Sie zum Bereich Private keys, klicken Sie auf Generate a private key und laden Sie die .pem-Datei herunter.
5. Klicken Sie im linken Menü auf Install App, wählen Sie Ihre Organisation und weisen Sie die Ziel-Repositories zu.

Schritt 2: Umgebungsvariablen (.env) konfigurieren

Erstellen Sie das Bereitstellungsverzeichnis auf dem Host-Server, klonen Sie das Sweep-Repository und legen Sie die Konfigurationsdatei an:

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

Erstellen Sie die Datei .env mit den zuvor generierten Parametern:

# GitHub-App-Authentifizierung
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=ihr_generiertes_webhook_secret

# Privater RSA-Schlüssel der GitHub App (als einzeiliger String mit \n oder mehrzeiliger Block)
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Sweep-Lizenzschlüssel
# Evaluierungsschlüssel sind für 14 Tage gültig; Enterprise-Lizenzen erfordern Kontakt mit dem Sweep-Team
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# Schnittstellen-Schlüssel für KI-Modelle
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Container-Konfiguration
PORT=8080
WORKERS=3

Wichtiger Hinweis zum RSA-Schlüssel: Wenn GITHUB_APP_PEM als einzeilige Umgebungsvariable übergeben wird, müssen alle Zeilenumbrüche durch \n ersetzt werden. In automatisierten Skripten kann die Datei direkt über GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)" eingelesen werden.

Schritt 3: Container-Bereitstellung mit Docker Compose

Das offizielle Sweep-Repository stellt ein mehrstufiges Dockerfile mit Python 3.10, Redis, ripgrep und Syntax-Tools sowie eine Datei docker-compose.yml bereit.

Die grundlegende Dienstdefinition lautet:

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"

Container starten

Legen Sie das Cache-Verzeichnis auf dem Host an und starten Sie den Dienst im Hintergrund:

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

# Image bauen und im Hintergrund starten
docker compose up --build -d hosted

Prüfen Sie den Container-Status und die Protokolle:

# Status kontrollieren
docker ps -f name=webhook

# Live-Logs verfolgen
docker compose logs -f hosted

Die Logs bestätigen den Start des internen redis-server und die Bereitschaft der Uvicorn-Worker auf 0.0.0.0:8080.

Schritt 4: Reverse-Proxy und Perimetersicherheit

In Unternehmensnetzwerken darf Port 8080 keinesfalls unverschlüsselt betrieben werden. Konfigurieren Sie Nginx in der DMZ mit TLS-Terminierung und IP-Filterung.

Nginx-Konfigurationsbeispiel

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;

    # Ausschließlich offizielle GitHub-Webhook-IP-Bereiche zulassen
    # Aktuelle CIDR-Blöcke abrufbar unter 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;
    # Internes Testnetz
    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;
    }
}

Hinweis für isolierte Netze: Beim Einsatz von GitHub Enterprise Server (GHES) im Firmennetz sind keine externen Portweiterleitungen erforderlich; der Datenverkehr verbleibt vollständig im Intranet.

Schritt 5: Verifikation des End-to-End-Workflows

Testen Sie die vollständige Pipeline nach Abschluss von Bereitstellung und Netzwerkkonfiguration:

1. Trigger-Issue erstellen: Eröffnen Sie in einem angebundenen Repository ein Issue mit dem Präfix Sweep:, z. B.:

   Title: Sweep: Token-Validierung und Komponententests in utils/auth.py hinzufügen
   Body: Bitte ergänzen Sie in tests/test_auth.py pytest-Tests für abgelaufene Tokens und ungültige Signaturen.
   

2. Webhook-Verarbeitung überprüfen: Verfolgen Sie die Protokolle auf dem Server:

   docker compose logs -f hosted
   

   Sweep validiert die Signatur, generiert das Installations-Token und startet die lokale Code-Analyse.
3. Ausführungsplan einsehen: Sweep antwortet im Issue mit einem detaillierten Kommentar über betroffene Dateien und Lösungsschritte.
4. Pull Request prüfen: Nach wenigen Minuten pusht Sweep einen Branch (sweep/token-validation...) und eröffnet einen Pull Request mit einer strukturierten Beschreibung.
5. Interaktive Code-Reviews testen: Hinterlassen Sie im PR-Diff einen Zeilenkommentar (z. B. "Sweep: Bitte Standard-Bibliothek für Zeitstempel verwenden"). Sweep verarbeitet den Review-Webhook und pusht automatisch einen Folge-Commit.

Wartung und Betriebsführung

Da Sweep langlebige Hintergrundprozesse für Indizierung und Git-Operationen ausführt, führt ein abruptes docker compose down zum Verlust aktiver Arbeitszustände.

Unterbrechungsfreie Aktualisierung (Zero-Downtime Redeployment)

Das Sweep-Repository enthält ein spezielles Skript für einen sauberen Neustart:

# Neuesten Code abrufen
git pull origin main

# Geordneten Neustart ausführen
bash bin/redeploy.sh

Das Skript stellt sicher, dass laufende Worker-Prozesse ihre aktuellen Aufgaben beenden, bevor neue Container aktiviert werden.

Speicherbereinigung und Cache-Hygiene

Mit zunehmender Anzahl von Repositories wächst /mnt/caches. Richten Sie einen monatlichen Cronjob zur Bereinigung ein:

# Caches löschen, die älter als 30 Tage sind
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# Ungenutzte Docker-Image-Fragmente entfernen
docker image prune -f

Vergleich: Self-Hosting vs. Offizielle SaaS-Cloud

Empfehlungen für DevOps-Teams

1. Modellauswahl: Die Qualität von Sweeps Multi-File-Edits korreliert direkt mit den Reasoning-Fähigkeiten des KI-Modells. Es wird dringend empfohlen, Claude 3.5 Sonnet oder GPT-4o einzusetzen. Kleinere lokale Modelle (7B/8B) erzeugen häufig fehlerhafte Diff-Formate und Syntaxfehler.
2. Langfristige Wartung: Das Sweep-Projekt hat dieses GitHub-Webhook-Backend quelloffen zur Verfügung gestellt und seinen kommerziellen Schwerpunkt später auf IDE-Assistenten erweitert. Unternehmen sollten diese Bereitstellung als interne PaaS betrachten und eigene Ressourcen für Softwarepflege und Anpassungen einplanen.
3. Regelmäßige Schlüsselrotation: Etablieren Sie einen 90-Tage-Zyklus zur Erneuerung des privaten RSA-Schlüssels (.pem) und des WEBHOOK_SECRET, um die Standards ISO 27001 und SOC 2 lückenlos zu erfüllen.

Referenzen

• 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