title: Vercel 배포 전략 + Git 브랜치 전략 제안서 date: 2026-02-25T20:45:00+09:00 type: strategy layer: L0 status: draft tags: [vercel, git-branch, deployment, ci-cd] author: self-healing-impl-pl project: infra reviewed_by: "jarvis" reviewed_at: "2026-02-25T23:15:00+09:00" approved_by: "" approved_at: ""

Vercel 배포 전략 + Git 브랜치 전략 제안서

1. 현황 분석

1-1. 현재 문제

1-2. 대상 프로젝트 현황

1-3. Vercel 플랜 비교

핵심: 상업적 프로젝트(apppro.kr, richbukae.com, koreaaihub.kr)는 Pro 플랜 필수. 내부 도구(kanban, content-orchestration)만 Hobby 허용.

2. Git 브랜치 전략 제안

2-1. 전략 비교

2-2. 추천: B안 — main/production 분리 (Modified GitHub Flow)

AI 1인 기업에 최적화된 2-브랜치 전략.

main (개발 브랜치)
  │
  │ ← AI 에이전트(자비스/PL) 커밋
  │ ← 개발자 직접 커밋
  │ ← feature 브랜치 merge
  │
  │    Vercel: Preview 배포 (자동)
  │    URL: *.vercel.app (Preview)
  │
  ├─── PR merge ───→ production (프로덕션 브랜치)
  │                      │
  │                      │    Vercel: Production 배포 (자동)
  │                      │    URL: 커스텀 도메인 (apppro.kr 등)
  │                      │
  │                      └─── CEO/VP 승인 후에만 merge
  │
  └─── feature/* (선택적)
       └─── 큰 기능 개발 시 사용, main으로 PR

핵심 원칙:

1. AI 에이전트는 main에만 push → production에 직접 push 금지
2. main → production merge는 CEO/VP 승인 후에만 (GitHub PR + Branch Protection)
3. production 브랜치 = Vercel Production Branch → 커스텀 도메인 연결
4. main 브랜치 = Vercel Preview → *.vercel.app Preview URL로 검수

2-3. 브랜치 역할 정의

3. 프로젝트별 적용 계획

3-1. content-pipeline (migkjy/ai-blog)

현재: main + phase1-mvp 브랜치, Vercel에 content-pipeline-sage + content-orchestration 2개 프로젝트 연결

적용 후:
  main         → Vercel Preview (content-pipeline-sage.vercel.app)
  production   → Vercel Production (blog.apppro.kr 도메인 연결 시)

  content-orchestration은 동일 레포의 별도 Vercel 프로젝트이므로:
  main         → content-orchestration Preview
  production   → content-orchestration Production (content-orchestration.vercel.app)

vercel.json 추가 설정:

{
  "git": {
    "deploymentEnabled": {
      "main": true,
      "production": true,
      "phase1-mvp": false
    }
  },
  "crons": [
    { "path": "/api/cron/publish", "schedule": "0 21 * * *" },
    { "path": "/api/cron/pipeline", "schedule": "0 21 * * 1-5" }
  ]
}

주의: phase1-mvp는 개발 완료된 브랜치이므로 배포 비활성화. main으로 merge 후 삭제 권장.

3-2. apppro-kr (migkjy/apppro.kr-)

현재: master 단일 브랜치

적용 후:
  master (→ main 이름 변경 권장) → Vercel Preview
  production                     → Vercel Production (apppro.kr)

작업 순서:

1. GitHub에서 기본 브랜치를 main으로 변경 (master → main rename)
2. production 브랜치 생성 (main 기준)
3. Vercel Project Settings → Production Branch: production 설정
4. 도메인 apppro.kr, www.apppro.kr → production 브랜치 연결
5. GitHub Branch Protection Rule: production에 PR 필수 + 최소 1 approval

3-3. richbukae-store (migkjy/richbukae-store)

현재: master 단일 브랜치

적용 후:
  master (→ main 이름 변경 권장) → Vercel Preview
  production                     → Vercel Production (richbukae.com)

동일한 작업 순서 적용. Toss 결제 연동 등 민감한 기능이 있으므로 production 분리 특히 중요.

3-4. kanban-dashboard (business-builder 모노레포 내부)

현재: business-builder 레포의 main 브랜치, Vercel 별도 프로젝트

특이사항: business-builder는 모노레포 (kanban-dashboard는 projects/ 하위)
→ Vercel Root Directory 설정으로 projects/kanban-dashboard/ 지정

적용 후:
  main         → Vercel Preview (business-builder-kanban.vercel.app)
  production   → Vercel Production (도메인 연결 시)

주의: business-builder 레포에는 AI 에이전트 커밋이 매우 빈번함 (지침/스킬/메모리 등). kanban-dashboard 외 파일 변경 시 불필요한 배포가 트리거됨. → ignoreCommand 필수.

vercel.json 추가:

{
  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- projects/kanban-dashboard/",
  "crons": [
    { "path": "/api/okr/check", "schedule": "0 9 * * *" }
  ]
}

이렇게 하면 projects/kanban-dashboard/ 디렉토리에 변경이 없는 커밋은 배포를 건너뛴다.

3-5. koreaaihub.kr (향후)

신규 프로젝트이므로 처음부터 main/production 구조로 생성:

1. GitHub 레포 생성 시 기본 브랜치 = main
2. 첫 배포 전에 production 브랜치 생성
3. Vercel Production Branch = production
4. 도메인 koreaaihub.kr → production 연결

4. 불필요한 배포 줄이기

4-1. vercel.json ignoreCommand

ignoreCommand는 빌드 전에 실행되어, exit code 0이면 배포 건너뜀, 1이면 빌드 진행.

프로젝트별 설정:

4-2. git.deploymentEnabled 설정

Preview 배포를 특정 브랜치에서만 허용.

// vercel.json
{
  "git": {
    "deploymentEnabled": {
      "main": true,
      "production": true,
      "feature/*": false
    }
  }
}

제한사항: Vercel은 deploymentEnabled에서 와일드카드(feature/*)를 지원하지 않음. 대신 ignoreCommand에서 브랜치 이름을 체크하는 스크립트를 사용해야 함.

대안 — 브랜치별 배포 제어 스크립트:

#!/bin/bash
# scripts/should-deploy.sh
# Vercel ignoreCommand에서 호출

BRANCH=$(git rev-parse --abbrev-ref HEAD)

# production과 main만 배포 허용
if [ "$BRANCH" = "production" ] || [ "$BRANCH" = "main" ]; then
  exit 1  # 빌드 진행
else
  exit 0  # 빌드 건너뜀
fi

// vercel.json
{
  "ignoreCommand": "bash scripts/should-deploy.sh"
}

4-3. .vercelignore 파일

빌드 시 불필요한 파일을 제외하여 빌드 속도 향상 (배포 횟수와는 무관하지만, 빌드 실패 방지).

# .vercelignore
.claude/
memory/
docs/
scripts/
*.md
!README.md

4-4. GitHub Branch Protection Rules

production 브랜치 보호:

• Require pull request before merging: ON
• Require approvals: 1 (CEO or VP)
• Require status checks to pass: ON (Vercel Preview 빌드 성공)
• Restrict pushes: CEO/VP GitHub 계정만 직접 push 가능
• Do not allow force pushes: ON
• Do not allow deletions: ON

main 브랜치 보호 (선택적):

• AI 에이전트 push 허용 (현재 운영 방식 유지)
• 단, --force-push 금지

5. CI/CD 파이프라인 설계

5-1. 전체 플로우

[1] AI 에이전트 / 개발자
    │
    │ git push origin main
    │
    ↓
[2] GitHub main 브랜치
    │
    │ Webhook → Vercel
    │
    ↓
[3] Vercel Preview 배포 (자동)
    │
    │ Preview URL: https://{project}-{hash}.vercel.app
    │
    ↓
[4] CEO/VP 검수
    │
    │ Preview URL에서 테스트
    │ QA 체크리스트 확인
    │
    ↓
[5] GitHub PR 생성 (main → production)
    │
    │ PR Description: 변경 사항 요약
    │ Vercel: PR에 Preview 배포 링크 자동 코멘트 (Pro 플랜)
    │
    ↓
[6] PR Merge (Squash & Merge 권장)
    │
    │ CEO/VP가 "Merge pull request" 클릭
    │
    ↓
[7] Vercel Production 배포 (자동)
    │
    │ 커스텀 도메인 (apppro.kr 등) 즉시 반영
    │
    ↓
[8] 배포 완료
    │
    └── 자비스가 QA 체크리스트 수행 (선택)

5-2. AI 에이전트 커밋이 실서비스에 바로 반영 안 되는 메커니즘

3중 안전장치:

AI 에이전트 행동 규칙 (CLAUDE.md에 추가):

### Git Push 규칙
- AI 에이전트(자비스/PL)는 `main` (또는 `master`) 브랜치에만 push한다
- `production` 브랜치에 직접 push 절대 금지
- production 배포는 CEO/VP가 PR merge로만 진행

5-3. 자동화 가능 영역

6. 구현 작업 목록 (우선순위순)

Phase 1: 즉시 적용 (비용 없음)

Phase 2: 브랜치 분리 (CEO 승인 필요)

Phase 3: Pro 플랜 전환 (비용 발생)

비용 영향: 최소 $20/월 (apppro.kr만 Pro), 권장 $40/월 (apppro.kr + richbukae.com Pro)

7. 위험 요소 및 대응

Cron 관련 중요 사항

Vercel Cron은 Production 배포에서만 실행된다. Preview 배포에서는 Cron이 트리거되지 않음.

따라서:

• content-pipeline의 파이프라인 Cron (/api/cron/pipeline, /api/cron/publish)은 production 브랜치가 배포된 후에만 동작
• kanban-dashboard의 OKR 체크 Cron도 동일
• production 브랜치 전환 시 즉시 첫 merge를 해야 Cron이 중단되지 않음

8. 요약: 핵심 제안 3가지

1. main/production 2-브랜치 전략 도입 — AI 에이전트 커밋은 main(Preview)에서 격리, CEO/VP 승인 PR merge로만 production(실서비스) 배포
2. ignoreCommand + deploymentEnabled로 불필요한 배포 80% 감소 — 특히 kanban-dashboard(모노레포)와 content-pipeline(phase1-mvp)에 즉시 적용 가능
3. 상업 프로젝트 Pro 전환 필요 — apppro.kr, richbukae.com은 Vercel ToS상 Hobby 상업적 사용 불가. 최소 $20/월(apppro.kr)부터 전환 권장

리뷰 로그

[자비스 검수] 2026-02-25 23:15

✅ 현황 분석 완비 — 5개 문제점(배포한도 초과/main 직접 배포/AI 에이전트 리스크/Preview 낭비/상업적 사용 위반) 명확히 식별 ✅ 대상 프로젝트 6개 개별 적용 계획 — content-pipeline, apppro-kr, richbukae-store, kanban-dashboard, content-orchestration, koreaaihub(향후) 전부 분석 ✅ 4가지 전략 비교 → B안(main/production 분리) AI 1인 기업 최적 선택. 3중 안전장치 설계 ✅ Phase 3분 구현 계획 — Phase 1(즉시/비용없음 4건) / Phase 2(CEO승인 4건) / Phase 3(비용발생 4건) ✅ 비용 분석 명확 — $20/월(apppro.kr만) ~ $40/월(+richbukae.com) 옵션 제시 ✅ Cron 주의사항 명시 — Production에서만 실행, 브랜치 전환 후 즉시 첫 merge 필수 ✅ ignoreCommand 와일드카드 미지원 제한 명시 + should-deploy.sh 스크립트 대안 제공 ✅ CLAUDE.md AI 에이전트 push 규칙 추가 제안 + 규칙 텍스트 포함 ✅ 위험 요소 5개 + 대응 방안 (특히 Hobby 상업적 사용 적발 중간 확률) ✅ kanban-dashboard ignoreCommand — 모노레포에서 kanban 외 변경 시 skip (배포 80%+ 감소 효과 큼) 검수 결론: 10항목 전부 ✅. VP 즉시 승인 가능. Phase 1은 CEO 승인 없이 자비스가 즉시 적용 가능 (비용 없음)

[self-healing-impl-pl 초안 작성] 2026-02-25 20:45

• Vercel Hobby/Pro 플랜 비교 + 상업적 사용 제한 정리
• Git 브랜치 전략 4가지 비교 → B안(main/production 분리) 추천
• 대상 프로젝트 5개 + 향후 1개 개별 적용 계획 수립
• 불필요한 배포 줄이는 4가지 방법: ignoreCommand, deploymentEnabled, .vercelignore, Branch Protection
• CI/CD 파이프라인 8단계 설계 + AI 에이전트 3중 안전장치
• 구현 작업 12개를 3개 Phase로 분류 (즉시/CEO승인/비용발생)
• Cron은 Production에서만 실행되는 점 주의사항 명시
• 자비스 검수 요청