zellyy-finance/docs/ci-cd-setup-guide.md

# CI/CD 파이프라인 설정 가이드

## 개요

Zellyy Finance 프로젝트는 GitHub Actions를 사용하여 완전히 자동화된 CI/CD 파이프라인을 구축했습니다. 이 가이드는 파이프라인 설정과 사용 방법을 설명합니다.

## 파이프라인 구조

### 워크플로우 흐름
```
코드 푸시 → 테스트 → 웹 빌드 → 모바일 빌드 → 릴리즈 → 앱스토어 배포
```

### 지원 플랫폼
- **Web**: Vercel 배포 (별도 워크플로우)
- **Android**: Google Play Store (AAB/APK)
- **iOS**: App Store Connect / TestFlight (IPA)

## GitHub Secrets 설정

### 1. Android 관련 Secrets

| Secret 이름 | 설명 | 생성 방법 |
|-------------|------|-----------|
| `ANDROID_KEYSTORE_BASE64` | 키스토어 파일 (base64) | `base64 -i release.keystore \| pbcopy` |
| `ANDROID_KEYSTORE_PASSWORD` | 키스토어 비밀번호 | 키스토어 생성 시 설정한 비밀번호 |
| `ANDROID_KEY_PASSWORD` | 키 비밀번호 | 키 생성 시 설정한 비밀번호 |
| `ANDROID_KEY_ALIAS` | 키 별칭 | 기본값: `zellyy-finance-key` |

### 2. iOS 관련 Secrets

| Secret 이름 | 설명 | 생성 방법 |
|-------------|------|-----------|
| `IOS_CERTIFICATES_P12_BASE64` | 배포 인증서 (base64) | Keychain에서 P12로 내보내기 후 base64 변환 |
| `IOS_CERTIFICATES_P12_PASSWORD` | P12 파일 비밀번호 | P12 내보내기 시 설정한 비밀번호 |
| `APPSTORE_ISSUER_ID` | App Store Connect API 발급자 ID | App Store Connect > API 키 생성 |
| `APPSTORE_KEY_ID` | App Store Connect API 키 ID | API 키 생성 시 표시되는 키 ID |
| `APPSTORE_PRIVATE_KEY` | App Store Connect API 개인 키 | .p8 파일 내용 전체 |

### 3. Google Play Store Secrets

| Secret 이름 | 설명 | 생성 방법 |
|-------------|------|-----------|
| `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` | 서비스 계정 JSON | Google Cloud Console에서 서비스 계정 키 생성 |

### 4. 앱 환경 변수 Secrets

| Secret 이름 | 설명 |
|-------------|------|
| `VITE_SUPABASE_URL` | Supabase 프로젝트 URL |
| `VITE_SUPABASE_ANON_KEY` | Supabase Anonymous Key |
| `VITE_CLERK_PUBLISHABLE_KEY` | Clerk Publishable Key |
| `VITE_SENTRY_DSN` | Sentry DSN |

## 워크플로우 트리거 조건

### 자동 트리거
- **PR 생성/업데이트**: 테스트 + 디버그 빌드만 실행
- **main 브랜치 푸시**: 전체 파이프라인 실행 (릴리즈 빌드 + 배포)
- **태그 푸시** (`v*`): 전체 파이프라인 실행

### 수동 트리거
GitHub Actions 탭에서 `workflow_dispatch` 이벤트로 수동 실행 가능

## 빌드 환경별 설정

### Development 환경
```bash
npm run build:dev
# - 앱 이름: Zellyy Finance (Dev)
# - 앱 ID: com.zellyy.finance.dev
# - 배경색: 노란색 톤 (#FEF3C7)
```

### Staging 환경
```bash
npm run build:staging
# - 앱 이름: Zellyy Finance (Beta)
# - 앱 ID: com.zellyy.finance.beta
# - 배경색: 파란색 톤 (#DBEAFE)
```

### Production 환경
```bash
npm run build:prod
# - 앱 이름: Zellyy Finance
# - 앱 ID: com.zellyy.finance
# - 배경색: 기본색 (#F8FAFC)
```

## 로컬 테스트

### 1. 디버그 키스토어 생성
```bash
npm run keystore:debug
```

### 2. 빌드 파이프라인 테스트
```bash
npm run pipeline:test
```

### 3. 단계별 테스트
```bash
# 빌드 검증
npm run pipeline:validate

# 모바일 빌드
npm run mobile:build

# Android 디버그 빌드
cd android && ./gradlew assembleDebug

# iOS 디버그 빌드 (macOS만)
npm run ios:open
```

## 버전 관리 자동화

### Semantic Release 구성
- **feat**: Minor 버전 증가 (1.0.0 → 1.1.0)
- **fix**: Patch 버전 증가 (1.0.0 → 1.0.1)
- **BREAKING CHANGE**: Major 버전 증가 (1.0.0 → 2.0.0)

### 커밋 메시지 규칙
```bash
# 새 기능
git commit -m "feat: 거래 내역 필터링 기능 추가"

# 버그 수정
git commit -m "fix: 로그인 에러 수정"

# 중대한 변경
git commit -m "feat!: 데이터베이스 스키마 변경

BREAKING CHANGE: 기존 데이터와 호환되지 않음"
```

### 자동 버전 동기화
```bash
# package.json → Android/iOS 버전 동기화
npm run version:sync
```

## 배포 프로세스

### 1. 개발 → 배포 흐름
```
1. 기능 개발 (feature branch)
2. PR 생성 → 자동 테스트 실행
3. main 브랜치 머지 → 자동 릴리즈 빌드
4. Semantic Release → 버전 태그 생성
5. 앱스토어 자동 업로드
```

### 2. Google Play Store 배포
- **트랙**: Internal Testing (내부 테스트)
- **파일 형식**: AAB (Android App Bundle)
- **자동 업로드**: main 브랜치 빌드 시

### 3. App Store / TestFlight 배포
- **트랙**: TestFlight (베타 테스트)
- **파일 형식**: IPA
- **자동 업로드**: main 브랜치 빌드 시

## 모니터링 및 알림

### 빌드 상태 확인
- GitHub Actions 탭에서 실시간 빌드 상태 확인
- 이메일 알림 (빌드 실패 시)
- Slack 연동 (선택사항)

### 아티팩트 관리
- **보관 기간**: 90일
- **다운로드**: GitHub Actions Artifacts 섹션
- **크기 제한**: 2GB per artifact

## 보안 고려사항

### Secrets 관리
- GitHub Secrets 사용으로 민감 정보 보호
- 환경별 Secret 분리
- 정기적인 키 로테이션

### 빌드 보안
- 서명된 릴리즈 빌드만 배포
- 소스맵 업로드 (Sentry)
- 의존성 보안 스캔

## 문제 해결

### 일반적인 빌드 오류

#### Android 빌드 실패
```bash
# 키스토어 관련 오류
Error: Keystore file not found
→ Solution: ANDROID_KEYSTORE_BASE64 Secret 확인

# 버전 충돌
Error: Version conflict
→ Solution: android/app/build.gradle 버전 확인
```

#### iOS 빌드 실패
```bash
# 인증서 오류
Error: Code signing failed
→ Solution: IOS_CERTIFICATES_P12_BASE64 Secret 확인

# 프로비저닝 프로파일 오류
Error: No matching provisioning profile
→ Solution: Apple Developer Portal에서 프로파일 확인
```

#### 환경 변수 오류
```bash
# Undefined environment variable
Error: VITE_SUPABASE_URL is not defined
→ Solution: GitHub Secrets에 모든 필수 환경 변수 설정
```

### 디버깅 도구

#### 로컬 디버깅
```bash
# 빌드 로그 상세 출력
npm run android:build -- --info

# 키스토어 정보 확인
npm run keystore:info

# 의존성 확인
npm audit
```

#### CI 디버깅
```bash
# GitHub Actions 로그 다운로드
gh run download [run-id]

# 특정 job 재실행
gh workflow run mobile-build.yml
```

## 성능 최적화

### 빌드 시간 단축
- 의존성 캐싱 활성화
- 병렬 빌드 사용
- 불필요한 단계 제거

### 아티팩트 크기 최적화
- Tree shaking 활성화
- Code splitting 적용
- 이미지 압축

## 확장 계획

### 추가 예정 기능
- Slack 알림 연동
- 자동 스크린샷 테스트
- E2E 테스트 자동화
- 성능 벤치마크 자동화

### 다중 환경 지원
- Staging 환경 자동 배포
- Feature branch 미리보기
- A/B 테스트 지원

---

이 문서는 Zellyy Finance CI/CD 파이프라인의 완전한 가이드입니다. 추가 질문이나 문제가 있으면 개발팀에 문의하세요.