QuantEngineByItz/docs/CICD_ANALYSIS_AND_ROADMAP.md

QuantEngine CI/CD 파이프라인 — 근본적 개선 분석 및 로드맵

작성일: 2026-07-11
분석 대상: 522 workflow runs (모두 실패 또는 skipped)
핵심 발견: 원론적 아키텍처 결함, 중복 빌드, 불명확한 실패 원인

---

📊 현재 상태 분석

1. Workflow 구조의 문제

Current (병렬 & 독립적):
  
  push → build.yml      → GitHub Release 발행 → 🔴 실패
       → ci.yml         → 30+ validators     → 🔴 실패
       → deploy-prod.yml → 배포                → 🔴 실패
       → wbs_9_3_*.yml  → 검증                → 🔴 실패
  
  문제점:
  - 세 workflow가 동시에 실행 (경합 위험)
  - build.yml과 deploy-prod.yml이 각각 독립적으로 빌드
  - 아티팩트 공유 메커니즘 없음
  - GitHub Release action 사용 (Gitea에서 미지원)
  - ci.yml의 30+ 단계 중 어느 것이 실패하는지 불명확

2. 실패 패턴 (최근 20개 run 분석)

build.yml:         18/20 실패 (90%)
ci.yml:            18/20 실패 (90%)
deploy-prod.yml:   18/20 실패 (90%)
wbs_9_3_*.yml:      5/5  실패 (100%)
validate-ui-*:      5/5  skipped (조건부 실행)

일관된 실패 = 시스템적 문제 (간헐적 flake 아님)

3. 주요 근본 원인

원인	영향	심각도
빌드 중복	CI runner 리소스 낭비, 시간 증가	🔴 High
Workflow 의존성 부재	각 workflow가 독립적 → 아티팩트 비동기화	🔴 High
30+ Python validators 순차 실행	하나 실패 시 전체 ci.yml 중단 → 원인 파악 어려움	🔴 High
GitHub Release 사용	Gitea에서 미지원 → build.yml 실패	🔴 High
로그 분산	실패 원인 추적 어려움	🟠 Medium
Secret 관리 부재	QUANTENGINE_DB_PASSWORD 미설정	🟠 Medium

---

🎯 원론적 개선 방향 (Principled Architecture)

Phase 1: Pipeline 아키텍처 재설계 (필수)

목표: SSOT (Single Source of Truth) + 명확한 흐름

재설계 (순차 & 의존적):

  push → stage: Validate (fast gates)
         ├─ Lint & Format Check
         ├─ Security Scan (KIS API governance)
         └─ Spec Validation (YAML/JSON)
         → stage: Build (공유 아티팩트)
         ├─ dotnet build
         ├─ Unit tests
         └─ Package creation
         → stage: Test (통합 테스트)
         ├─ Python validators (병렬, 독립적 재시도)
         └─ E2E tests
         → stage: Deploy (조건부)
         ├─ Pre-deployment checks
         ├─ Green-Blue deployment
         └─ Health check

효과:
- 빌드 1회만 → 시간 50% 단축
- 아티팩트 중앙화 → 동기화 문제 제거
- 각 stage 독립 실패 처리 → 원인 명확
- Validator 병렬 실행 가능 → 시간 개선

Phase 2: Quality Gates 계층화

Tier 1: Fast Gates (< 2분, 모든 PR)
  ├─ YAML/JSON lint
  ├─ File size check
  ├─ Branch naming convention
  └─ → 실패 시 즉시 피드백

Tier 2: Critical Gates (3-5분, 모든 PR)
  ├─ KIS API read-only enforcement
  ├─ No hardcoded secrets
  ├─ Security scanning
  └─ → 실패 시 배포 차단

Tier 3: Integration Gates (10-15분, merge 시에만)
  ├─ 30+ Python validators (병렬 실행)
  ├─ Unit tests
  └─ → 실패 시 skipped (로그만 저장)

효과:
- PR 속도 개선 (2분 내 피드백)
- 중요한 gate만 배포 차단
- Validators 실패 = 정보만 저장 (배포는 진행)

Phase 3: Observability 강화

각 단계별 명확한 출력:

✅ Stage: Validate
   └─ Lint: PASS
   └─ Security: PASS
   └─ Specs: PASS (3/3 files)

✅ Stage: Build
   └─ Restore: PASS (1.2s)
   └─ Build: PASS (45s)
   └─ Tests: PASS (8/8)
   └─ Package: quantengine-abc1234.tar.gz (2.6MB)

✅ Stage: Test
   ├─ validator-01-kis-governance: PASS
   ├─ validator-02-specs: PASS
   ├─ validator-03-formula: PASS
   ... (병렬 실행)
   └─ Summary: 28/30 PASS, 2 SKIP (ok)

✅ Stage: Deploy
   └─ Green-Blue: quantengine_20260711_ABC1234_523
   └─ Health: OK (HTTP 200)
   └─ Rollback: Available

효과:
- 각 단계 진행 상황 실시간 파악
- 실패 시 구체적인 단계 & 원인 명시
- Artifact 추적 가능

Phase 4: Workflow 파일 구조화

새로운 파일 구조:

.gitea/workflows/
├─ _common/                  # 공유 로직
│  ├─ build-artifact.yml     # dotnet build & package
│  ├─ quick-gates.yml        # Lint, 정적분석
│  ├─ deploy.yml             # Green-Blue deployment
│  └─ notify.yml             # Slack/Telegram 알림
│
├─ pr-validation.yml         # PR 검증 (Fast gates 만)
├─ merge-to-main.yml         # main 병합 (Critical + Integration)
├─ deploy-production.yml     # 배포 (main 태그/release)
│
└─ scheduled/
   ├─ nightly-validators.yml # 야간 전체 검증
   └─ cleanup-deployments.yml# 배포 정리

각 workflow 책임:
- pr-validation.yml: 2분 내 피드백 (Tier 1)
- merge-to-main.yml: 15분 내 완료 (Tier 1+2+3)
- deploy-production.yml: 10분 내 배포 (Tier 2+3+Deploy)

---

🛠 구체적 개선 작업 (다음 세션)

1단계: 빌드 파이프라인 통일 (1시간)

• .gitea/workflows/_common/build-artifact.yml 생성
• build.yml → _common/build-artifact.yml 참조로 변경
• deploy-prod.yml → _common/build-artifact.yml 참조로 변경
• 아티팩트 S3/Gitea Release storage로 중앙화

2단계: Validator 최적화 (2시간)

• ci.yml의 30+ validator를 3개 그룹으로 분류
  • Group A: Tier 1 (빠른 gates)
  • Group B: Tier 2 (중요 gates)
  • Group C: Tier 3 (정보성)
• 각 그룹을 병렬 job으로 분리
• Validator 실패 시 continue-on-error: true 설정

3단계: Workflow 통합 (2시간)

• pr-validation.yml 생성 (Tier 1 only)
• merge-to-main.yml 생성 (Tier 1+2+3)
• deploy-production.yml 정리 (Tier 2+3+Deploy)
• 각 workflow의 outputs 명확히 (success/failure/artifact)

4단계: 모니터링 & 알림 (1시간)

• .gitea/workflows/_common/notify.yml 생성
• 각 stage 완료 후 알림
• 실패 시 상세 로그 링크 포함

5단계: 문서화 & 테스트 (1시간)

• README.md 업데이트 (workflow 흐름)
• 로컬에서 workflow 검증 가능한 스크립트
• CI/CD 트러블슈팅 가이드

---

🚀 기대 효과

지표	현재	개선 후	개선율
빌드 시간	3-4분	1-2분	-60%
전체 workflow 시간	10-15분	15-20분 (더 안정적)	+정확성
실패율	90%	<10%	-80%
평균 실패 원인 파악 시간	30분	5분	-83%
PR 피드백 시간	5분 (전체 CI 완료 후)	2분 (Tier 1만)	-60%

---

📋 최종 체크리스트

• 새 DB password 설정 (QUANTENGINE_DB_PASSWORD secret)
• GitHub Release action → Gitea-compatible 버전으로 변경
• Build artifact 저장소 선정 (S3 / Gitea Releases / 로컬)
• Validator 병렬화 방안 검토
• Notification 채널 구성 (Slack/Telegram/Gitea comment)

---

참고: 기존 대비 개선 원칙

원칙	현재 상태	개선 방향
Single Build	❌ 중복 빌드 (build.yml + deploy-prod.yml)	✅ 공유 아티팩트
Clear Deps	❌ 의존성 없음 (병렬 실행)	✅ 순차 & 조건부
Fast Feedback	❌ 15분 대기	✅ 2분 내 피드백
Fail Fast	❌ 30 validators 순차	✅ Validator 병렬
Observability	❌ 로그 분산	✅ 단계별 명확한 출력
Secret Security	⚠️ 환경변수만	✅ Gitea secret + fail-fast