Codernetes

자동화된 GitHub 이슈 해결 시스템

Codernetes는 GitHub 이슈를 자동으로 해결하고 Pull Request를 생성하는 분산 작업 실행 플랫폼입니다. LLM Agent(Claude Code, Codex, Aider)를 활용하여 코드 변경을 자동화하고, Master/Node 아키텍처로 확장 가능한 워크플로우를 제공합니다.

🎨 Codernetes

🎯 주요 기능

• 🤖 자동 코드 작업: GitHub/Linear 이슈를 선택하면 LLM Agent가 자동으로 코드를 수정
• 🔄 PR 자동 생성: 변경사항을 커밋하고 Pull Request 자동 생성
• 📐 Linear 통합: Linear 이슈 관리 시스템 완벽 지원 (팀 선택, 이슈 필터링, 우선순위)
• 📊 실시간 모니터링: 웹 대시보드에서 작업 진행 상황 실시간 추적
• ⚡ 분산 처리: Master/Node 아키텍처로 여러 작업 병렬 실행
• 🚀 동시 작업 실행: 단일 노드에서 최대 5개 작업 동시 처리 (설정 가능)
• 💬 응답 전용 모드: 코드 변경 없이 Agent 응답만 제공하는 작업 지원
• 🛡️ 에러 핸들링: 자동 에러 분류 및 재시도 로직
• 🔍 작업 로그: 실시간 로그 스트리밍 및 검색

🏗️ 아키텍처

┌─────────────┐
│  Frontend   │  React + Vite (Port 5173)
│  Dashboard  │
└──────┬──────┘
       │ HTTP/WebSocket
┌──────▼──────────────────┐
│   Master Server         │
│  - HTTP API (8080)      │
│  - WebSocket Hub (8765) │
│  - SQLite DB            │
│  - Job Scheduler        │
└──────┬──────────────────┘
       │ WebSocket
┌──────▼───────┐  ┌─────────────┐  ┌─────────────┐
│   Node 1     │  │   Node 2    │  │   Node 3    │
│   Worker     │  │   Worker    │  │   Worker    │
└──────┬───────┘  └─────────────┘  └─────────────┘
       │
       └─► GitHub Clone → LLM Agent → Commit → Push → PR

🚀 빠른 시작

필수 요구사항

• Python 3.12+
• Node.js 18+
• uv (Python 패키지 관리)
• GitHub Personal Access Token
• LLM Agent CLI (하나 선택):
  • Claude Code: npm i -g @anthropic-ai/claude-code + ANTHROPIC_API_KEY
  • Codex: npm i -g @openai/codex + ChatGPT Plus/Pro 계정 또는 OPENAI_API_KEY

설치

# 1. 저장소 클론
git clone https://github.com/your-org/codernetes.git
cd codernetes

# 2. Python 의존성 설치
uv sync

# 3. Frontend 설치
cd frontend
npm install
cd ..

# 4. 환경 변수 설정
cp .env.sample .env
# .env 파일 편집하여 필수 값 입력:
# GITHUB_TOKEN, ANTHROPIC_API_KEY, JOBS_WORK_DIR

실행

Terminal 1 - Master 서버:

uv run python -m master.server --host 0.0.0.0 --port 8765 --http-port 8080

Terminal 2 - Node 클라이언트:

# 기본값 사용 (localhost:8765에 연결)
uv run python -m node.client

# 또는 명시적으로 지정
uv run python -m node.client --host localhost --port 8765

Terminal 3 - Frontend:

cd frontend
npm run dev

브라우저에서 http://localhost:5173 접속

첫 번째 작업 실행

1. Settings 탭에서 GitHub Token 등록
2. Jobs 탭으로 이동
3. GitHub 저장소 선택 → 이슈 선택
4. Agent 타입 선택 (claude-code 권장)
5. 작업 생성 클릭
6. 실시간으로 작업 진행 상황 모니터링
7. PR 생성 완료 후 GitHub에서 확인

📚 문서

• 사용자 가이드 - 기본 사용법 및 고급 설정
• Linear 통합 가이드 - Linear 이슈 관리 시스템 연동
• 운영 가이드 - 프로덕션 배포 및 운영
• 구현 계획 - Phase별 구현 상세
• 구현 상태 - Phase 1 완료 현황

🎮 주요 컴포넌트

Master Server

중앙 조율 서버로 다음 기능을 제공합니다:

• HTTP API (Port 8080): Job 생성, 조회, 상태 업데이트
• WebSocket Hub (Port 8765): Node 서버들과 실시간 통신
• SQLite Database: Job, Node, 로그 저장
• Job Scheduler: Node에 Job 할당

주요 API 엔드포인트:

• GET /api/status - 시스템 상태
• GET /api/github/repos - GitHub 저장소 목록
• GET /api/github/issues - 이슈 목록
• POST /api/jobs - Job 생성
• GET /api/jobs - Job 목록
• GET /api/jobs/{id} - Job 상세
• GET /api/jobs/{id}/logs - Job 로그

Node Server

작업 실행 워커로 다음을 수행합니다:

1. 동시 작업 처리: 최대 5개 작업 병렬 실행 (node-config.yaml에서 설정 가능)
2. 격리된 작업 환경: 각 작업은 독립된 디렉터리에서 실행
3. Git 저장소 클론
4. LLM Agent 실행 (Claude Code, Codex, Aider)
5. 변경사항 커밋 (변경사항이 있는 경우)
6. GitHub에 Push (변경사항이 있는 경우)
7. Pull Request 생성 (변경사항이 있는 경우)
8. Agent 응답 전달 (코드 변경이 없어도 Agent의 분석/설명 제공)
9. 실시간 로그 전송

동시 작업 실행 설정 (node-config.yaml):

# Performance
max_concurrent_jobs: 5  # 동시 실행 가능한 최대 작업 개수 (기본값: 5)

Frontend Dashboard

React + Vite 기반 웹 대시보드:

• Jobs: 작업 생성 및 모니터링
• Settings: GitHub 연동 및 시스템 설정
• Nodes: 연결된 Node 서버 관리

🔧 고급 설정

Agent CLI 설정

Codernetes는 2가지 LLM Agent를 지원합니다:

1. Claude Code

# 설치
npm i -g @anthropic-ai/claude-code

# 환경 변수
export ANTHROPIC_API_KEY=sk-ant-your-key

# 특징
# - --print 플래그: 비대화형 출력 모드
# - --dangerously-skip-permissions: 자동화를 위한 권한 우회
# - Codernetes는 신뢰된 환경에서 이 플래그들을 사용합니다

# 수동 테스트
claude --print "Say hello"
claude --print --dangerously-skip-permissions "Create a test file"

2. Codex

# 설치 (npm)
npm install -g @openai/codex

# 또는 Homebrew (macOS)
brew install --cask codex

# 인증 방법 (둘 중 하나)
# 1. ChatGPT 계정 (Plus/Pro/Team/Enterprise)
codex  # 브라우저에서 로그인

# 2. OpenAI API Key
export OPENAI_API_KEY=sk-your-openai-key

# 특징
# - 'codex exec' 명령으로 비대화형 실행
# - ChatGPT 계정 또는 API Key 인증
# - GitHub Action, TypeScript SDK 지원
# - MCP (Model Context Protocol) 서버 연결 지원
# - 구성 파일: ~/.codex/config.toml

# 더 많은 정보: https://github.com/openai/codex

.codernetes/agent.md

저장소에 .codernetes/agent.md 파일을 추가하여 Agent 동작을 커스터마이징할 수 있습니다:

# Codernetes Agent Configuration

## Agent Settings
**Agent Type**: claude-code
**Auto Commit**: true

## Code Style
**Linter**: eslint
**Formatter**: prettier

## Testing Policy
**Required**: true
**Command**: npm test
**Coverage Threshold**: 80%

## Protected Paths
- /config/
- /secrets/

## System Prompt
You are a senior software engineer.
Follow existing code style and patterns.
Write comprehensive tests for new features.

환경 변수

.env 파일에서 설정할 수 있는 주요 환경 변수:

# GitHub
GITHUB_TOKEN=ghp_your_token_here

# Linear (선택)
LINEAR_USER_ID=user:12345
LINEAR_API_KEY=lin_api_your_key_here

# Anthropic (Claude Code)
ANTHROPIC_API_KEY=sk-ant-your_key_here

# 작업 디렉토리
JOBS_WORK_DIR=/tmp/codernetes-jobs

# 서버 설정
MASTER_HOST=0.0.0.0
MASTER_PORT=8765
MASTER_HTTP_PORT=8080

# 로그 레벨
LOG_LEVEL=INFO

🛡️ 에러 핸들링

Codernetes는 포괄적인 에러 핸들링 시스템을 갖추고 있습니다:

에러 분류:

• Network errors
• Authentication errors
• Resource errors
• Timeout errors
• Git errors
• Agent execution errors

자동 재시도:

• Network: 3회, 5초 간격
• Timeout: 2회, 10초 간격
• Agent: 2회, 15초 간격
• Git: 2회, 5초 간격

재시도 불가:

• Authentication errors
• Validation errors

📊 작업 워크플로우

코드 변경 작업

1. pending      → Job 생성
2. queued       → 큐 대기
3. running      → 실행 시작
4. accepted     → Node가 수락
5. cloning      → Git 클론
6. agent_working → Agent 실행
7. committing   → 변경사항 커밋
8. pushing      → GitHub Push
9. pr_creating  → PR 생성 중
10. pr_created  → PR 생성 완료 ✅

응답 전용 작업 (코드 변경 없음)

1. pending      → Job 생성
2. queued       → 큐 대기
3. running      → 실행 시작
4. accepted     → Node가 수락
5. cloning      → Git 클론
6. agent_working → Agent 실행 (분석/설명)
7. succeeded    → Agent 응답 제공 완료 ✅
   (committing, pushing, pr_creating 단계 스킵)

응답 전용 모드 사용 예시:

• 코드 리뷰 및 분석
• 아키텍처 설명
• 버그 원인 분석
• 개선 제안
• 문서 질문 답변

🔐 보안

GitHub Token 권한

필요한 최소 권한:

• repo (저장소 접근)
• workflow (GitHub Actions)

API Key 관리

• 환경 변수로 관리
• 절대 코드에 하드코딩 금지
• 정기적으로 키 순환 (90일 권장)

네트워크

• Master/Node 간 WebSocket은 내부 네트워크만 허용
• Frontend는 Nginx 리버스 프록시 사용
• HTTPS/TLS 설정 권장

🧪 테스트

Unit/Integration 테스트

# Python 테스트
uv run pytest

# Frontend 테스트
cd frontend
npm test

E2E 테스트 (Playwright)

E2E 테스트로 전체 시스템 워크플로우를 검증할 수 있습니다.

# 1. E2E 테스트 환경 설정 (최초 1회)
cd tests/e2e
./setup.sh

# 2. Master와 Node 서버 시작 (별도 터미널)
uv run python -m master.server
uv run python -m node.client

# 3. E2E 테스트 실행
cd tests/e2e
./run-tests.sh

# 또는 직접 실행
npm test                 # 모든 테스트
npm run test:critical    # 크리티컬 테스트만
npm run test:headed      # 브라우저 표시 모드
npm run test:ui          # 인터랙티브 UI 모드

# 테스트 리포트 보기
npm run report

E2E 테스트 커버리지: 37개 테스트 케이스 (기본 워크플로우, 노드 연결, 작업 취소, GitHub 통합, 에러 처리)

자세한 내용은 E2E 테스트 README 참조

📈 모니터링

로그 확인

# Master 로그
tail -f /var/log/codernetes/master.log

# Node 로그
tail -f /var/log/codernetes/node.log

# 특정 Job 로그 (웹 대시보드에서 실시간 확인 가능)

Job 통계

sqlite3 /var/lib/codernetes/codernetes.db <<EOF
SELECT status, COUNT(*) FROM jobs GROUP BY status;
EOF

🤝 기여하기

기여는 언제나 환영합니다!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참고하세요.

🎯 로드맵

Phase 1 (완료) ✅

• GitHub 통합 및 이슈 선택
• Linear 통합 (팀 선택, 이슈 필터링, 브랜치 자동 생성)
• LLM Agent 실행 (Claude Code, Codex, Aider)
• PR 자동 생성
• 웹 대시보드
• 에러 핸들링
• 실시간 로그
• 동시 작업 실행 (노드당 최대 5개, 설정 가능)
• 응답 전용 모드 (코드 변경 없는 작업)

Phase 2 (계획)

• PR 자동 리뷰
• 자동 병합 (조건부)
• Slack/Telegram 통합
• 다중 저장소 지원
• 작업 템플릿

Phase 3 (계획)

• 성능 최적화
• 고급 스케줄링
• 작업 우선순위
• 리소스 관리
• 통계 및 분석

📞 지원

• Issues: GitHub Issues
• 문서: /docs 디렉토리
• Email: jiunbae.dev@gmail.com

🙏 감사의 말

이 프로젝트는 다음 오픈소스 프로젝트들의 도움을 받아 개발되었습니다:

• Claude by Anthropic
• FastAPI
• React
• PyGithub
• websockets

---

Made with ❤️ by the Codernetes Team

버전: 1.1 (Phase 1 Complete + Concurrent Execution) 최종 업데이트: 2025-11-01