Docker와 전용 GitHub App 자격 증명 기반의 Sweep 셀프 호스팅: 온프레미스 안전한 코드 자동화 엔지니어링 가이드

금융, 헬스케어, 방위산업 등 엄격한 컴플라이언스가 요구되는 엔지니어링 조직에서는 자율형 AI 코딩 에이전트를 도입할 때 핵심 독점 소스코드가 외부 멀티테넌트 퍼블릭 클라우드로 유출되는 것을 엄격히 금지하는 보안 규정에 부딪히게 됩니다. 오픈소스 개발자 에이전트인 Sweep(sweepai/sweep 저장소)의 컨테이너 기반 셀프 호스팅 아키텍처는 이러한 규제 장벽을 해소하는 실질적인 엔지니어링 해법을 제공합니다. 전용 사설 VPC 또는 온프레미스 서버에 Docker 기반으로 Sweep 백엔드를 배포하고, 전용 GitHub App과 사내 Webhook을 연동함으로써 코드베이스 인덱싱, AST(추상 구문 트리) 분석, Git 브랜치 체크아웃 및 Pull Request(PR) 생성 전 과정을 사내 방화벽 내부에서 완결하여 "소스코드 자산 제로 유출" 환경을 구현할 수 있습니다.

본 가이드에서는 하드웨어 사이징, 최소 권한 원칙의 GitHub App 자격 증명 구성, Docker Compose 배포, 리버스 프록시 보안 및 무중단 유지보수에 이르기까지 완전한 구축 절차를 안내합니다.

아키텍처 개요: 셀프 호스팅 Sweep의 동작 원리

사내 인프라에서 Sweep을 안정적으로 운영하기 위해서는 내부 서비스가 GitHub 및 대규모 언어 모델(LLM) API와 통신하는 흐름을 명확히 이해해야 합니다.

[GitHub / GitHub Enterprise]
       |
       |  1. Webhook 페이로드 (Issue 생성, PR 리뷰 댓글 등)
       v
[리버스 프록시 / 인그레스 (TLS 종단 및 GitHub IP 화이트리스트)]
       |
       |  2. HTTP 8080 포트 포워딩 (HMAC-SHA256 서명 검증)
       v
[Sweep 컨테이너 (`sweepai/sweep`)]
  ├── 신속 Webhook 응답 핸들러 (FastAPI / Uvicorn)
  ├── 비동기 작업 큐 및 디스패처 (내장 Redis + 백그라운드 워커)
  ├── 코드 인텔리전스 엔진 (Ripgrep 기호 검색 + GitHub Linguist + AST 파서)
  └── 영구 캐시 볼륨 (`/mnt/caches`)
       |
       |  3. 정제된 최소 컨텍스트 프롬프트만 외부 전송
       v
[엔터프라이즈 LLM API (OpenAI / Anthropic / 사내 게이트웨이)]
       |
       |  4. 패치 계획 및 코드 Diff 합성 결과 반환
       v
[Sweep Git 실행 엔진]
       |
       |  5. GitHub App RSA 키로 토큰 발급, 브랜치 푸시 및 PR 생성
       v
[대상 GitHub 저장소 (신규 브랜치 및 Pull Request 자동 생성)]

1. 사내 Webhook 수신 및 서명 검증: 개발자가 저장소에서 Sweep: 접두사를 붙여 Issue를 발행하면 GitHub는 Sweep 호스트의 8080 포트로 JSON 페이로드를 전달합니다. Sweep은 환경 변수에 정의된 WEBHOOK_SECRET을 바탕으로 요청 헤더의 HMAC-SHA256 서명을 즉시 검증하여 무인가 요청을 차단합니다.
2. 비동기 큐 기반 분리: GitHub는 Webhook 응답에 대해 10초 이내의 응답 제한 시간을 강제합니다. Sweep은 유효한 요청을 수신하는 즉시 내장 Redis 큐에 작업을 전달하고 HTTP 200 OK를 즉각 반환하며, 실제 무거운 분석 작업은 백그라운드 워커가 비동기로 처리합니다.
3. 로컬 코드베이스 검색 및 인덱싱: 컨테이너 내부에는 고속 검색 도구인 ripgrep, 언어 식별 모듈 github-linguist, 구문 트리 분석기 tree-sitter가 번들링되어 있습니다. 임시 디렉터리에 코드를 클론하고 인덱스 및 중간 상태를 호스트의 /mnt/caches에 영구 보존합니다.
4. LLM 오케스트레이션 및 데이터 프라이버시: Sweep은 작업 해결에 꼭 필요한 코드 스니펫과 지시문만을 프롬프트로 구성하여 설정된 OPENAI_API_KEY 또는 ANTHROPIC_API_KEY로 전달합니다. 엔터프라이즈 제로 데이터 보존(Zero Data Retention, ZDR) 계약과 결합하면 전체 저장소 코드가 외부 모델 학습이나 저장소에 남지 않습니다.
5. GitHub App 인증 및 Git 자동화: Sweep은 설정된 GitHub App ID와 RSA 개인키(GITHUB_APP_PEM)를 통해 짧은 수명의 설치 액세스 토큰(Installation Access Token)을 동적으로 발급받습니다. 이를 사용하여 최신 브랜치로부터 sweep/... 브랜치를 생성하고, 변경 사항을 커밋한 뒤 PR을 자동 개설합니다.

시스템 요구 사양 및 사전 준비

Sweep은 멀티 프로세스 기반의 AST 파싱, 고속 정규표현식 검색 및 동시 Git 연산을 수행하므로 안정적인 리소스 배정이 필수적입니다.

권장 하드웨어 제원

• 운영체제: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS 또는 엔터프라이즈 Linux(RHEL 9 / Rocky Linux).
• CPU: 최소 4 vCPU(대규모 저장소 병렬 검색을 위해 8 vCPU 권장).
• 메모리: 최소 32 GB RAM(16 GB 설정 시 대규모 코드베이스의 AST 파싱 중 OOM 킬이 발생할 수 있음).
• 디스크: 최소 200 GB SSD 또는 NVMe(빈번한 Git 클론과 로컬 캐시 저장을 위해 고속 디스크 필수).
• 클라우드 인스턴스 기준: AWS t3.xlarge, GCP e2-standard-8 또는 동급 가상 머신.

소프트웨어 및 네트워크 요구 사항

• Docker Engine(v24.0 이상) 및 Docker Compose(v2.20 이상).
• 아웃바운드 통신: LLM API 엔드포인트(api.openai.com 또는 api.anthropic.com)를 향한 TCP 443 포트 연결.
• 인바운드 통신: GitHub의 Webhook을 수신할 수 있는 네트워크 경로. GitHub.com 연동 시 TLS 종단을 갖춘 Nginx 리버스 프록시를 적용하며, 사내 GitHub Enterprise Server(GHES) 환경에서는 인트라넷 내부 통신만으로 구성 가능합니다.

1단계: 프라이빗 GitHub App 생성 및 권한 구성

개인 액세스 토큰(PAT) 대신 전용 GitHub App을 구성하는 것은 최소 권한 원칙을 준수하고 감사 추적성을 확보하기 위한 핵심 조치입니다.

1. GitHub App 신규 등록

1. 조직 관리자 권한을 가진 계정으로 GitHub에 로그인합니다.
2. 조직 Settings > Developer settings > GitHub Apps > New GitHub App으로 이동합니다.
3. 애플리케이션 정보를 입력합니다:
   • GitHub App name: 조직 내 식별 가능한 이름(예: Corp-Internal-Sweep).
   • Homepage URL: 사내 포털 또는 운영 문서 링크.
   • Callback URL: 공란으로 유지 가능.

2. Webhook 구성

• Webhook URL: 리버스 프록시가 적용된 외부 도메인(예: https://sweep.internal.yourcorp.com/, 내부 테스트 시 http://<호스트IP>:8080).
• Webhook secret: 터미널에서 openssl rand -hex 32 명령을 실행하여 생성한 강력한 암호화 문자열을 입력하고 안전하게 보관합니다.

3. 저장소 권한 구성(Repository permissions)

최소 권한 원칙에 따라 다음 권한을 정확히 부여합니다:

4. Webhook 이벤트 구독(Subscribe to events)

다음 이벤트 항목에 체크합니다:

• Issues (Issue 생성, 수정, 라벨 지정, 담당자 할당)
• Issue comment (Issue 댓글 작성)
• Pull request (PR 생성, 동기화, 리뷰 요청)
• Pull request review comment (코드 라인 단위 리뷰 댓글 작성)
• Check run (CI 빌드/테스트 완료)

5. 개인키 생성 및 앱 설치

1. Where can this GitHub App be installed? 항목을 Only on this account(조직 전용 사설 설치)로 지정합니다.
2. Create GitHub App을 클릭하여 생성을 완료합니다.
3. 앱 설정 화면에서 숫자 형태의 App ID(예: 123456)를 기록합니다.
4. 하단의 Private keys 영역으로 이동하여 Generate a private key를 클릭하고 .pem 파일을 다운로드합니다.
5. 좌측 메뉴에서 Install App을 클릭하고, 대상 조직을 선택한 뒤 Sweep을 적용할 저장소를 지정합니다.

2단계: 환경 변수 파일(.env) 작성

호스트 서버에 작업 디렉터리를 생성하고 Sweep 저장소를 클론한 후 설정 파일을 준비합니다:

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

1단계에서 획득한 자격 증명 정보를 .env 파일에 작성합니다:

# GitHub App 인증 정보
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=your_generated_webhook_secret_here

# GitHub App RSA 개인키 (\n으로 개행을 이스케이프한 단일 행 또는 멀티라인 블록)
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Sweep 라이선스 키
# 평가 용도의 경우 14일 체험 라이선스가 제공되며 상용 배포는 공식 팀 문의가 필요합니다
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# 인공지능 추론 모델 API 키
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 컨테이너 포트 및 워커 구성
PORT=8080
WORKERS=3

개인키 서식 유의사항: 단일 행 환경 변수로 전달할 경우 실제 개행 문자를 모두 \n으로 치환해야 합니다. 자동화 배포 시 GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)" 형식으로 파일 내용을 직접 주입할 수도 있습니다.

3단계: Docker Compose를 활용한 컨테이너 구동

Sweep 공식 저장소에는 Python 3.10, Redis, ripgrep 등이 포함된 멀티 스테이지 Dockerfile과 docker-compose.yml이 포함되어 있습니다.

핵심 서비스 구성은 다음과 같습니다:

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"

서비스 기동

호스트의 캐시 저장소를 생성하고 권한을 부여한 뒤 백엔드 서비스를 시작합니다:

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

# 이미지 빌드 및 백그라운드 구동
docker compose up --build -d hosted

컨테이너 상태와 시작 로그를 확인합니다:

# 컨테이너 상태 점검
docker ps -f name=webhook

# 실시간 구동 로그 확인
docker compose logs -f hosted

로그에 내장 redis-server가 정상 초기화되고 Uvicorn 워커 프로세스가 0.0.0.0:8080 포트에서 대기 상태로 전환된 것을 확인할 수 있습니다.

4단계: 리버스 프록시 및 보안 인그레스 구성

프로덕션 환경에서는 암호화되지 않은 HTTP 8080 포트를 외부에 직접 노출해서는 안 됩니다. DMZ 영역에 Nginx 리버스 프록시를 배치하여 TLS 암호화 종단 및 GitHub IP 화이트리스트 필터링을 적용합니다.

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;

    # GitHub 공식 Webhook 발신 IP 대역만 허용
    # 최신 CIDR 목록은 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;
    # 사내 테스트 서브넷
    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;
    }
}

폐쇄망 운영 안내: 사내 인트라넷에 설치된 GitHub Enterprise Server(GHES)를 사용할 경우, 외부 인터넷 포트 포워딩 없이 사내 내부 DNS 매핑만으로 완전한 폐쇄망 구축이 가능합니다.

5단계: 엔드투엔드 파이프라인 검증

배포와 네트워크 설정이 완료되면 실제 대상 저장소에서 전체 워크플로를 테스트합니다:

1. 자동화 Issue 생성: GitHub App이 설치된 저장소에서 제목이 Sweep:으로 시작하는 Issue를 등록합니다:

   Title: Sweep: utils/auth.py 모듈에 토큰 만료 검증 및 단위 테스트 추가
   Body: tests/test_auth.py에 만료된 토큰 및 유효하지 않은 서명 케이스를 처리하는 pytest 테스트 코드를 작성해 주세요.
   

2. Webhook 처리 확인: 서버 터미널에서 실시간 로그를 모니터링합니다:

   docker compose logs -f hosted
   

   Sweep이 수신된 서명을 검증하고, 설치 액세스 토큰을 취득한 뒤 저장소를 클론하여 분석을 시작합니다.
3. 실행 계획 확인: Sweep이 Issue에 자동으로 첫 댓글을 등록하여 수정 대상 파일 목록과 작업 계획을 브리핑합니다.
4. Pull Request 생성 검증: 약 2~5분 이내에 sweep/token-validation-tests 형태의 신규 브랜치가 푸시되고 상세한 설명이 포함된 PR이 자동 생성됩니다.
5. 인터랙티브 코드 리뷰 테스트: 생성된 PR의 코드 diff 라인에 리뷰 댓글(예: "Sweep: 여기서는 정규표현식 대신 표준 split 함수를 사용하세요")을 남기면, Sweep이 이를 감지하여 해당 브랜치에 추가 커밋을 푸시합니다.

운영 및 유지보수: 무중단 재배포와 디스크 관리

Sweep은 백그라운드에서 긴 호흡의 인덱싱 및 추론을 수행하므로, 단순한 docker compose down 명령은 진행 중인 작업을 강제 종료시킬 수 있습니다.

무중단 재배포(Graceful Redeployment)

Sweep 저장소는 안전한 프로세스 재배포 스크립트를 제공합니다:

# 최신 코드 동기화
git pull origin main

# 안전한 재기동 실행
bash bin/redeploy.sh

해당 스크립트는 기존 워커가 처리 중인 작업을 정상 종료할 때까지 대기한 후 새로운 컨테이너를 실행합니다.

캐시 정리 및 디스크 관리

다수의 프로젝트를 인덱싱하면 /mnt/caches 디렉터리에 작업 트리가 누적됩니다. 서버의 월간 cron 작업으로 유휴 캐시를 정리해 주십시오:

# 30일 이상 미사용된 캐시 디렉터리 정리
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# 불필요한 Docker 이미지 레이어 정리
docker image prune -f

비교 분석: 셀프 호스팅 vs 공식 SaaS 멀티테넌트

엔지니어링 현장 권고사항

1. 고성능 추론 모델 채택: 다중 파일 수정의 정확도는 모델의 논리적 추론력에 직결됩니다. Claude 3.5 Sonnet 또는 OpenAI GPT-4o를 연결하십시오. 7B/8B 크기의 소형 오픈소스 로컬 모델을 연결할 경우 diff 포맷 오류나 구문 불일치가 빈번하게 발생합니다.
2. 사내 플랫폼 관점의 유지보수: Sweep 프로젝트는 초기에 GitHub 기반 에이전트 백엔드를 오픈소스로 공개한 후 상업적 초점을 IDE 확장 도구로 확장했습니다. 따라서 이 백엔드를 셀프 호스팅하는 팀은 이를 사내 PaaS 솔루션으로 인식하고 자체 유지보수 역량을 확보해야 합니다.
3. 자격 증명 정기 로테이션: 보안 감사의 무결성을 위해 GitHub App RSA 개인키(.pem)와 WEBHOOK_SECRET을 90일 주기로 정기 갱신하는 정책을 수립하십시오.

참고 자료

• 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