claude-hub

🚀 빠른 시작 가이드 (Quick Start Guide) | 💬 Discord | 📚 문서 (Documentation) | 📖 전체 설정 (Complete Setup) | 🔐 인증 (Authentication)

Claude Code를 완전 자율적인 GitHub 봇으로 배포하세요. 자신만의 봇 계정을 생성하고, 이슈(Issue)나 PR(Pull Request)에서 해당 계정을 언급하기만 하면 AI 기반의 엔드 투 엔드 (end-to-end) 개발이 이루어지는 것을 확인할 수 있습니다. Claude는 전체 기능을 구현하고, 코드를 리뷰하며, PR을 머지(Merge)하고, CI 빌드를 기다리며, 작업이 완료될 때까지 몇 시간 동안 자율적으로 실행될 수 있습니다. 컨테이너 격리, 자동화된 워크플로우(Workflow), 지능형 프로젝트 관리를 갖춘 프로덕션 준비 완료(Production-ready) 마이크로서비스(Microservice)입니다.

# 모든 GitHub 이슈 또는 PR에서 (설정된 봇 계정 사용):
@YourBotName OAuth를 사용한 사용자 인증 구현해줘
@YourBotName 이 PR의 보안 취약점을 리뷰해줘
...

Claude는 완전한 개발 워크플로우를 자율적으로 처리합니다. 전체 저장소(Repository)를 분석하고, 처음부터 기능을 구현하며, 철저한 코드 리뷰를 수행하고, 풀 리퀘스트(Pull Request)를 관리하며, CI/CD 파이프라인을 모니터링하고, 자동화된 피드백에 응답합니다. 이 모든 과정은 인간의 개입 없이 이루어집니다. 컨텍스트 스위칭 (Context switching)도, 수동 감독도 필요하지 않습니다. 여러분이 일하는 곳에서 원활한 자율 개발이 이루어집니다.

Cloudflare Tunnel을 사용하여 도메인이나 복잡한 설정 없이 Claude가 GitHub 이슈에 응답하도록 만드는 10분 빠른 시작 가이드를 따라해보세요!

# 1. 클론(Clone) 및 설정
git clone https://github.com/claude-did-this/claude-hub.git
cd claude-hub
...

끝입니다! 이제 봇을 사용할 준비가 되었습니다. 자세한 지침과 웹후크(Webhook) 설정은 전체 빠른 시작 가이드를 참조하세요.

기능 구현 (Feature Implementation): 요구사항부터 완전히 테스트된 프로덕션 준비 완료 코드까지
코드 리뷰 및 품질 (Code Review & Quality): 보안, 성능 및 베스트 프랙티스(Best practices)를 포함한 종합적인 분석
PR 라이프사이클 관리 (PR Lifecycle Management): 브랜치(Branch) 생성, 변경 사항 커밋(Commit), 코드 푸시(Push) 및 머지(Merge) 프로세스 관리
CI/CD 모니터링 (CI/CD Monitoring): 빌드를 능동적으로 대기하고, 테스트 결과를 분석하며, 실패를 수정
자동화된 코드 응답 (Automated Code Response): 자동화된 리뷰 댓글에 응답하고 피드백을 기반으로 적응

수 시간 단위의 작업 (Multi-hour Operations): 복잡한 작업이 100% 완료될 때까지 자율적으로 작업을 지속
의존성 해결 (Dependency Resolution): 차단 요소(blockers)를 처리하고, 외부 프로세스를 기다리며, 자동으로 작업을 재개
컨텍스트 보존 (Context Preservation): 장시간 실행되는 작업 전반에 걸쳐 프로젝트 상태와 진행 상황을 유지
적응형 문제 해결 (Adaptive Problem Solving): 테스트 결과 및 코드 리뷰 피드백을 기반으로 솔루션을 반복 개선

완전한 기능 구현 (Complete Feature Implementation): 요구사항부터 배포까지 Claude가 전체 기능을 코딩
지능형 PR 관리 (Intelligent PR Management): 풀 리퀘스트 (Pull Requests)를 자동으로 생성, 리뷰 및 병합
CI/CD 통합 (CI/CD Integration): 빌드를 기다리고, 테스트 실패에 대응하며, 자동화된 워크플로우를 처리
장시간 실행 작업 (Long-running Tasks): 복잡한 프로젝트가 완료될 때까지 수 시간 동안 자율적으로 작동
자동 라벨링 (Auto-labeling): 콘텐츠 분석을 통해 새로운 이슈 (Issues)에 자동으로 태그 지정
컨텍스트 인식 (Context-aware): Claude가 전체 리포지토리 (Repository) 구조와 개발 패턴을 이해
상태 비저장 실행 (Stateless execution): 각 요청은 격리된 Docker 컨테이너에서 실행

• 전략적 러너 (Runner) 분배를 통한 병렬 테스트 실행

• 조건부 Docker 빌드 (코드 변경 시에만 실행)

• 1초 미만의 응답 시간을 위한 리포지토리 캐싱 (Repository caching)

• 시간 측정 지표를 포함한 고급 빌드 프로파일링 (Build profiling)

• 웹훅 서명 검증 (Webhook signature verification, HMAC-SHA256)

• AWS IAM 역할 기반 인증 (Role-based authentication)

• 프리 커밋 (Pre-commit) 자격 증명 스캐닝

• 최소 권한을 통한 컨테이너 격리

• 세밀한 GitHub 토큰 범위 지정 (Fine-grained GitHub token scoping)

현재 설정 (Current Setup): 본인만의 GitHub 봇 계정을 생성해야 합니다:

봇 전용 GitHub 계정 생성 (예: MyProjectBot)

봇 계정에서 리포지토리 권한을 가진 개인 액세스 토큰 (Personal Access Token) 생성

환경 변수에 봇 사용자 이름 설정

봇 계정을 리포지토리의 협업자 (Collaborator)로 추가

향후 출시 계획 (Future Release): 우리는 이를 범용 봇 계정을 제공하는 GitHub App으로 출시할 계획입니다. 이를 통해 셀프 호스팅 (Self-hosted) 인스턴스에 대한 동일한 기능을 유지하면서도, 개별적인 봇 설정의 필요성을 제거할 것입니다.

# 핵심 설정 (Core settings)
BOT_USERNAME=YourBotName # GitHub 봇 계정 사용자 이름 (직접 봇 계정을 생성하세요)
GITHUB_WEBHOOK_SECRET=<generated> # 웹훅 검증 (Webhook validation)
...

사용량 기반의 API 비용 대신 기존의 Claude Max 구독을 자동화에 사용하세요:

# 1. 대화형 인증 설정 실행
./scripts/setup/setup-claude-interactive.sh
# 2. 컨테이너 내에서: 구독 정보로 인증
...

전제 조건 (Prerequisites): Claude Max 구독 (5x 또는 20x 플랜). Claude Pro는 Claude Code 접근 권한을 포함하지 않습니다.

상세 정보 (Details): 설정 컨테이너 가이드 (Setup Container Guide)

ANTHROPIC_API_KEY=sk-ant-your-api-key-here

최적의 용도 (Best for): 프로덕션 환경 (Production environments), 팀 단위 사용, 보장된 안정성.

상세 정보 (Details): 인증 가이드 (Authentication Guide)

AWS_REGION=us-east-1
ANTHROPIC_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
CLAUDE_CODE_USE_BEDROCK=1

최적의 용도 (Best for): 엔터프라이즈 배포 (Enterprise deployments), AWS 통합, 컴플라이언스 요구 사항.

상세 정보 (Details): 인증 가이드 (Authentication Guide)

• Repository → Settings → Webhooks로 이동
• 웹훅 추가:
  Payload URL:https://your-domain.com/api/webhooks/github

Content type:application/json

Secret: 귀하의 GITHUB_WEBHOOK_SECRET

Events: "Send me everything" 선택

# 옵션 1: IAM 인스턴스 프로필 (EC2)
# 인스턴스 메타데이터를 자동으로 사용
# 옵션 2: ECS 태스크 역할 (ECS Task Role)
...

웹훅 API를 통해 비동기 Claude 세션을 생성하세요:

# 새 세션 생성
curl -X POST http://localhost:3002/api/webhooks/claude \
-H "Content-Type: application/json" \
...

# 기본 사용법
./cli/claude-webhook myrepo "Review the authentication flow"
# PR 리뷰
...

자율 실행을 위해 각기 다른 작업에 맞춤화된 보안 프로필 (Security profiles)을 사용합니다:

Auto-tagging (자동 태깅): 최소 권한 (읽기 + GitHub 도구만 허용)
PR Reviews (PR 리뷰): 표준 권한 (자동 병합 기능이 포함된 전체 도구 액세스)
Feature Development (기능 개발): 전체 개발 권한 (코드 편집, 테스트, CI 모니터링)
Long-running Tasks (장기 실행 작업): 체크포인트/재개 (checkpoint/resume) 기능이 포함된 확장된 컨테이너 수명
Custom Commands (사용자 정의 명령): --allowedTools 플래그를 통해 구성 가능

GitHub Event → Webhook Endpoint → Signature Verification
↓ ↓
Container Spawn ← Command Parser ← Event Processor
...

Spawn (생성): 요청당 새로운 Docker 컨테이너를 생성하며, 장기 작업을 위해 확장된 수명 제공
Clone (클론): 저장소를 가져오거나 (또는 캐시 히트 시) 전체 개발 환경 설정 완료
Execute (실행): Claude가 기능을 구현하고, 테스트를 실행하며, CI를 모니터링하고, 피드백을 자율적으로 처리
Iterate (반복): 작업 완료 시까지 지속적인 개발 사이클 수행
Deploy (배포): 결과물 푸시, PR 병합, 작업 완료 표시
Cleanup (정리): 작업 성공 완료 후 컨테이너 파괴

Network (네트워크): Webhook 서명 검증
Authentication (인증): GitHub 사용자 허용 목록 (allowlist)
Authorization (인가): 세분화된 토큰 권한 (Fine-grained token permissions)
Execution (실행): 컨테이너 격리 (Container isolation)
Tools (도구): 작업별 허용 목록 (allowlists)

REPO_CACHE_DIR=/cache/repos
REPO_CACHE_MAX_AGE_MS=3600000 # 1시간

CONTAINER_LIFETIME_MS=7200000 # 2시간 타임아웃
CLAUDE_CONTAINER_IMAGE=claudecode:latest

• 병렬 Jest 테스트 실행
• Docker 레이어 캐싱
• 조건부 이미지 빌드
• 무거운 작업을 위한 셀프 호스팅 러너 (Self-hosted runners)

curl http://localhost:3002/health

docker compose logs -f webhook

npm test # 모든 테스트
npm run test:unit # 단위 테스트만
npm run test:integration # 통합 테스트만
...

DEBUG=claude:* npm run dev

• 컨테이너 인증 설정 (Setup Container Authentication) - 구독 기반 인증에 대한 기술적 세부 사항

• 인증 가이드 (Authentication Guide) - 모든 인증 방법 및 문제 해결

• 전체 워크플로 (Complete Workflow) - 엔드 투 엔드 (End-to-end) 기술 가이드

• 컨테이너 설정 (Container Setup) - Docker 구성 세부 사항

• AWS 베스트 프랙티스 (AWS Best Practices) - IAM 및 자격 증명 관리

• GitHub 연동 (GitHub Integration) - Webhook 이벤트 및 권한

• 스크립트 문서 (Scripts Documentation) - 유틸리티 스크립트 및 명령

• 명령 참조 (Command Reference) - 빌드 및 실행 명령

# 의존성 설치
npm install
# pre-commit hook 설정
...

• async/await 패턴을 사용하는 Node.js 20+
• 80% 이상의 커버리지 목표를 가진 Jest 테스트
• 코드 포매팅을 위한 ESLint + Prettier
• 버전 관리를 위한 Conventional commits

Webhook 응답 없음 (Webhook not responding)

• 시그니처 비밀값 (signature secret) 일치 여부 확인
• GitHub 토큰 권한 확인
• Webhook URL 접근 가능 여부 확인

Claude 타임아웃 (Claude timeouts)

• CONTAINER_LIFETIME_MS 값 증가
• AWS Bedrock 할당량 (quotas) 확인
• 네트워크 연결 상태 확인

권한 거부 (Permission denied)

• AUTHORIZED_USERS에 사용자 포함 여부 확인

• GitHub 토큰 스코프 (scopes) 확인

• AWS IAM 권한 확인

• 이슈 보고: GitHub Issues

• 상세 문제 해결: 전체 워크플로 가이드 (Complete Workflow Guide)

MIT - 자세한 내용은 LICENSE 파일을 참조하세요.