14. 배포 프로세스 체크리스트

0. 먼저 알고 가기 (30초 요약)

• 배포는 “준비-승인-실행-확인-복구” 순서에서만 움직입니다.
• 카나리아/점진 배포로 리스크를 쪼개고 문제를 조기에 잡으세요.
• 체크리스트를 누락 없이 통과해야만 다음 단계로 넘어가는 구조로 만드세요.

초심자용 한눈에 보기

배포는 준비-검증-승인-출시-회복(롤백)의 순서가 핵심입니다.

일상 비유: 우편 배달과 같습니다. 분류(빌드/검증) -> 차량 적재(아티팩트) -> 일부 지역 시범 배달(canary) -> 전 지역 배달(릴리스) -> 반송 처리(롤백) 순서가 흔들리면 잘못된 우편이 모든 집에 한꺼번에 도착합니다.

핵심 용어 빠르게 정리

deploy와 release 분리 한눈에 보기

왜 중요한가: deploy와 release를 같이 두면 "노출 직후 발견된 결함" 때문에 전체 롤백이 강제됩니다. 분리하면 코드는 그대로 두고 노출만 끌 수 있습니다.

flowchart LR
  subgraph DEPLOY["Deploy (배포)"]
    D1["artifact 환경에 올림"]
    D2["검증/smoke 통과"]
  end
  subgraph RELEASE["Release (노출)"]
    R1["feature flag ON"]
    R2["canary 확대"]
    R3["전체 사용자 공개"]
  end
  DEPLOY --> RELEASE
  R3 -. 문제 발생 .-> Kill["flag OFF\n(코드 재배포 불필요)"]

---

배포는 파일을 서버에 올리는 작업이 아니라 검증된 artifact를 안전하게 사용자에게 노출하고, 문제가 생기면 빠르게 되돌리는 운영 절차입니다.

---

추천 항목 (실무 우선순위)

• 시작 추천: release 전 5단계 체크(빌드, 테스트, 보안, 모니터링, 롤백 준비)를 정형화하세요.
• 안정 추천: 카나리아는 기능 단위로 좁게 시작해 이슈 전파 범위를 제한하세요.
• 운영 추천: 각 배포에 대한 승인 근거와 롤백 근거를 템플릿으로 남깁니다.

추천 항목 고도화 체크

• 첫 적용 — canary, flag, rollback artifact, release health 중 하나를 실제 PR이나 운영 이슈에 붙이고, 변경 전 기준을 먼저 적는다.
• 증거 정리 — release note, deployment log, rollback artifact, health dashboard를 같은 작업 기록에 남긴다.
• 재점검 — rollback 시간, canary error rate, release failure 수가 나아졌는지 30일 안에 확인하고 기준을 유지, 수정, 폐기 중 하나로 판정한다.

추천 항목 실행 기록 템플릿

• 작업 : canary, flag, rollback artifact, release health 적용 범위를 어느 화면, 패키지, 문서에 둘지 적는다.
• 증거 : release note, deployment log, rollback artifact, health dashboard 중 실제로 남긴 항목만 링크한다.
• 판정 : 유지/수정/폐기 중 하나와 이유를 한 문장으로 남긴다.
• 다음 점검 : rollback 시간, canary error rate, release failure 수를 다시 볼 날짜와 담당자를 지정한다.

문서 책임 범위

---

0. 모든 프론트엔드 그룹 공통 Baseline

0.0 배포 실행 경로

flowchart TD
  A["배포 대상 변경사항 정리"] --> B["Preflight 체크"]
  B --> C{"Preflight 통과"}
  C -->|미통과| D["수정 후 Recheck"]
  C -->|통과| E["deploy/release 분리 확인"]
  E --> F["Canary / Flag 전략 선택"]
  F --> G["실사용 모니터링"]
  G --> H{"이상 징후"}
  H -->|있음| I["중단 + 완화"]
  H -->|없음| J["release handoff"]
  I --> D
  J --> K["모니터링 위임 + runbook 종료"]

0.1 교차 검증 매트릭스

0.2 운영 게이트

---

0.3 배포 의사결정 지도

배포는 기능 공개 시점과 rollback 비용을 동시에 고려해야 합니다.

배포 단계 책임 맵

빌드 오너   => artifact + checksum 책임
릴리즈 오너 => canary/rollback 판단
관측성     => 모니터링 지표와 dashboard 유지
커뮤니케이션 => 사용자 공지/상태 공유

flowchart TD
  A["변경이 사용자 노출되는가?"] -->|아니오| B["데모/PR 경로"]
  A -->|예| C["deploy/release 분리 점검"]
  C --> D["preflight gate 통과 여부"]
  D -->|미통과| E["롤백/수정 후 게이트 재실행"]
  D -->|통과| F["점진 노출 전략 선택\ncanary / flag / blue-green"]
  F --> G["post-deploy 모니터링"]
  G --> H{"이상 징후?"}
  H -->|yes| I["중단 + 완화 + 재평가"]
  H -->|no| J["release handoff"]

flowchart TD
  A2["빌드 오너"] --> B2["artifact/checksum 책임"]
  C2["릴리즈 오너"] --> D2["canary/rollback 판단"]
  E2["관측성"] --> F2["지표 + dashboard 유지"]
  G2["커뮤니케이션"] --> H2["사용자 공지/상태 공유"]

1. 배포 전 체크리스트

---

2. 배포 전략 선택

일상 비유: 새 다리를 개통할 때 통행을 일부 차량에만 먼저 허용(canary)할지, 옆에 새 다리를 짓고 한번에 통행을 옮길지(blue/green)는 사고 시 우회 비용이 결정합니다.

전략은 조직 문화가 아니라 변경 위험과 복구 가능성에 따라 고릅니다.

2.0 blue/green 전환 흐름

이 그림은 blue 환경에서 green 환경으로 트래픽을 전환하면서 문제가 생기면 즉시 되돌리는 흐름을 보여줍니다.

일상 비유: 호텔이 새 객실 동(green)을 짓고 손님을 받기 전 청소·점검을 마친 뒤 단 한 번의 키 발급 시스템 변경(라우터 스위치)으로 손님을 옮기는 방식입니다. 문제가 생기면 키를 다시 옛 객실 동(blue)으로 돌려주면 됩니다.

flowchart LR
  subgraph BLUE["Blue (현재 운영)"]
    B1[기존 artifact v1]
    B2[100% 트래픽]
  end
  subgraph GREEN["Green (새 release)"]
    G1[새 artifact v2]
    G2[0% 트래픽]
  end
  R[Router/CDN] --> B2
  G1 -. warm-up + smoke .-> S1[smoke 통과]
  S1 --> Cut{스위치 전환}
  Cut -->|성공| R2[Router 100% Green]
  Cut -->|이상 감지| Back[즉시 Blue 복귀]
  R2 --> Hold[Blue 환경 유지\n롤백 대기 창]
  Hold --> Drain[일정 시간 후 Blue 폐기]

2.1 canary 점진 롤아웃 단계

왜 중요한가: 한 번에 100%를 노출하면 문제 영향 범위가 즉시 전체로 퍼집니다. 단계별 확대는 "조기 발견 + 작은 폭발 반경"을 만듭니다.

flowchart LR
  S0["0%\n내부 dogfood"] --> S1["1%\n초기 신호 관측"]
  S1 --> S5["5%\n오류율/지표 확인"]
  S5 --> S25["25%\nCWV/전환율 확인"]
  S25 --> S50["50%\n장시간 안정성"]
  S50 --> S100["100%\nrelease note + handoff"]
  S1 -.->|회귀 감지| Halt["확대 중단\nflag off 또는 rollback"]
  S5 -.->|회귀 감지| Halt
  S25 -.->|회귀 감지| Halt
  S50 -.->|회귀 감지| Halt

---

3. 배포 중 확인

배포 중 이상 징후가 있으면 "원인 분석을 끝낼 때까지 확대 중단"이 기본입니다.

---

4. 롤백 기준

일상 비유: 비행기 조종사의 "go-around" 결정과 비슷합니다. 무리하게 착륙을 강행하기보다 다시 상승해 안전을 확보하는 것이 훈련된 절차입니다. 롤백은 실패가 아니라 설계된 비상 경로입니다.

롤백은 실패가 아니라 준비된 복구 절차입니다. rollback을 어렵게 만드는 schema/cache/auth 변경은 배포 전에 별도 RFC가 필요합니다.

4.1 롤백 의사결정 트리

왜 중요한가: 장애 중에 의사결정 기준이 머릿속에만 있으면 사람마다 판단이 달라집니다. 분기를 미리 정해두면 30분 내에 일관된 결정을 내릴 수 있습니다.

flowchart TD
  Detect[이상 징후 감지] --> Sev{심각도}
  Sev -->|보안/PII 노출| Sec[즉시 노출 차단 + purge + incident]
  Sev -->|핵심 flow 차단| Crit[flag off 시도]
  Sev -->|지표 회귀\nCWV/오류율| Warn[canary 확대 중단]
  Crit --> Q1{flag off로 복구되는가}
  Q1 -->|예| Stab[안정화 후 원인 분석]
  Q1 -->|아니오| RB[artifact rollback]
  RB --> Q2{HTML/asset mismatch}
  Q2 -->|예| Entry[entry 문서 rollback + cache 재검증]
  Q2 -->|아니오| Prev[이전 release로 복귀]
  Warn --> Inv{원인 식별 가능한가}
  Inv -->|예| Fix[hotfix 또는 점진 rollback]
  Inv -->|아니오| Pause[확대 정지 + 모니터링]
  Sec --> Post[postmortem + 재발 방지 액션]
  Stab --> Post
  Entry --> Post
  Prev --> Post
  Fix --> Post

4.2 롤백 실행 시퀀스

비유: 응급실에서 의사가 환자에게 처치할 때 "절차서대로" 움직이는 것과 같습니다. 누가 무엇을 언제 하는지를 평소에 정해두지 않으면 실제 상황에서 늦습니다.

sequenceDiagram
  participant Owner as On-call/Release Owner
  participant Flag as Feature Flag
  participant CDN as CDN
  participant CI as Deploy CI
  participant Mon as Monitoring
  Owner->>Flag: 우선 flag off 시도
  Flag-->>Owner: 영향 범위 축소
  alt flag로 회복되지 않음
    Owner->>CI: 이전 artifact rollback 트리거
    CI->>CDN: entry HTML/manifest 복구
    CI-->>Owner: rollback 완료 이벤트
    Owner->>CDN: 변경 경로 purge
  end
  Owner->>Mon: 지표 회복 확인
  Mon-->>Owner: error/latency/CWV 정상
  Owner->>Owner: postmortem 시작 + release note 갱신

---

5. 배포 후 모니터링

왜 중요한가: "배포 성공"과 "기능 성공"은 다릅니다. 배포 직후 보지 않는 지표는 며칠 뒤에야 문제로 드러나, 원인 추적이 어렵습니다.

monitoring owner는 배포자가 맡되, 장기 운영 지표는 기능 owner에게 인계합니다.

Sentry를 사용하는 배포에서는 28. Sentry 모니터링 활용의 release, source map, trace alert 기준을 이 monitoring window에 연결합니다.

flowchart LR
  T0["0~15분\nerror/crash/blank"] --> T1["15~60분\nCWV/API 실패율/전환"]
  T1 --> T2["1일\n문의/지역·브라우저 이상치/비용"]
  T2 --> T3["1주\n장기 추세/flag 정리/회고"]
  T0 --> O1["배포자가 owner"]
  T3 --> O2["기능 owner에게 handoff"]

---

6. Feature Flag 운영

일상 비유: 전등 스위치를 방마다 다는 것은 편리하지만, 어느 스위치가 어느 방을 켜는지 잊으면 집 전체가 점점 어두워집니다. flag도 owner와 만료일이 없으면 코드 경로가 미로가 됩니다.

flag가 많아지면 코드 경로가 폭발합니다. 임시 flag는 만료일 없이 만들지 않습니다.

이 그림은 flag가 생성·실험·전체 노출·정리로 이동하는 단계별 상태와 전이 조건을 보여줍니다.

stateDiagram-v2
  [*] --> Created: owner + 만료일 설정
  Created --> Internal: dogfood로 검증
  Internal --> Canary: 일부 사용자 노출
  Canary --> Released: 전체 노출 완료
  Canary --> KilledOff: kill switch 발동
  KilledOff --> Created: 원인 수정 후 재시도
  Released --> CleanupPending: 제거 PR 생성 대상
  CleanupPending --> Removed: 코드/설정 정리 완료
  Removed --> [*]

6.1 feature flag 사용 단계

이 그림은 flag를 코드에 도입한 시점부터 사용자에게 전체 노출하고 정리하기까지의 실무 작업 순서를 보여줍니다.

flowchart LR
  P1["1. 정의\nowner+만료+default"] --> P2["2. 코드 머지\noff-default"]
  P2 --> P3["3. 내부 dogfood"]
  P3 --> P4["4. canary 1~5%"]
  P4 --> P5["5. 점진 확대 25~50%"]
  P5 --> P6["6. 100% 안정 운영"]
  P6 --> P7["7. cleanup PR"]
  P4 -. 회귀 .-> KS["kill switch off"]
  P5 -. 회귀 .-> KS
  KS --> P3

---

7. 체크리스트

• [ ] 배포 artifact와 테스트 artifact가 동일한 commit에서 생성되었는가
• [ ] deploy와 release가 분리되어 있는가
• [ ] 변경 위험도와 rollback 난이도가 PR 또는 release note에 적혀 있는가
• [ ] canary 또는 preview에서 핵심 flow가 검증되었는가
• [ ] 배포 후 볼 dashboard와 알림 조건이 준비되어 있는가
• [ ] rollback/flag off/cache purge 절차가 사전에 검증되었는가
• [ ] 배포 완료 후 owner가 30~60분 동안 release health를 확인하는가
• [ ] 임시 feature flag 제거 계획이 있는가

---

8. 제외한 벤더 종속 항목

공통 개발 가이드에는 특정 배포 플랫폼, 특정 progressive delivery 제품, 특정 feature flag SaaS, 특정 알림 도구, 특정 CDN/클라우드 명령을 표준으로 포함하지 않습니다. 이 문서에는 어떤 배포 시스템에서도 유지되어야 하는 사전 검증, 점진 노출, 롤백, 배포 후 관측 기준만 남깁니다.

---

실무 적용 가이드

언제 이 문서를 펼칠까

• 배포와 기능 공개가 같은 순간에 일어나 rollback이 어려울 때
• canary 지표 없이 전체 사용자에게 바로 노출할 때
• 장애 시 누가 어떤 순서로 되돌릴지 불명확할 때

적용 순서

1. deploy와 release를 feature flag로 분리한다.
2. preflight gate와 post-deploy smoke를 정한다.
3. canary 확대 기준과 중단 기준을 숫자로 둔다.
4. rollback artifact와 flag off 경로를 리허설한다.
5. release health를 배포 후 일정 시간 모니터링한다.

함께 두는 파일

• feature flag 정의와 사용처, fallback test를 feature 폴더에 둔다.
• release checklist와 rollback runbook은 서비스별 배포 문서에 둔다.
• 관측성 metric name은 기능/route와 연결한다.

흔한 실수

• 배포 성공을 기능 성공으로 착각한다.
• rollback artifact 없이 hotfix만 준비한다.
• flag off 후 UI 상태를 테스트하지 않는다.
• 배포 후 모니터링 기준이 없다.

PR 완료 기준

• [ ] preflight와 post-deploy smoke가 있다.
• [ ] canary/rollback 기준이 있다.
• [ ] feature flag kill switch가 검증되었다.
• [ ] release health 결과가 남았다.

추천 항목 실행 우선순위 매핑

• P1(7일 내) — canary, flag, rollback artifact, release health 중 하나를 작은 변경 1건에 적용하고 증거(release note)를 남긴다.
• P2(30일 내) — 배포 절차 기준을 팀 템플릿, 체크리스트, CI 중 한 곳에 고정한다.
• P3(90일 내) — rollback 시간, canary error rate, release failure 수 추이를 보고 기준을 유지할지 조정할지 결정한다.
• 완료 기준 — 릴리스 오너가 증거와 철회 조건을 확인했다는 기록을 남긴다.

추천 항목 실행 체크리스트

• [ ] 1단계(7일) : canary, flag, rollback artifact, release health 적용 대상을 1개로 좁힌다.
• [ ] 2단계(30일) : 증거(release note, deployment log, rollback artifact, health dashboard)를 PR, ADR, 회고 중 한 곳에 연결한다.
• [ ] 3단계(60일) : rollback 시간, canary error rate, release failure 수가 기준 안에 들어왔는지 확인한다.
• [ ] 문제 대응 : 미달성 사유와 다음 조치, 중단 여부를 같은 기록에 남긴다.

추천 항목 실행 운영 규칙

• 실행 게이트 : deploy와 release를 분리하고 rollback artifact를 먼저 확인한다.
• 승인 체계 : 릴리스 오너가 영향 범위와 rollback 담당자를 적용 전에 확인한다.
• 재개 조건 : canary health가 기준 안에 있으면 트래픽을 단계적으로 늘린다.
• 정지 조건 : rollback 경로가 없거나 health 지표가 비면 release를 멈춘다.
• 리스크 점수 : 트래픽 비중, 변경 파일 수, dependency 변경으로 산정한다.
• 리더 승인자 : 릴리스 매니저가 최종 승인 책임을 맡는다.
• 승인 역할 : 배포 절차 작성자, 검토자, 운영 확인자를 분리해 기록한다.
• 재평가 주기 : 배포 후 24시간 안에 release health를 회고한다.