Auto-héberger Sweep avec Docker et des identifiants GitHub App privés : Le guide d'ingénierie pour une automatisation sécurisée du code sur site

Les équipes d'ingénierie opérant dans des secteurs hautement réglementés — tels que la finance, la santé, la défense et les infrastructures critiques — se heurtent fréquemment à une barrière stricte de conformité lorsqu'elles évaluent des agents autonomes de développement : les politiques de sécurité interdisent formellement le transfert de code source propriétaire vers des environnements cloud mutualisés tiers. L'agent open source Sweep (dépôt sweepai/sweep) résout cette problématique grâce à son architecture conteneurisée. En déployant le backend de Sweep sur une infrastructure privée (VPC ou serveurs sur site) à l'aide de Docker et en le connectant à une GitHub App privée dédiée, les ingénieurs DevOps peuvent automatiser l'intégralité du cycle de vie des tickets (Issue) jusqu'à la création de Pull Requests (PR), tout en conservant l'indexation du code, les opérations Git et les secrets de configuration au sein du périmètre sécurisé de l'entreprise.

Ce guide fournit la feuille de route technique complète pour le dimensionnement, la configuration des permissions à moindre privilège sur GitHub App, l'orchestration Docker, la sécurisation des flux réseau et la maintenance sans interruption de service.

Vue d'ensemble de l'architecture : Fonctionnement de Sweep auto-hébergé

Pour exploiter Sweep de manière pérenne sur une infrastructure locale, il est indispensable de comprendre comment ses services conteneurisés communiquent avec GitHub et les fournisseurs de modèles de langage (LLM) :

[GitHub / GitHub Enterprise]
       |
       |  1. Charge utile Webhook (création d'Issues, commentaires de PR)
       v
[Proxy inverse / Ingress (Terminaison TLS & Filtrage IP GitHub)]
       |
       |  2. Redirection port HTTP 8080 (Signature HMAC-SHA256 validée)
       v
[Conteneur Sweep (`sweepai/sweep`)]
  ├── Récepteur rapide de Webhooks (FastAPI / Uvicorn)
  ├── File d'attente asynchrone (Redis intégré + Workers d'arrière-plan)
  ├── Moteur d'analyse du code (Ripgrep + GitHub Linguist + Parseurs AST)
  └── Montage de cache persistant (`/mnt/caches`)
       |
       |  3. Uniquement des invites (prompts) épurées et contextualisées
       v
[API LLM d'entreprise (OpenAI / Anthropic / Passerelle privée)]
       |
       |  4. Restitution du plan d'action et des diffs de code
       v
[Moteur Git de Sweep]
       |
       |  5. Token émis par clé RSA, push de branche & ouverture de PR
       v
[Dépôt GitHub cible (Nouvelle branche et Pull Request automatique)]

1. Réception et validation sécurisée du Webhook : Lorsqu'un développeur ouvre une Issue précédée du préfixe Sweep:, GitHub envoie une notification JSON vers le port 8080 de l'instance Sweep. L'application valide immédiatement la signature cryptographique HMAC-SHA256 figurant dans les en-têtes HTTP à l'aide du secret partagé WEBHOOK_SECRET.
2. Découplage par file d'attente asynchrone : GitHub imposant un délai strict de 10 secondes pour accuser réception des webhooks, Sweep enregistre immédiatement la tâche dans une file Redis interne et renvoie le code HTTP 200 OK. L'analyse lourde du code est déléguée aux processus workers en arrière-plan.
3. Indexation et analyse locale du code : Le conteneur intègre des utilitaires natifs haute performance : ripgrep pour la recherche de symboles et de texte, github-linguist pour la détection des langages et des parseurs tree-sitter pour l'analyse des arbres de syntaxe abstraite (AST). Le dépôt est cloné dans un espace de travail éphémère et les index sont conservés dans /mnt/caches.
4. Orchestration LLM et protection des données : Sweep n'envoie vers les modèles (OPENAI_API_KEY ou ANTHROPIC_API_KEY) que les extraits de code ciblés et les consignes du prompt. Sous contrat d'entreprise avec clause de rétention nulle des données (Zero Data Retention), le code source complet n'est jamais sauvegardé ni utilisé pour l'entraînement par des tiers.
5. Automatisation Git via GitHub App : À l'aide de l'App ID et de la clé privée RSA (GITHUB_APP_PEM), Sweep génère à la volée des jetons d'accès d'installation temporaires. Il crée une branche de travail sweep/..., applique les modifications générées, signe les commits sous son identité et ouvre la Pull Request.

Dimensionnement de l'infrastructure et prérequis

Sweep exécute simultanément des opérations exigeantes : clonages Git, recherches massives par expressions régulières et génération de syntaxe. L'infrastructure minimale suivante est recommandée :

Spécifications matérielles recommandées

• Système d'exploitation : Ubuntu 22.04 LTS, Ubuntu 24.04 LTS ou distribution Linux d'entreprise (RHEL 9 / Rocky Linux).
• Processeur : Minimum 4 vCPU (8 vCPU recommandés pour accélérer les recherches Ripgrep sur de gros dépôts).
• Mémoire vive : Minimum 32 Go de RAM (16 Go peuvent provoquer des arrêts par manque de mémoire [OOM] lors du parsing d'arbres AST complexes).
• Stockage : Minimum 200 Go sur SSD ou NVMe (les débits d'E/S rapides sont cruciaux pour les opérations Git et la persistance du cache).
• Équivalents cloud : AWS t3.xlarge, GCP e2-standard-8 ou machines virtuelles locales équivalentes.

Prérequis logiciels et réseau

• Docker Engine (v24.0+) et Docker Compose (v2.20+).
• Connectivité sortante (Egress) : Port TCP 443 ouvert vers les API de LLM (api.openai.com ou api.anthropic.com).
• Connectivité entrante (Ingress) : Accès HTTPS pour recevoir les webhooks de GitHub, assuré par un proxy inverse avec terminaison TLS, ou réseau intranet exclusif si vous utilisez GitHub Enterprise Server (GHES).

Étape 1 : Créer et configurer la GitHub App privée

L'utilisation d'une GitHub App dédiée à la place de jetons d'accès personnels (PAT) garantit le principe du moindre privilège et assure une traçabilité d'audit rigoureuse.

1. Enregistrer la GitHub App

1. Connectez-vous à GitHub avec des droits d'administrateur sur votre organisation.
2. Accédez à Settings de l'organisation > Developer settings > GitHub Apps > New GitHub App.
3. Renseignez les informations de base :
   • GitHub App name : Nom d'identification interne (ex. : Corp-Internal-Sweep).
   • Homepage URL : URL du portail interne ou de la documentation technique.
   • Callback URL : Peut être laissé vide.

2. Configurer le Webhook

• Webhook URL : Adresse sécurisée par votre proxy inverse (ex. : https://sweep.internal.yourcorp.com/ ou http://<IP_HOTE>:8080 lors des tests).
• Webhook secret : Générez une chaîne aléatoire sécurisée en exécutant openssl rand -hex 32 dans votre terminal et conservez-la précieusement.

3. Configurer les permissions du dépôt (Repository permissions)

Attribuez strictement les permissions suivantes :

4. Souscrire aux événements de Webhook (Subscribe to events)

Sélectionnez les événements suivants :

• Issues (ouverture, modification, étiquetage, assignation)
• Issue comment (publication de commentaires sur les issues)
• Pull request (ouverture, synchronisation, demande de revue)
• Pull request review comment (commentaires de revue ciblés sur les lignes de code)
• Check run (achèvement des suites de tests CI)

5. Générer la clé privée et installer l'application

1. Définissez Where can this GitHub App be installed? sur Only on this account (Installation privée au sein de l'organisation).
2. Cliquez sur Create GitHub App.
3. Sur la page récapitulative, notez le numéro de l'App ID (ex. : 123456).
4. Faites défiler jusqu'à la section Private keys et cliquez sur Generate a private key. Téléchargez le fichier .pem obtenu.
5. Dans le menu de gauche, cliquez sur Install App, sélectionnez votre organisation et indiquez les dépôts autorisés à utiliser Sweep.

Étape 2 : Configurer le fichier de variables d'environnement (.env)

Créez le répertoire de travail sur votre serveur, clonez le projet Sweep et préparez la configuration :

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

Créez le fichier .env avec les valeurs obtenues à l'Étape 1 :

# Authentification GitHub App
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=votre_secret_webhook_ici

# Clé privée RSA de la GitHub App (format sur une ligne avec \n ou bloc multiligne)
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Clé de licence Sweep
# Les clés d'essai sont valables 14 jours ; les licences de production nécessitent de contacter l'équipe Sweep
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# Clés d'API des modèles d'intelligence artificielle
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Configuration du conteneur
PORT=8080
WORKERS=3

Remarque sur le format de clé RSA : Si vous définissez GITHUB_APP_PEM sur une seule ligne, veillez à remplacer tous les retours à la ligne par \n. Dans un pipeline d'automatisation, il est également possible de charger directement le fichier via GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)".

Étape 3 : Démarrer Sweep avec Docker Compose

Le dépôt de Sweep comprend un Dockerfile multi-étapes basé sur Python 3.10 avec Redis, ripgrep et les analyseurs de code, ainsi qu'un fichier docker-compose.yml.

La configuration centrale se présente comme suit :

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"

Lancement des conteneurs

Créez le dossier de cache sur l'hôte et démarrez le conteneur en arrière-plan :

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

# Compiler l'image et démarrer le service
docker compose up --build -d hosted

Vérifiez l'état d'exécution et les journaux de démarrage :

# Vérifier l'état du conteneur
docker ps -f name=webhook

# Consulter les logs en temps réel
docker compose logs -f hosted

Vous constaterez le lancement du serveur interne redis-server, suivi par l'initialisation des workers Uvicorn sur 0.0.0.0:8080.

Étape 4 : Configurer le proxy inverse et la sécurité du réseau

En production, le port HTTP 8080 ne doit jamais être exposé directement sans chiffrement TLS. Configurez Nginx en zone démilitarisée (DMZ) avec terminaison TLS et filtrage des adresses IP autorisées.

Exemple de configuration 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;

    # Autoriser uniquement les plages d'adresses IP officielles des webhooks GitHub
    # La liste CIDR actualisée est disponible sur 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;
    # Sous-réseau interne de tests
    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;
    }
}

Remarque pour les réseaux fermés : Si votre organisation utilise GitHub Enterprise Server (GHES) en interne, aucune ouverture de port public n'est requise ; la communication s'opère de manière hermétique sur le réseau local.

Étape 5 : Validation du flux de travail de bout en bout

Une fois les services déployés et le réseau configuré, testez le pipeline complet :

1. Création d'une Issue de test : Dans l'un des dépôts configurés, ouvrez une Issue dont le titre commence par Sweep:, par exemple :

   Title: Sweep: Ajouter la validation des jetons JWT et des tests unitaires dans utils/auth.py
   Body: Veuillez implémenter des contrôles pour les jetons expirés et les signatures altérées dans utils/auth.py avec des tests pytest associés.
   

2. Surveillance des logs : Observez la réception du webhook sur votre serveur :

   docker compose logs -f hosted
   

   Sweep validera l'événement, demandera son jeton d'installation et initialisera l'analyse du code.
3. Consultation du plan d'action : Sweep postera un premier commentaire dans l'Issue détaillant les fichiers concernés et les étapes techniques planifiées.
4. Examen de la Pull Request : En quelques minutes, Sweep créera une nouvelle branche (sweep/jwt-validation...) et ouvrira une PR accompagnée d'un récapitulatif complet des modifications.
5. Test de revue interactive : Laissez un commentaire ciblé sur une ligne de code du PR (ex. : "Sweep: utilisez la fonction time native plutôt qu'un module externe"). Sweep traitera la demande et publiera automatiquement un commit rectificatif.

Maintenance et exploitation sans interruption de service

Sweep exécutant des tâches d'arrière-plan de longue durée, l'arrêt brutal des conteneurs via docker compose down risque d'interrompre des processus en cours d'exécution.

Déploiement sans interruption (Zero-Downtime Redeployment)

Le dépôt inclut un script dédié au redémarrage ordonné :

# Mettre à jour le code du dépôt
git pull origin main

# Exécuter le redémarrage sécurisé
bash bin/redeploy.sh

Ce script attend la fin des traitements en cours avant de recréer et basculer sur les nouveaux conteneurs.

Hygiène de stockage et purge du cache

Au fil du temps, /mnt/caches accumulera des arbres de travail obsolètes. Configurez une tâche cron mensuelle sur le serveur hôte :

# Supprimer les caches inactifs depuis plus de 30 jours
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# Nettoyer les couches d'images Docker orphelines
docker image prune -f

Matrice comparative : Auto-hébergé vs Cloud SaaS officiel

Recommandations pour les équipes d'ingénierie

1. Sélection du modèle de raisonnement : La qualité des modifications multi-fichiers dépend fortement de la puissance d'analyse du modèle. Privilégiez Claude 3.5 Sonnet ou OpenAI GPT-4o. L'utilisation de petits modèles locaux (7B/8B) génère fréquemment des erreurs de formatage de diffs et des ruptures de syntaxe.
2. Périmètre de maintenance interne : Sweep a publié ce moteur d'automatisation GitHub en open source avant de focaliser son offre commerciale sur des extensions pour environnements de développement (IDE). Les entreprises adoptant ce backend doivent l'aborder comme une plateforme PaaS interne et prévoir les ressources pour sa maintenance.
3. Rotation des clés : Instaurez un cycle de rotation tous les 90 jours pour la clé privée RSA (.pem) de votre GitHub App et le WEBHOOK_SECRET afin de vous conformer aux exigences ISO 27001 et SOC 2.

Références

• 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