Auto-hospedagem do Sweep com Docker e credenciais privadas do GitHub App: Guia de engenharia para automação local de código

Equipes de engenharia que operam em setores altamente regulamentados — como serviços financeiros, saúde, defesa e infraestrutura crítica — frequentemente enfrentam uma barreira rígida ao adotar agentes autônomos de codificação: políticas corporativas proíbem categoricamente o envio de código-fonte proprietário para nuvens públicas multilocatárias. O agente de código aberto Sweep (repositório sweepai/sweep) soluciona esse atrito por meio de sua arquitetura conteinerizada. Ao implantar a pilha do Sweep em uma nuvem privada virtual (VPC) ou em servidores locais com Docker, associada a um GitHub App privado e a webhooks internos, engenheiros de DevOps podem automatizar o ciclo completo de Issue a Pull Request (PR) com a garantia de que a indexação, os comandos Git e os segredos do repositório permaneçam integralmente dentro do perímetro corporativo.

Este guia fornece o blueprint técnico completo para dimensionamento, provisionamento de credenciais com privilégio mínimo, configuração de rede e manutenção contínua de uma instância privada do Sweep.

Visão geral da arquitetura: Como o Sweep auto-hospedado opera

Para manter o Sweep estável em um ambiente on-premises, é crucial compreender o fluxo de comunicação entre seus microsserviços internos, o GitHub e as APIs de modelos de linguagem (LLM):

[GitHub / GitHub Enterprise]
       |
       |  1. Payload de Webhook (issues, comentários de PR)
       v
[Proxy Reverso / Ingress (Terminação TLS e lista de permissões de IP)]
       |
       |  2. Encaminhamento HTTP na porta 8080 (Assinatura HMAC validada)
       v
[Contêiner do Sweep (`sweepai/sweep`)]
  ├── Receptor rápido de Webhooks (FastAPI / Uvicorn)
  ├── Fila assíncrona e despachante (Redis embutido + Workers de segundo plano)
  ├── Motor de inteligência de código (Ripgrep + GitHub Linguist + Parsers AST)
  └── Volume persistente de cache (`/mnt/caches`)
       |
       |  3. Apenas prompts com contexto filtrado
       v
[API corporativa de LLM (OpenAI / Anthropic / Gateway privado)]
       |
       |  4. Retorno do plano de ação e diffs de código
       v
[Motor Git do Sweep]
       |
       |  5. Token emitido via chave RSA, push de branch e abertura de PR
       v
[Repositório no GitHub (Nova branch e Pull Request automatizado)]

1. Recepção e validação do Webhook: Quando um desenvolvedor abre uma Issue com o prefixo Sweep:, o GitHub envia uma notificação JSON para a porta 8080 do Sweep. O contêiner valida imediatamente a assinatura criptográfica HMAC-SHA256 no cabeçalho da requisição utilizando a chave WEBHOOK_SECRET.
2. Desacoplamento por fila assíncrona: O GitHub impõe um tempo limite estrito de 10 segundos para confirmação de webhooks. O Sweep enfileira o evento em uma instância local do Redis e responde instantaneamente com HTTP 200 OK, repassando o trabalho de análise pesada para workers em segundo plano.
3. Indexação local do código: O contêiner executa ferramentas nativas otimizadas: ripgrep para buscas textuais e de símbolos, github-linguist para identificação de linguagens e bibliotecas tree-sitter para análise de árvores de sintaxe abstrata (AST). Os clones e índices intermediários ficam armazenados no volume /mnt/caches.
4. Orquestração de LLMs e proteção de dados: O Sweep reúne apenas os trechos de código estritamente necessários no prompt enviado aos endpoints (OPENAI_API_KEY ou ANTHROPIC_API_KEY). Com contratos corporativos de retenção zero de dados (Zero Data Retention), o código proprietário nunca é persistido ou utilizado para treinamento por terceiros.
5. Autenticação via GitHub App e automação Git: Utilizando o App ID e a chave privada RSA (GITHUB_APP_PEM), o Sweep solicita dinamicamente tokens de acesso de instalação de curta duração, cria uma nova branch de trabalho sweep/..., aplica os patches sintetizados, comita as alterações e cria o Pull Request no repositório.

Dimensionamento de hardware e pré-requisitos

O Sweep realiza operações simultâneas intensivas de Git, varredura de árvores de diretórios com regex e consultas a modelos de IA. Recomenda-se a seguinte infraestrutura de suporte:

Especificações recomendadas de servidor

• Sistema operacional: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS ou distribuições corporativas (RHEL 9 / Rocky Linux).
• Processador: Mínimo de 4 vCPUs (8 vCPUs recomendadas para repositórios com muitos arquivos).
• Memória RAM: Mínimo de 32 GB RAM (instâncias com 16 GB podem sofrer encerramento por falta de memória [OOM] durante o parsing de ASTs complexas).
• Armazenamento: Mínimo de 200 GB SSD ou NVMe (desempenho rápido de leitura/escrita é vital para clones e persistência de cache).
• Referência de nuvem: AWS t3.xlarge, GCP e2-standard-8 ou máquinas virtuais equivalentes.

Requisitos de software e conectividade

• Docker Engine (v24.0+) e Docker Compose (v2.20+).
• Saída HTTPS (porta TCP 443) liberada para as APIs de IA (api.openai.com ou api.anthropic.com).
• Entrada HTTPS para webhooks do GitHub, provida por proxy reverso com certificado TLS ou puramente por rede interna caso o ambiente utilize o GitHub Enterprise Server (GHES).

Passo 1: Criar e configurar o GitHub App privado

A utilização de um GitHub App dedicado substitui tokens de acesso pessoal (PAT) e garante a conformidade com o princípio do menor privilégio.

1. Registrar o GitHub App

1. Acesse o GitHub com permissões de administrador da organização.
2. Navegue até Settings da organização > Developer settings > GitHub Apps > New GitHub App.
3. Preencha os campos básicos:
   • GitHub App name: Nome identificador (ex.: Corp-Internal-Sweep).
   • Homepage URL: URL do portal corporativo ou da documentação interna.
   • Callback URL: Pode permanecer em branco.

2. Configurar o Webhook

• Webhook URL: Endereço protegido pelo proxy reverso (ex.: https://sweep.internal.yourcorp.com/ ou http://<IP_DO_HOST>:8080 em laboratório).
• Webhook secret: Gere um segredo aleatório e robusto executando openssl rand -hex 32 no terminal.

3. Configurar permissões do repositório (Repository permissions)

Atribua estritamente os seguintes acessos:

4. Subscrever eventos de Webhook (Subscribe to events)

Selecione os seguintes eventos:

• Issues (abertura, edição, rotulação, atribuição)
• Issue comment (criação de comentários em issues)
• Pull request (abertura, sincronização, solicitação de revisão)
• Pull request review comment (comentários em linhas de código no PR)
• Check run (conclusão de testes de CI)

5. Gerar a chave privada e instalar o aplicativo

1. Em Where can this GitHub App be installed?, marque Only on this account (Uso privado na organização).
2. Clique em Create GitHub App.
3. Na página de visão geral, anote o número do App ID (ex.: 123456).
4. Role até a seção Private keys e clique em Generate a private key. O arquivo .pem será baixado automaticamente.
5. No menu lateral, clique em Install App, selecione sua organização e aponte os repositórios autorizados a utilizar o Sweep.

Passo 2: Configurar o arquivo de variáveis de ambiente (.env)

Crie o diretório de trabalho no servidor, faça o clone do projeto e estruture o arquivo de configuração:

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

Crie o arquivo .env com as configurações obtidas no Passo 1:

# Identificação do GitHub App
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=seu_segredo_webhook_aqui

# Chave privada RSA emitida pelo GitHub App (formato com quebras escapadas \n ou bloco multilinha)
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Chave de licença do Sweep
# Chaves de avaliação têm validade de 14 dias; licenças de produção requerem contato com o time do Sweep
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# Credenciais dos modelos de inteligência artificial
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Parâmetros de execução do contêiner
PORT=8080
WORKERS=3

Dica sobre a chave RSA: Caso insira a chave GITHUB_APP_PEM em uma única linha, certifique-se de substituir quebras de linha reais por \n. Em automações, pode-se ler o arquivo diretamente com GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)".

Passo 3: Inicializar o Sweep com Docker Compose

O repositório do Sweep disponibiliza um Dockerfile multi-stage com Python 3.10, Redis, ripgrep e analisadores sintáticos, além do arquivo docker-compose.yml.

A estrutura central de serviços é configurada assim:

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"

Inicialização do serviço

Crie o diretório de cache no host e inicie os contêineres:

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

# Compilar a imagem e iniciar em segundo plano
docker compose up --build -d hosted

Monitore os logs para confirmar a inicialização bem-sucedida:

# Validar status do contêiner
docker ps -f name=webhook

# Acompanhar logs em tempo real
docker compose logs -f hosted

Os logs indicarão a inicialização do redis-server interno e o início dos processos Uvicorn escutando em 0.0.0.0:8080.

Passo 4: Configurar o proxy reverso e a segurança perimetral

Em ambientes de produção corporativos, nunca exponha a porta 8080 diretamente sem criptografia TLS. Configure um proxy reverso Nginx na DMZ para realizar a terminação TLS e aplicar listas de controle de acesso (ACL) por IP.

Exemplo de configuração do 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 exclusivamente os blocos de IP oficiais de webhooks do GitHub
    # A lista atualizada de CIDRs pode ser consultada no endpoint 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;
    # Sub-rede interna de testes
    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 ambientes isolados: Se a equipe utiliza o GitHub Enterprise Server (GHES) internamente, todo o tráfego permanece dentro da rede local, dispensando publicação de portas na internet.

Passo 5: Teste e validação do fluxo ponta a ponta

Com os contêineres e o proxy ativos, realize um teste operacional completo:

1. Abertura da Issue de teste: Em um repositório autorizado, crie uma Issue com título iniciado por Sweep:, por exemplo:

   Title: Sweep: Adicionar validação de tokens JWT e testes unitários em utils/auth.py
   Body: Por favor, adicione validações para tokens expirados e assinaturas inválidas em utils/auth.py junto com testes em pytest.
   

2. Monitoramento do Webhook: No console do servidor, verifique a chegada do evento:

   docker compose logs -f hosted
   

   O Sweep autenticará o webhook, solicitará o token de instalação e iniciará a clonagem local.
3. Validação do plano de ação: O Sweep postará um comentário detalhado na Issue, explicando a lista de arquivos afetados e a lógica da alteração.
4. Verificação do Pull Request: Em 2 a 5 minutos, o Sweep publicará uma nova branch (sweep/jwt-validation...) e abrirá o Pull Request com descrição estruturada.
5. Revisão interativa de código: Faça um comentário de revisão em uma linha do diff no PR (ex.: "Sweep: utilize a biblioteca time padrão para verificar expiração"). O Sweep capturará o webhook e enviará um novo commit de ajuste.

Operações e manutenção contínua

Como o Sweep executa processos de longa duração em segundo plano, desligamentos repentinos com docker compose down podem corromper tarefas em andamento.

Reinicialização segura (Zero-Downtime Redeployment)

Utilize o script de reinício suave disponibilizado no repositório:

# Baixar atualizações do código
git pull origin main

# Executar reinício ordenado
bash bin/redeploy.sh

Esse procedimento aguarda a finalização dos workers ativos antes de recriar e subir os novos contêineres.

Limpeza de cache e higiene de disco

Com o passar do tempo, /mnt/caches acumulará árvores de trabalho antigas. Programe uma rotina cron mensal no servidor:

# Excluir pastas de cache inativas há mais de 30 dias
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# Remover imagens Docker não utilizadas
docker image prune -f

Comparativo: Auto-hospedado vs. Nuvem SaaS oficial

Recomendações de engenharia para produção

1. Escolha do modelo de inferência: A precisão do Sweep na modificação de múltiplos arquivos depende diretamente da capacidade analítica do modelo. Utilize Claude 3.5 Sonnet ou GPT-4o. Modelos menores de 7B/8B tendem a corromper a sintaxe dos diffs e gerar falhas de execução.
2. Postura de manutenção interna: O Sweep estabeleceu um padrão importante no ecossistema de agentes via GitHub, mas sua equipe comercial expandiu posteriormente o foco para assistentes integrados a IDEs. Organizações que adotam esse backend devem encará-lo como uma plataforma PaaS interna, destinando capacidade técnica para sua manutenção.
3. Ciclo de rotação de chaves: Institua uma rotina de substituição a cada 90 dias para a chave privada RSA (.pem) do GitHub App e para a WEBHOOK_SECRET, alinhando-se aos padrões de segurança ISO 27001 e SOC 2.

Referências

• 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