AI-Powered Self-Healing Autopilot for your GitHub Workflows & Issues
PikiLand는 GitHub CI/CD 워크플로 실패 및 이슈를 수신하고, AI 코드 분석과 하네스(Harness) 기반 자가 보완 루프(Ralph Loop)를 거쳐 실제 검증된 단 하나의 패치 PR과 Slack 알림을 자동 생성하는 시스템입니다.
- 오케스트레이터 & 실행 엔진 이원화:
- Web App (Coordinator): TypeScript + Bun (Hono) 기반의 고성능 초경량 오케스트레이터. 웹훅 수신, OAuth 인증, 대시보드, 어드민 및 저장소 워크플로 자동 삽입을 관리합니다.
- CLI (Execution Engine): GitHub Actions 환경에서 단발성으로 동작하는 실행 엔진 (
yourssu/PikiLand-Engine). 분석, Ralph Loop, 패치 적용, PR 생성을 담당합니다.
- 단방향 프로덕션 로그 수집 & 1회성 SSH 프로비저닝 (Zero Trust):
- 대시보드 UI에서 1회용 SSH Private Key(
.pem)를 통해 원격 EC2에 Fluent Bit 수집기를 자동 설치하고grep정규식 필터를 주입하며 접속 후 백엔드 SSH 키 메모리 및 임시 파일은 원천 파기됩니다.
- 대시보드 UI에서 1회용 SSH Private Key(
- LLM 기반 로그 경로 자동 추론:
application.yml,logback.xml,docker-compose.yml등 프로젝트 설정 파일을 분석하여 프로덕션 로그 경로를 자동 추론합니다.
- GitHub App 설치 완료 전용 안내 페이지 (
/setup) & Direct API 로딩 최적화:- 앱 설치 직후 연결되는 전용 완료 페이지(
/setup)를 제공하고, 설치된 저장소만 direct로 로딩하여 대시보드 성능을 최적화합니다.
- 앱 설치 직후 연결되는 전용 완료 페이지(
- Harness & Ralph Loop 기반 자가 보완 검증:
- 패치 전 테스트 실패(Red)로 버그를 재현하고, 패치 후 테스트 성공(Green) 및 회귀 테스트를 통과한 패치만 PR로 생성합니다.
- Harness Command 자동 추론:
- 저장소 연동 시 Gradle, Maven, npm, pytest 등 프로젝트 빌드/테스트 도구를 자동 추론하여 추천합니다.
- 독립된 어드민 페이지 & 보안 액세스 제어:
- 중앙 시스템 설정(GitHub App ID, Private Key, OAuth Credentials)을 별도의
/admin페이지로 분리하고PIKILAND_ADMIN_USERS기반 접근 권한을 적용했습니다.
- 중앙 시스템 설정(GitHub App ID, Private Key, OAuth Credentials)을 별도의
- 소유자(Owner)별 저장소 분류 & 다크/라이트 테마:
- 대시보드 내 저장소들을 소유자별 탭으로 깔끔하게 필터링할 수 있으며, 다크/라이트 테마 전환 스위치를 제공합니다.
[ GitHub Webhook / Issues ]
│
▼
┌─────────────────────────────────────────┐
│ PikiLand Web App (Coordinator) │
│ - 웹훅 수신 & OAuth2 인증 │
│ - pikiland.yml 워크플로 자동 삽입 │
│ - 대시보드 & 어드민 UI (/admin) │
└────────────────────┬────────────────────┘
│ workflow_dispatch
▼
┌─────────────────────────────────────────┐
│ Target Repo: .github/workflows/pikiland │
│ └─ PikiLand Engine (CLI) │
│ - Harness 기반 버그 재현 (Red) │
│ - AI 기반 원인 분석 & 패치 생성 │
│ - Ralph Loop 자가 보완 검증 (Green) │
│ - Verified PR 생성 & Slack 알림 │
└─────────────────────────────────────────┘
- 역할: 사용자 대시보드, GitHub OAuth 로그인, 웹훅 수신, 시스템 설정 및 워크플로 자동 삽입.
- 실행 환경: 지속 구동되는 초경량 웹 서버 (
TypeScript + Bun,Hono, 포트8080).
- 역할: 격리된 GitHub Actions Runner 상에서 가동되는 단발성 패치/검증 엔진.
- 실행 환경: 대상 저장소의 GitHub Actions Runner (
TypeScript + BunCLI 실행).
Bun 1.2+ 환경이 필요합니다.
# 1. 환경 변수 설정 (.env 작성)
cp .env.example .env
# 2. 의존성 설치
bun install
# 3. 로컬 개발 서버 실행 (Live Reload)
bun dev서버 실행 후 브라우저에서 http://localhost:8080으로 접속할 수 있습니다.
| 환경 변수 | 설명 |
|---|---|
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
대시보드 로그인용 GitHub OAuth 인증 정보 |
GITHUB_APP_ID, GITHUB_PRIVATE_KEY_PATH |
GitHub App 인증 정보 |
GITHUB_WEBHOOK_SECRET |
GitHub Webhook HMAC 서명 검증 키 |
PIKILAND_ADMIN_USERS |
어드민 페이지(/admin)에 접근할 수 있는 GitHub 사용자명 (쉼표 구분) |
DATABASE_PATH |
SQLite DB 파일 경로 (기본값: ./data/pikiland.sqlite) |
LOG_RECEIVER_TOKEN |
EC2 Fluent Bit 원격 로그 수신 인증 Bearer 토큰 |
DEBUG (또는 PIKILAND_DEBUG) |
디버그 모드 여부 (true 시 웹훅 서명 검증 및 저장소 소유권 검사까지 우회, 기본값: false) |
PIKILAND_UI_PREVIEW |
UI 미리보기 모드 (true 시 GitHub OAuth 로그인만 우회 — 웹훅/소유권 검사는 그대로 유지, 기본값: false) |
DEBUG와 PIKILAND_UI_PREVIEW는 NODE_ENV=production이면 값과 무관하게 항상 비활성화됩니다.
Webhook HMAC 검증, 로그 정제 및 시그니처 해싱, Harness 추론 단위/통합 테스트 스위트를 실행합니다.
bun test랜딩/대시보드/어드민/설치완료 화면과 다크·라이트 테마 토글을 실제 브라우저로 검증합니다. 개발자의 로컬 .env와는 완전히 분리된 전용 포트(4300)·전용 SQLite 파일로 서버를 띄우므로 bun run dev로 띄워둔 서버나 프로덕션 설정과 섞이지 않습니다.
bunx playwright install --with-deps chromium # 최초 1회
bun run test:e2e/admin처럼 로그인 여부에 따라 응답이 달라지는 화면은 tests/e2e/support/auth.ts의 loginAs()로 실제 세션 쿠키 포맷을 주입해 검증합니다 (PIKILAND_UI_PREVIEW로 우회하지 않고 실제 인증 코드 경로를 그대로 통과).
프로젝트의 세부 설계, 아키텍처, 배포 가이드는 docs/ 디렉터리의 문서를 참고하세요.
| 문서 | 설명 |
|---|---|
| 📖 Product Design | 제품 범위, 핵심 철학 및 MVP 결정 사항 |
| 🏗️ Architecture & Data Pipeline | 전체 데이터 파이프라인, Harness 및 Ralph Loop 상세 계약 |
| 🚀 Deployment Guide | Nginx 설정, GitHub App 등록, Docker 배포 및 대상 저장소 설정 가이드 |
| 🔍 Competitive Research | 타 솔루션 및 기존 코딩 에이전트와의 차별점 분석 |
| 💡 Future Ideas | MVP 이후 고려할 확장 아이디어 보관소 |