Spective 핸드오프

Appearance

5. 배포 & 릴리스 ​

코드가 어떻게 dev/prod로 나가는지, 무엇이 트리거인지, 문제 시 어떻게 되돌리는지.

5.1 브랜치 · 커밋 · 릴리스 흐름 ​

  • Conventional Commits (한국어) — commitlint + husky로 검증. (standards:commit-convention)
  • release-please: main 머지 누적 → 자동 릴리스 PR 생성 → 머지 시 버전 태그 + GitHub Release 발행 + CHANGELOG.md 갱신.
  • 출처: .github/workflows/release-please.yml, release-please-config.json, .release-please-manifest.json

5.2 CI (모든 PR / main push) ​

.github/workflows/ci.yml — self-hosted 러너(aws)에서 mise로 Node/Bun 설치 후:

Job명령비고
lintbun run lintESLint 캐시 복원
testbun run test단위 테스트
test-integrationbun run test:integrationtestcontainers (TESTCONTAINERS_RYUK_DISABLED=true)
e2ebun run e2e현재 if: false로 비활성화
  • CHANGELOG.md / .release-please-manifest.json 변경은 CI 스킵(paths-ignore).

5.3 dev 자동 배포 ​

.github/workflows/deploy-dev.yml

  • 트리거: main push 중 apps/web/**, packages/**, package.json, bun.lock 변경 시 (또는 수동 workflow_dispatch)
  • 동시성: deploy-dev-<ref>, 진행 중 취소함(cancel-in-progress: true)
  • 파이프라인: AWS OIDC 인증 → bun install → turbo build:cloudrun:dev → db:migrate:deploy:dev → GCP 인증 → Docker build/push(dev-<sha>) → Cloud Run deploy(min=0, max=3) → Firebase Hosting deploy
  • 이미지 캐시: S3 (spective-web-dev)

5.4 prod 배포 ​

.github/workflows/deploy-prod.yml

  • 트리거: GitHub release published (긴급 시 workflow_dispatch + confirm=true 필수)
  • 동시성: deploy-prod, 진행 중 취소 안 함(cancel-in-progress: false)
  • 파이프라인: dev와 동일 구조, 단 db:migrate:deploy(prod), 이미지 태그 <release_tag|sha>, Cloud Run min=1/max=10
  • 빌드 명령: turbo run build:cloudrun --filter=web

5.5 CI/배포 인프라 의존성 ​

  • self-hosted 러너: RunsOn (AWS). 배포 잡 라벨 [self-hosted, linux, x64, ubuntu-2404, aws, xlarge]
  • 캐시: Turbo remote cache(TURBO_TOKEN/TURBO_TEAM), Docker S3 캐시(RUNS_ON_S3_BUCKET_CACHE), bun 캐시
  • 필요 GitHub Secrets (이름 / 용도):
Secret용도
AWS_ROLE_TO_ASSUMEself-hosted 러너 OIDC
FIREBASE_SERVICE_ACCOUNT_SPECTIVE_DEV / _PRODGCP 인증
DOTENV_PRIVATE_KEY_SECRETS_DEVELOPMENT / _PRODUCTIONdotenvx 복호화
TURBO_TOKEN / TURBO_TEAMTurbo remote cache
RUNS_ON_S3_BUCKET_CACHEDocker 빌드 캐시
  • Secrets 발급·갱신: 위 Secrets는 이전되지 않으며, 인수 측이 자체 환경에서 신규 발급합니다 (상세: §7.3).

5.6 롤백 절차 ​

현 담당자(이민수) 확인 기준:

애플리케이션 (Cloud Run) ​

  • 이전 리비전으로 트래픽 되돌리기가 기본 롤백 방법.
bash
# 리비전 목록 확인
gcloud run revisions list --service=spective-web --region=asia-northeast3 --project=spective-prod
# 직전 정상 리비전으로 트래픽 100% 전환
gcloud run services update-traffic spective-web \
  --to-revisions=<REVISION>=100 --region=asia-northeast3 --project=spective-prod

데이터베이스 (Prisma 마이그레이션) ​

  • 담당자 방침: 마이그레이션 down으로 되돌림.
  • ⚠️ 주의: Prisma 7에는 자동 down 마이그레이션이 없습니다. 실무상 다음 중 하나로 처리:
    • 포워드 수정 마이그레이션 작성 (권장 — 운영 안전)
    • db:execute로 수동 보정 SQL 실행 + db:resolve로 마이그레이션 상태 정리
    • dev 한정: db:reset(파괴적, prod 금지)
  • 권장 절차 — 포워드 수정 마이그레이션 (운영 안전, 다운타임 없음):
    1. 잘못된 스키마를 되돌리는 새 마이그레이션 생성: cd apps/web && bun run db:migrate:new <revert_xxx> (--create-only)
    2. 생성된 SQL에 역방향 변경 작성 → bun run db:migrate:deploy로 prod 적용
  • 긴급 수동 보정 (마이그레이션 이력이 깨진 경우):
    bash
    cd apps/web
bun run db:execute --file ./fix.sql        # 보정 SQL 직접 실행
bun run db:resolve --rolled-back <name>     # 실패 마이그레이션을 rolled-back 처리
# 또는 --applied <name> 으로 적용 완료 표시
  • ⚠️ db:reset은 전체 삭제 — dev 전용, prod 절대 금지.
  • 인계 시 위 절차를 실제 1회 리허설 권장 (운영 절차 확정).

Firebase Hosting ​

  • 공식 문서 기준 콘솔에서 이전 릴리스로 롤백, 또는 직전 빌드 재배포.

배포 실패 ​

  • 흔한 실패 케이스: 특이사항 없음(담당자 답변). 발생 시 6.3 장애 플레이북 절차를 따름.