Gopedia Synapse

GitHub Issues와 Pull Requests를 Outline Wiki로 자동 동기화하는 FastAPI 서비스입니다.

🚀 주요 기능

• GitHub Issues/PRs 조회: GitHub API를 통해 이슈와 PR 데이터 수집
• Outline 문서 생성: GitHub 데이터를 마크다운 형식으로 변환하여 Outline에 문서 생성
• 자동 동기화: 일괄 또는 개별 항목 동기화 지원
• 백그라운드 처리: 대량 데이터 처리를 위한 백그라운드 작업
• 상태 모니터링: 동기화 상태 및 서비스 헬스 체크

📁 프로젝트 구조

gopedia_synapse/
├── app/
│   ├── core/           # 핵심 설정 및 데이터베이스
│   ├── controllers/    # API 엔드포인트
│   ├── services/       # 비즈니스 로직
│   ├── repositories/   # 데이터 접근 계층
│   ├── dto/           # 데이터 전송 객체
│   ├── utils/         # 유틸리티 함수
│   └── main.py        # FastAPI 애플리케이션
├── requirements.txt
├── .env.example
└── README.md

⚡ 빠른 시작

python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8800

1. 저장소 클론 및 의존성 설치

pip install -r requirements.txt

2. 환경 변수 설정

.env.example을 .env로 복사하고 필요한 값들을 설정하세요:

cp .env.example .env

필수 환경 변수

# Outline API 설정
OUTLINE_SUBDOMAIN=your_subdomain
OUTLINE_DOMAIN=your_domain.com
OUTLINE_API_TOKEN=your_outline_api_token
OUTLINE_COLLECTION_ID=your_collection_id

# GitHub API 설정
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_owner
GITHUB_REPO=your_github_repo

# 데이터베이스 설정 (선택사항)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=outline_db
DB_USER=your_db_user
DB_PASSWORD=your_db_password

3. 서버 실행

# 개발 모드
uvicorn app.main:app --reload --host 0.0.0.0 --port 8800

# 또는 Python으로 직접 실행
python -m app.main

서비스가 실행되면 다음 URL에서 접근할 수 있습니다:

• API 문서: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• 서비스 정보: http://localhost:8000/

📚 API 사용법

GitHub 데이터 조회

# 모든 Issues 조회
curl http://localhost:8000/github/issues

# 특정 Issue 조회
curl http://localhost:8000/github/issues/123

# Pull Requests 조회
curl http://localhost:8000/github/pull-requests?state=open&limit=50

동기화 작업

# 전체 동기화 (Issues + PRs)
curl -X POST http://localhost:8000/sync/github-to-outline \
  -H "Content-Type: application/json" \
  -d '{
    "sync_type": "both",
    "state": "all",
    "limit": 100
  }'

# 특정 Issue 동기화
curl -X POST http://localhost:8000/sync/issue/123

# 특정 PR 동기화
curl -X POST http://localhost:8000/sync/pull-request/456

서비스 상태 확인

# 헬스 체크
curl http://localhost:8000/health

# 동기화 서비스 상태
curl http://localhost:8000/sync/status

# 설정 검증
curl -X POST http://localhost:8000/sync/validate-settings

🔧 환경 설정 가이드

Outline API 토큰 발급

1. Outline 관리자 계정으로 로그인
2. Settings > API > Create new token
3. 생성된 토큰을 OUTLINE_API_TOKEN에 설정

GitHub Personal Access Token 생성

1. GitHub Settings > Developer settings > Personal access tokens
2. "Generate new token" 클릭
3. 필요한 권한 선택:
   • repo (private 저장소의 경우)
   • public_repo (public 저장소의 경우)
4. 생성된 토큰을 GITHUB_TOKEN에 설정

Outline Collection ID 찾기

# 컬렉션 목록 조회
curl http://localhost:8000/sync/collections

📋 주요 엔드포인트

GitHub API

• GET /github/issues - Issues 목록 조회
• GET /github/issues/{issue_number} - 특정 Issue 조회
• GET /github/pull-requests - Pull Requests 목록 조회
• GET /github/pull-requests/{pr_number} - 특정 PR 조회

동기화 API

• POST /sync/github-to-outline - 전체 동기화
• POST /sync/issue/{issue_number} - 단일 Issue 동기화
• POST /sync/pull-request/{pr_number} - 단일 PR 동기화
• GET /sync/status - 동기화 서비스 상태

관리 API

• GET /health - 헬스 체크
• GET /info - 애플리케이션 정보
• POST /sync/validate-settings - 설정 검증

🏗️ 아키텍처

레이어 구조

1. Controller Layer: HTTP 요청/응답 처리
2. Service Layer: 비즈니스 로직 구현
3. Repository Layer: 외부 API 호출 (GitHub, Outline)
4. DTO Layer: 데이터 전송 객체 정의
5. Utils Layer: 공통 유틸리티 함수

데이터 플로우

GitHub API → Repository → Service → Controller → API Response
                    ↓
            Outline API ← Repository ← Service

🔒 보안 고려사항

• 모든 API 토큰은 환경 변수로 관리
• .env 파일은 절대 버전 관리에 포함하지 않음
• HTTPS 사용 권장 (프로덕션 환경)
• API 요청 시 적절한 timeout 설정

🐛 트러블슈팅

일반적인 문제들

1. API 토큰 오류

   # 설정 검증으로 확인
   curl -X POST http://localhost:8000/sync/validate-settings

2. Outline 연결 오류

   # 연결 테스트
   curl -X POST http://localhost:8000/sync/test-outline-connection

3. GitHub API 레이트 리밋

   • Personal Access Token 사용 시 시간당 5,000 요청 제한
   • limit 파라미터로 요청 수 조절

로그 확인

로그 레벨을 DEBUG로 설정하여 상세한 로그 확인:

LOG_LEVEL=DEBUG
DEBUG=True

🤝 기여하기

1. 이슈 리포트나 기능 제안은 GitHub Issues를 통해
2. Pull Request는 언제나 환영합니다
3. 코드 스타일: Black + isort 사용 권장

📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다.

📞 지원

문제가 발생하거나 질문이 있으시면:

• GitHub Issues에 문의
• 개발팀 내부 채널 활용

---

Gopedia Synapse - GitHub와 Outline을 연결하는 똑똑한 동기화 서비스 🚀