TIL - 20260927

juni·6일 전

목록 보기

463/468

0927 운영 자동화/AI 워크플로우 심화 (21/N): Release Gate, 배포 검증과 안전한 Rollback 자동화

✅ 1. CI가 성공했다고 ‘배포해도 안전하다’는 뜻은 아니다

보통 배포 흐름은 이렇게 시작한다.

Git Push
↓
Build
↓
Test
↓
Deploy

하지만 실제 Production에서는 이것만으로 부족하다.

예를 들어:

Build 성공

Unit Test 성공

Lint 성공

이어도 실제 배포 후에는 다음 문제가 생길 수 있다.

환경변수 누락

DB Migration 문제

외부 API 설정 오류

Production 데이터에서만 발생하는 Bug

Health Check 실패

응답 속도 급증

주문 API 오류 증가

즉:

코드가 빌드된다는 사실과 운영에 안전하다는 사실은 다르다.

✅ 2. Release를 하나의 Workflow로 본다

배포를 단순한:

npm run build
→ 서버 교체

정도로 생각하지 않는다.

하나의 Release Workflow로 생각한다.

Change
↓
Validation
↓
Build
↓
Test
↓
Approval
↓
Deploy
↓
Health Verification
↓
Traffic Release
↓
Monitoring
↓
Complete

이렇게 보면 각 단계마다 실패 기준과 복구 전략을 둘 수 있다.

✅ 3. Release와 Deploy를 구분하면 편하다

개념적으로:

Release
=
운영에 내보낼 하나의 변경 묶음

Deploy
=
그 Release를 특정 환경에 실제 적용하는 행위

예:

Release
release_20260927_03

Commit
abc123

이 Release를:

staging
production

에 각각 Deploy할 수 있다.

✅ 4. Release ID를 만드는 이유

운영 중 다음 질문이 자주 생긴다.

지금 서버에 어떤 코드가 올라가 있지?

이 장애가 어느 배포부터 발생했지?

직전 정상 버전이 뭐였지?

그래서 Commit SHA만으로도 가능하지만, 별도 Release ID를 두면 운영 관점에서 편하다.

예:

release_20260927_03

commitSha
abc123def

createdAt
2026-09-27 18:31

✅ 5. Release Metadata

예:

interface Release {
  id: string;

  commitSha: string;

  branch: string;

  environment: string;

  createdBy: string;

  createdAt: Date;

  status: ReleaseStatus;
}

추가로:

Migration 포함 여부

Feature Flag 변경 여부

Config 변경 여부

Rollback 가능 여부

등을 기록할 수 있다.

✅ 6. Release Gate란?

Release Gate는 다음 단계로 넘어가기 전에 반드시 만족해야 하는 조건이다.

예:

Build Gate

Test Gate

Security Gate

Migration Gate

Approval Gate

Health Gate

SLO Gate

즉:

조건 만족
→ 다음 단계

조건 실패
→ 배포 중단

이다.

✅ 7. 가장 기본적인 Gate

초기에는 다음 정도면 충분하다.

Build 성공

Unit Test 성공

Lint 성공

Type Check 성공

필수 환경변수 존재

Migration 검증

배포 후 Health Check

여기서부터 시작한다.

✅ 8. 모든 Gate를 동일하게 취급할 필요는 없다

Gate도 나눌 수 있다.

BLOCKING

실패하면 무조건 진행 중단.

예:

Build 실패

Migration 검증 실패

필수 Secret 없음

반면:

WARNING

은 사람이 확인하고 진행할 수 있다.

예:

Bundle Size 5% 증가

경미한 Test Flaky

Latency 약간 증가

✅ 9. Gate Result 구조

예:

interface ReleaseGateResult {
  gate: string;

  status:
    | 'PASS'
    | 'WARN'
    | 'FAIL';

  message?: string;

  checkedAt: Date;
}

✅ 10. Production 배포 전 확인해야 할 것

현재 프로젝트 기준으로는 다음 정도가 중요하다.

Build

TypeScript Type Check

Test

Prisma Schema

Migration

Environment Variable

AWS Parameter / Secret

DB 연결

외부 Provider 설정

배포 Artifact

특히 Environment와 Migration이 중요하다.

✅ 11. 환경변수 누락은 배포 전에 잡아야 한다

예:

KAKAO_API_KEY

가 Production에서 누락됐다고 하자.

배포 후 첫 알림톡 발송 때 알게 되는 것보다:

Deploy 시작 전
Config Validation

에서 막는 편이 낫다.

✅ 12. Config Validation

예:

const requiredConfig = [
  'DATABASE_URL',
  'KAKAO_API_KEY',
  'AWS_REGION',
];

배포 전:

모두 존재하는가?

형식이 올바른가?

를 확인한다.

Secret 값 자체를 로그에 찍지는 않는다.

✅ 13. Production과 Staging 설정 Drift

Staging에서는 정상인데 Production에서 실패하는 이유 중 하나다.

예:

Staging
API_URL=v2

Production
API_URL=v1

같은 차이가 있을 수 있다.

그래서 실제 Secret 값이 아니라:

필수 Key 목록

Configuration Version

Provider 이름

정도는 비교할 수 있다.

✅ 14. Config Version

예:

configVersion
2026-09-27-v3

처럼 설정 변경 자체에도 버전을 둘 수 있다.

그러면:

Release abc123

Config v3

조합을 기록할 수 있다.

✅ 15. 코드 배포만 Release가 아니다

운영 변경은 다음 모두를 포함한다.

Code

DB Migration

Config

Feature Flag

Infrastructure

예를 들어 코드 변경 없이:

Feature Flag ON

만 해도 실제 서비스 동작은 크게 바뀔 수 있다.

따라서 변경 이력을 남겨야 한다.

✅ 16. Migration Gate

DB Migration은 특히 강한 Gate가 필요하다.

예:

Migration 파일 존재

Migration 순서 정상

Production Schema와 충돌 없음

위험 SQL 포함 여부

Backward Compatibility

등을 본다.

✅ 17. 위험한 Migration 예시

DROP COLUMN phone;

ALTER TABLE orders
DROP COLUMN old_status;

같은 변경은 Rollback을 어렵게 한다.

✅ 18. Expand → Migrate → Contract

보다 안전한 Migration 패턴이다.

예를 들어 기존:

customer_phone

을 새로운 구조로 바꾼다고 하자.

바로 삭제하지 않는다.

1단계 — Expand

새 Column 추가

2단계 — 코드 배포

Old + New 모두 지원

3단계 — Data Migration

기존 데이터 이전.

4단계 — 안정화

새 구조 사용 확인.

5단계 — Contract

이전 Column 제거.

✅ 19. 이 방식의 장점

중간에 문제가 생겨도 이전 코드가 동작할 가능성이 높다.

즉:

Rollback 가능성 증가

한다.

✅ 20. Migration과 코드 배포를 한 번에 묶지 않는 이유

예:

DB Column 제거
+
새 코드 배포

를 동시에 했다가 새 코드가 실패하면 이전 코드도 이미 동작하지 않을 수 있다.

이런 배포는 되돌리기 어렵다.

✅ 21. Rollback 가능 여부를 Release 전에 판단한다

모든 Release가 동일하게 Rollback 가능한 것은 아니다.

예:

Frontend 문구 변경
→ 매우 쉬움

Backend Logic 변경
→ 보통

DB 파괴적 Migration
→ 어려움

그래서 Release Metadata에:

rollbackSafety

를 둘 수도 있다.

✅ 22. Rollback Safety

예:

SAFE

CONDITIONAL

UNSAFE

SAFE

이전 Release로 즉시 돌아갈 수 있음.

CONDITIONAL

Migration 상태를 확인해야 함.

UNSAFE

데이터 변환 때문에 단순 Rollback 불가.

✅ 23. 배포 전에 Rollback 방법부터 생각한다

많이 놓치는 부분이다.

배포 성공하면 어떻게 하지?

만 생각하지 말고:

배포 실패하면 어떻게 원래 상태로 돌아가지?

를 먼저 정한다.

✅ 24. Rollback Plan 예시

Release
v2026.09.27.3

Rollback Target
v2026.09.27.2

DB Compatibility
Compatible

Migration
Additive Only

Estimated Impact
Low

Rollback Method
Previous Artifact Deploy

✅ 25. Deploy 단계도 상태 머신으로 관리

예:

PENDING

VALIDATING

DEPLOYING

VERIFYING

MONITORING

SUCCESS

FAILED

ROLLBACK_PENDING

ROLLING_BACK

ROLLED_BACK

이렇게 하면 현재 어떤 단계인지 알 수 있다.

✅ 26. Deploy가 SUCCESS라고 바로 끝내지 않는다

서버에 파일을 올렸다고 배포 성공이 아니다.

실제 서비스가 정상인지 확인해야 한다.

그래서:

DEPLOYING
↓
VERIFYING

단계를 둔다.

✅ 27. Health Verification

배포 직후 확인할 수 있는 항목:

Application Health

DB Connection

Queue Connection

Critical API

External Provider Configuration

Running Commit SHA

등이다.

✅ 28. Running Commit 확인

배포 시스템에는 성공이라고 표시되는데 실제 서버는 이전 버전을 실행할 수도 있다.

그래서:

GET /health/version

같은 Endpoint에서:

{
  "releaseId": "release_20260927_03",
  "commitSha": "abc123"
}

정도를 확인할 수 있다.

✅ 29. Health Endpoint에 Secret은 넣지 않는다

Health Endpoint는:

Version

Build Time

Environment

Basic Status

정도만 보여준다.

민감 설정이나 내부 Infrastructure 정보를 과하게 노출하지 않는다.

✅ 30. Smoke Test

배포 직후 매우 핵심적인 기능만 빠르게 확인하는 테스트다.

예:

상품 조회

주문 Health Check

관리자 인증

DB Read

DB Write Test

단 Production에서는 실제 고객 주문을 만드는 테스트를 함부로 하면 안 된다.

✅ 31. Production Smoke Test는 안전해야 한다

예:

실제 고객 주문 생성

대신:

Synthetic Test Account

Dry Run Endpoint

Health용 Test Resource

를 활용한다.

✅ 32. 배포 직후 가장 위험한 시간

배포 직후 몇 분 동안은:

Error Rate

Latency

CPU

DB Connection

Queue Lag

등을 집중적으로 보는 것이 좋다.

✅ 33. Monitoring Window

예:

배포 후 10분

동안:

Critical Error 없음

Order Error Rate 정상

Latency 정상

Queue 정상

이면 Release를 최종 성공 처리한다.

✅ 34. Release 상태를 MONITORING으로 두는 이유

예:

배포 완료
19:00

오류 발생
19:04

라면 19:00에 즉시 SUCCESS 처리했던 것이 성급했던 것이다.

그래서:

VERIFYING
↓
MONITORING
↓
SUCCESS

흐름을 둔다.

✅ 35. Automatic Rollback

배포 후 명확한 이상 조건이 감지되면 자동 Rollback하는 방식이다.

예:

5분 동안

Order Error Rate > 20%

이면:

Auto Rollback

을 실행할 수 있다.

✅ 36. 자동 Rollback은 매우 보수적으로 써야 한다

다음처럼 약간의 오류만으로:

Error 3건
→ Rollback

하면 오히려 배포가 불안정해진다.

명확한 기준이 필요하다.

✅ 37. 자동 Rollback 조건 예시

Critical Health Check
3회 연속 실패

또는:

주문 생성 실패율
5분간 30% 이상

처럼 강한 신호를 사용한다.

✅ 38. 하나의 Metric만 보고 Rollback하지 않는 것이 좋다

예:

CPU 90%

만으로 Rollback할 필요는 없다.

오히려:

Error Rate 증가
+
Latency 증가
+
배포 직후 발생

처럼 여러 근거를 함께 볼 수 있다.

✅ 39. 최근 배포가 원인이라는 보장도 없다

예:

19:00 배포

19:02 외부 Provider 장애

가 우연히 겹칠 수도 있다.

따라서:

배포 시점과 장애 시점이 비슷하다

만으로 원인을 확정하지 않는다.

✅ 40. Human Approval이 필요한 Rollback

특히:

DB Migration 포함

대규모 상태 변경

외부 API 계약 변경

등은 자동 Rollback보다:

Rollback Recommended
↓
Approval
↓
Execution

형태가 안전하다.

✅ 41. Rollback과 Feature Flag의 차이

기능 하나가 문제라면 전체 Release를 되돌릴 필요가 없을 수도 있다.

예:

새 AI 상품 추천

이 문제라면:

Feature Flag OFF

만 하면 된다.

전체 Rollback보다 Blast Radius가 작다.

✅ 42. Kill Switch와도 연결된다

외부 자동화가 문제일 경우:

notificationAutoSend = false

같은 Kill Switch를 사용할 수 있다.

즉 대응 순서는 상황에 따라:

Feature Flag Off
↓
Kill Switch
↓
Partial Rollback
↓
Full Rollback

이 될 수 있다.

✅ 43. Roll Forward도 중요한 전략이다

항상 Rollback이 정답은 아니다.

예:

DB Migration 때문에
이전 코드로 돌아갈 수 없음

이라면:

Hotfix Release

를 빠르게 올리는 Roll Forward가 필요할 수 있다.

✅ 44. Rollback vs Roll Forward

Rollback

이전 정상 버전으로 복구

Roll Forward

새 수정 버전을 만들어 전진

Migration이 포함된 시스템에서는 Roll Forward가 더 안전한 경우도 있다.

✅ 45. Release Decision Matrix

상황	우선 대응
Feature 하나 문제	Feature Flag OFF
외부 자동화 문제	Kill Switch
코드 전체 문제	Rollback
DB 비호환	Roll Forward 검토
Provider 장애	배포보다 Circuit/Queue 대응

이런 기준을 Runbook에 넣을 수 있다.

✅ 46. Canary Release와 Release Gate 연결

0926에서 다룬 Canary를 생각해보면:

5%
↓
25%
↓
50%
↓
100%

각 단계마다 Gate를 둘 수 있다.

✅ 47. Canary Promotion Gate

예:

5% Traffic

배포 후:

Error Rate

Latency

Critical Business Metric

정상일 때만:

25%

로 올린다.

✅ 48. Promotion 조건 예시

5분 동안

Error Rate < 1%

p95 < 1초

Order Success Rate > 99%

Critical Error = 0

이면:

Promote

한다.

✅ 49. Regression이면 즉시 확장 중단

예:

5% Canary

Order Error Rate
8%

라면:

25%로 확대

하지 않는다.

Canary 중단

또는:

Rollback

한다.

✅ 50. Progressive Delivery의 핵심

핵심은:

새 Release가 안전하다고 가정하고
전체에게 배포

가 아니라:

작은 범위에서 증명하면서
점점 확대

하는 것이다.

✅ 51. 사용자 비율이 아니어도 된다

Canary 대상은:

Traffic %

외에도:

내부 관리자만

특정 테스트 계정

특정 통신사

특정 상품

특정 지역

Beta 사용자

등으로 나눌 수 있다.

✅ 52. 현재 프로젝트에서는 내부 운영자 Canary가 실용적이다

예:

새 주문 관리 UI

를 먼저:

개발자 계정

관리자 1명

에게만 노출한다.

문제 없으면 전체 관리자에게 적용한다.

이 정도만 해도 상당한 위험 감소 효과가 있다.

✅ 53. Release Gate와 SLO 연결

0922에서 만든 SLO를 Release 판단에도 사용할 수 있다.

예:

주문 API SLO
99.9%

배포 이후:

최근 5분
98.1%

로 떨어지면:

Promotion 중단

할 수 있다.

✅ 54. 하지만 월간 SLO와 배포 Gate는 기준이 다를 수 있다

월간:

99.9%

만 보면 배포 직후 장애를 빠르게 잡기 어렵다.

따라서 Release Gate에서는:

최근 5분

최근 10분

같은 짧은 Window를 같이 본다.

✅ 55. Error Budget과 Release 연결

Error Budget이 거의 소진된 상태라면:

실험적인 Release

를 줄이고:

안정화 Release

를 우선할 수 있다.

✅ 56. Release Risk Score를 만들 수도 있다

복잡한 AI 점수가 아니라 규칙 기반으로도 충분하다.

예:

DB Migration 포함
+3

Auth 변경
+3

결제/주문 로직
+3

Feature Flag 존재
-1

Rollback 안전
-2

합계가 높으면 Approval을 요구한다.

✅ 57. 하지만 숫자를 맹신하지 않는다

Risk Score는:

판단 지원 도구

이지:

절대적인 안전 판정

이 아니다.

✅ 58. 현재 프로젝트용 위험도 분류

예:

LOW

문구

UI

관리자 편의 기능

MEDIUM

상품 API

검색

Export

HIGH

주문 생성

상태 변경

알림톡

DB Migration

Auth

Production Automation

✅ 59. Release Approval Policy

예:

LOW
자동 배포 가능

MEDIUM
Test + Health Gate

HIGH
Manual Approval 필요

현재 혼자 개발한다면 Manual Approval은:

배포 직전 체크리스트 직접 확인

정도로도 의미가 있다.

✅ 60. 자기 자신에게 Approval이 무슨 의미인가?

혼자 개발한다고 의미 없는 것은 아니다.

코딩 직후 바로 Production에 올리는 것과:

작업 완료
↓
Test
↓
Diff 확인
↓
배포 Checklist
↓
Production Deploy

를 분리하는 것만으로도 실수를 줄인다.

✅ 61. Approval에는 근거가 있어야 한다

예:

Test
PASS

Migration
ADDITIVE ONLY

Rollback
SAFE

Recent Error Budget
HEALTHY

를 보고 승인한다.

✅ 62. AI Agent도 Gate를 통과해야 한다

AI가 코드를 수정했다고 바로 배포시키면 안 된다.

예:

AI Modify
↓
AI Test
↓
Deploy

보다는:

AI Modify
↓
Build Gate
↓
Test Gate
↓
Diff Review
↓
Policy Gate
↓
Human Approval
↓
Deploy

가 안전하다.

✅ 63. AI Review와 Release Gate

AI가 자체 리뷰하는 것도 가능하지만:

같은 Agent가
작성 + 승인

하면 독립성이 약하다.

최소한:

Writer
↓
Deterministic Test
↓
Policy Check
↓
Human Approval

정도로 분리하는 것이 낫다.

✅ 64. Deterministic Gate를 AI보다 우선한다

예:

Build 성공 여부

Test 성공 여부

Lint

Type Check

Migration 위험 SQL

은 AI 판단보다 명확한 코드 기반 Gate가 낫다.

AI는 설명과 분석 보조로 활용한다.

✅ 65. AI가 잘할 수 있는 Release 분석

예:

Git Diff 요약

변경 영향 영역

Migration 포함 여부 설명

Rollback 위험 요소 요약

누락 가능 테스트 제안

등이다.

✅ 66. AI가 Release Risk Report 생성

예:

Release
release_20260927_03

Changes
- 주문 상태 변경 로직 수정
- NotificationJob Retry 수정

Risk
HIGH

DB Migration
없음

External Provider
Kakao

Rollback
SAFE

Recommended Checks
- 주문 상태 변경 Integration Test
- 중복 알림톡 테스트

이런 보고서를 만들 수 있다.

✅ 67. AI가 배포 승인 자체를 최종 결정하게 할 필요는 없다

초기에는:

AI
→ Release Report

사람
→ Approval

이 가장 현실적이다.

✅ 68. Release Artifact를 불변으로 관리

빌드 후 Production에서 다시 Build하면 환경에 따라 결과가 달라질 수 있다.

가능하면:

Build Once
↓
Same Artifact
↓
Staging
↓
Production

이 좋다.

✅ 69. Artifact Metadata

예:

artifactId

commitSha

buildTime

nodeVersion

checksum

등을 기록할 수 있다.

✅ 70. Checksum

배포 Artifact가 바뀌지 않았는지 확인하기 위해 Hash를 사용할 수 있다.

sha256

같은 값을 저장한다.

✅ 71. Dependency Drift

Build 시점마다 Dependency가 달라지면 재현성이 떨어진다.

Lockfile을 유지하는 이유도 여기에 있다.

예:

pnpm-lock.yaml

을 기준으로 고정한다.

✅ 72. Runtime Version도 기록하면 좋다

예:

Node
24.13.1

같은 정보다.

개발 환경과 Production Runtime 차이로 생기는 문제를 추적하기 쉽다.

✅ 73. Release Manifest

하나의 파일로 다음 정보를 모을 수도 있다.

{
  "releaseId": "release_20260927_03",
  "commitSha": "abc123",
  "nodeVersion": "24.13.1",
  "migrationVersion": "20260927001",
  "configVersion": "v7"
}

✅ 74. Rollback Target은 미리 보관한다

새 배포 후 문제가 생겼는데 이전 Artifact가 없으면 Rollback이 느려진다.

그래서:

Current Release

Previous Stable Release

를 명확하게 관리한다.

✅ 75. Stable Release 개념

가장 최근 배포 버전이 항상 Stable Release인 것은 아니다.

예:

v3
현재 Monitoring 중

v2
마지막 검증 완료 버전

이라면 Rollback Target은:

v2

다.

✅ 76. Production 상태와 Release DB 상태를 Reconcile

0927 내용도 이전 Reconciliation과 연결된다.

DB에는:

release_v3
ACTIVE

인데 실제 서버는:

release_v2

를 실행하고 있을 수 있다.

따라서 주기적으로:

Desired Release

Actual Running Release

를 비교한다.

✅ 77. Release Drift

Expected
v3

Actual
v2

이면:

DEPLOYMENT_DRIFT

다.

자동으로 재배포하기보다 우선 Alert하는 편이 안전할 수 있다.

✅ 78. Multi-instance 환경에서는 더 중요하다

예:

Instance A
v3

Instance B
v3

Instance C
v2

라면 일부 고객만 이상한 버전을 보게 된다.

그래서 Instance별 Release Version을 확인할 수 있으면 좋다.

✅ 79. 지금은 규모가 작다면 여기까지 할 필요는 없다

현재 단일 또는 소규모 EC2 운영이라면:

Health Version Endpoint

Release ID 기록

정도만 해도 충분하다.

✅ 80. 배포 실패 자체도 Incident일 수 있다

Production Deploy가 실패했지만 기존 버전이 정상이라면:

고객 영향 없음

일 수 있다.

이 경우:

P2 Deploy Incident

정도로 관리할 수 있다.

반면 배포 실패로 서비스가 내려갔다면 Severity가 높아진다.

✅ 81. Release Timeline

예:

18:30
Release 생성

18:31
Build PASS

18:34
Test PASS

18:35
Approval

18:37
Deploy 시작

18:39
Health PASS

18:39
Monitoring

18:49
SUCCESS

문제가 생기면:

18:42
Order Error Rate 상승

18:43
Rollback 시작

18:45
Previous Release 복구

처럼 기록한다.

✅ 82. Deploy Correlation ID

Release 하나에:

correlationId

를 부여하면:

CI

Deploy

Health Check

Rollback

로그를 하나로 묶을 수 있다.

✅ 83. Incident와 Release Timeline 연결

Incident 발생 시:

incident.startedAt

과:

release.deployedAt

를 같이 보여주면 분석이 쉬워진다.

✅ 84. Deployment Freeze

특정 기간에는 배포를 자제할 수도 있다.

예:

아이폰 사전예약 첫날

대형 프로모션

추석 연휴 직전

처럼 운영 대응 인력이 부족하거나 트래픽이 몰릴 때다.

✅ 85. Freeze라고 모든 배포를 금지하는 것은 아니다

예:

긴급 Bug Fix

Security Fix

는 배포해야 할 수 있다.

따라서:

Normal Change
차단

Emergency Change
Approval 후 가능

정도로 운영한다.

✅ 86. Change Window

배포 시간을 정하는 것도 하나의 안전장치다.

혼자 운영한다면:

배포 후 최소 30분은 직접 상태를 볼 수 있는 시간

에 배포하는 것이 좋다.

✅ 87. 퇴근 직전 큰 변경은 피하는 이유

예:

18:58
대규모 Migration 배포

19:00
퇴근

같은 방식은 문제가 발생했을 때 대응하기 어렵다.

변경 규모가 클수록 Monitoring 시간을 확보한다.

✅ 88. Emergency Release

긴급 수정은 일반 Release 절차 일부를 줄일 수 있다.

하지만 완전히 생략하면 안 된다.

최소:

Build

Critical Test

Diff 확인

Rollback Plan

정도는 유지한다.

✅ 89. Emergency라고 Audit를 생략하지 않는다

오히려 나중에 반드시 기록해야 한다.

왜 긴급 배포했는가?

어떤 Gate를 생략했는가?

결과는 어땠는가?

를 남긴다.

✅ 90. Release Checklist

실제 배포 전에 빠르게 확인할 수 있다.

[ ] Build PASS

[ ] Test PASS

[ ] Type Check PASS

[ ] Migration 확인

[ ] Config 확인

[ ] Feature Flag 확인

[ ] Rollback Target 확인

[ ] Release Notes 확인

✅ 91. 배포 후 Checklist

[ ] Running Release 확인

[ ] Health Check PASS

[ ] 주문 API 정상

[ ] 관리자 API 정상

[ ] DB 정상

[ ] Queue 정상

[ ] Error Rate 정상

[ ] Latency 정상

✅ 92. 위험 배포 추가 체크

[ ] Migration Backward Compatible

[ ] 복구 Query 준비

[ ] Feature Flag로 기능 차단 가능

[ ] Provider 의존성 확인

[ ] Manual Approval 완료

✅ 93. Release Notes 자동화

Git Diff와 Commit을 바탕으로 AI가 초안을 만들 수 있다.

예:

### Changes

- 주문 상태 변경 로직 수정
- 알림톡 Retry 개선
- 관리자 검색 성능 개선

### Risk

- 주문 상태 변경
- 외부 알림톡 API

### Migration

없음

### Rollback

이전 Release 재배포 가능

✅ 94. 사용자용 Release Notes와 내부 Release Notes는 다르다

사용자:

검색 기능을 개선했습니다.

내부:

GET /admin/orders 쿼리 변경
index 추가

목적이 다르다.

운영 자동화에는 내부 Release Notes가 중요하다.

✅ 95. Local LLM Work Report와 연결

현재 자동 보고서에 다음을 추가할 수 있다.

### Release

Release
20260927-03

Commit
abc123

Deploy
SUCCESS

Migration
없음

Monitoring
정상

Rollback
불필요

운영 성과 기록에도 좋다.

✅ 96. 자동 배포 기록을 Notion에 남길 수도 있다

예:

Release ID

작업 요약

Risk

Deploy 결과

Incident 여부

Rollback 여부

를 일일 보고서와 함께 관리한다.

✅ 97. GitHub Actions 구조 예시

개념적으로:

validate
↓
build
↓
test
↓
release
↓
deploy
↓
verify

각 Job이 앞 Gate를 통과해야 다음으로 진행한다.

✅ 98. Production Deploy Job은 별도 분리

예:

deploy-staging

와:

deploy-production

을 분리한다.

Production은:

environment protection

이나 Approval을 추가할 수 있다.

✅ 99. 배포 Script도 Idempotent하게

같은 Release 배포 명령을 두 번 실행했을 때:

데이터 중복

Migration 중복

불필요한 Side Effect

가 발생하지 않는 것이 좋다.

0916의 Idempotency와 연결된다.

✅ 100. Deploy Request Idempotency

예:

(environment, releaseId)
UNIQUE

를 둘 수 있다.

이미:

production
release_03

배포가 완료됐다면 동일 Deploy 요청은 결과를 재사용한다.

✅ 101. Migration은 별도의 Idempotency가 필요하다

Migration Framework가 이미 적용된 Migration을 기록한다면 같은 Migration을 다시 적용하지 않는다.

Prisma Migration 같은 도구가 이런 역할 일부를 담당한다.

✅ 102. Release Lock

동시에 Production 배포 두 개가 실행되면 위험하다.

예:

Release A 배포 중

Release B 배포 시작

하면 상태가 꼬일 수 있다.

따라서:

Production Deploy Lock

을 둘 수 있다.

✅ 103. Atomic Deploy Claim

예:

READY
→ DEPLOYING

을 조건부 Update한다.

한 Deploy Worker만 성공하도록 한다.

✅ 104. Stale Deploy

배포 Worker가 죽어:

DEPLOYING

에 영원히 남을 수도 있다.

0917 구조처럼:

Heartbeat

Lease

Reconciliation

을 적용할 수 있다.

✅ 105. Deploy Reconciliation

예:

DeployJob
DEPLOYING

Worker 없음

일 때 실제 서버를 확인한다.

Running Release = target

이면:

SUCCESS 복구

할 수 있다.

반대로 이전 Release라면:

FAILED 또는 RETRY

를 판단한다.

✅ 106. 배포 자동화에도 UNKNOWN 상태가 필요하다

예:

배포 API 호출

↓
Connection 끊김

실제로 배포가 시작됐는지 모를 수 있다.

이때:

UNKNOWN
→ 실제 Release 확인

을 먼저 한다.

✅ 107. 무작정 Deploy Retry하면 안 되는 이유

이미 배포가 성공했는데 같은 Deploy를 다시 실행할 수 있기 때문이다.

그래서:

Reconcile First

가 중요하다.

✅ 108. Release Gate 기록도 Audit 대상이다

예:

Release
release_03

Gate
MIGRATION_CHECK

Result
PASS

CheckedBy
SYSTEM

또는:

Approval
admin_1

같은 기록을 남긴다.

✅ 109. Release DB 모델 예시

model Release {
  id          String   @id
  commitSha   String

  status      String
  riskLevel   String

  createdAt   DateTime @default(now())
  deployedAt  DateTime?

  rollbackTo  String?

  deployments Deployment[]
}

✅ 110. Deployment 모델

model Deployment {
  id            String   @id @default(cuid())

  releaseId     String
  environment   String

  status        String

  startedAt     DateTime?
  completedAt   DateTime?

  correlationId String

  release       Release  @relation(
    fields: [releaseId],
    references: [id]
  )

  @@unique([releaseId, environment])
}

✅ 111. ReleaseGate 모델

model ReleaseGate {
  id         String   @id @default(cuid())

  releaseId  String

  type       String
  status     String

  message    String?

  checkedAt  DateTime @default(now())
}

✅ 112. Rollback Record

Rollback도 별도 Deployment라고 볼 수 있다.

또는:

rollbackFrom

rollbackTo

reason

을 기록한다.

✅ 113. Release State Machine

예:

DRAFT

↓

VALIDATING

↓

READY

↓

DEPLOYING

↓

VERIFYING

↓

MONITORING

↓

SUCCESS

실패:

FAILED

ROLLBACK_PENDING

ROLLING_BACK

ROLLED_BACK

✅ 114. 잘못된 상태 전이는 차단한다

예:

DRAFT
→ SUCCESS

는 허용하지 않는다.

또한:

ROLLED_BACK
→ DEPLOYING

도 별도의 새 Deployment로 처리하는 편이 낫다.

✅ 115. Release Gate Service 구조

ReleaseValidator

├─ BuildGate
├─ TestGate
├─ ConfigGate
├─ MigrationGate
├─ RiskGate
└─ ApprovalGate

각 Gate가 독립적으로 결과를 반환하게 할 수 있다.

✅ 116. Gate Orchestrator

for (const gate of gates) {
  const result =
    await gate.check(context);

  await saveGateResult(result);

  if (result.status === 'FAIL') {
    throw new ReleaseBlockedError(
      gate.name,
    );
  }
}

형태로 구성할 수 있다.

✅ 117. 배포 후 Gate

배포 전 Gate만 있는 것은 아니다.

HealthGate

SmokeTestGate

MetricGate

CanaryGate

는 배포 후에 실행된다.

✅ 118. Release Workflow 전체

Create Release

↓

Pre-Deploy Gates

↓

Approval

↓

Deploy

↓

Health Gate

↓

Smoke Gate

↓

Canary / Monitoring

↓

Metric Gate

↓

Success

이것이 하나의 Release Orchestration이다.

✅ 119. Production에서 자동화 범위

현재 규모에서는 다음은 자동화해도 좋다.

Build

Lint

Test

Type Check

Config Key Validation

Health Check

Version Check

반면:

Production Rollback

파괴적 Migration

대규모 Feature Flag 변경

은 사람 확인을 남겨두는 편이 좋다.

✅ 120. AI Release Assistant 구조

예:

Git Push

↓

CI Gate

↓

AI Release Summary

↓

Risk Analysis

↓

Human Approval

↓

Deploy

↓

Metric Collection

↓

AI Result Summary

AI가 배포 시스템을 지배하는 것이 아니라 분석과 문서화를 보조한다.

✅ 121. AI에게 줄 수 있는 Release Context

Commit Diff

Changed Files

Test Result

Migration Diff

Config Changes

Previous Release

Recent Incidents

Current Error Budget

정도다.

✅ 122. AI가 반환할 구조

Change Summary

Risk Areas

Required Checks

Rollback Risks

Missing Tests

Recommended Monitoring

형태가 좋다.

✅ 123. AI에게 Secret이나 전체 Production 환경변수를 넘기지 않는다

Config는:

KAKAO_API_KEY
exists=true

정도만 전달해도 충분하다.

실제 값을 넘길 필요가 없다.

✅ 124. 배포 성공 후 자동 보고서

예:

Release
release_20260927_03

Result
SUCCESS

Duration
7m 31s

Gates
8/8 PASS

Health
PASS

Monitoring
10m 정상

Rollback
미실행

Incident
없음

이런 보고서를 자동 생성할 수 있다.

✅ 125. 배포 실패 보고서

Release
release_20260927_04

Result
ROLLED_BACK

Failure Stage
Health Verification

Error
ORDER_API_HEALTH_FAILED

Rollback Target
release_20260927_03

Customer Impact
없음

이런 기록은 나중에 매우 유용하다.

✅ 126. Release Failure도 Regression Test로 연결

배포 중 발견된 문제:

환경변수 Validation 누락

이 있었다면 다음부터:

Config Gate

를 추가한다.

즉:

Release Failure
↓
Postmortem
↓
New Gate

로 발전한다.

✅ 127. 좋은 Gate는 실제 사고에서 태어난다

처음부터 Gate 50개를 만들 필요는 없다.

예:

Migration 문제 발생
→ Migration Gate 추가

Secret 누락
→ Config Gate 추가

Health 실패
→ Health Gate 강화

식으로 실제 위험에 맞춰 발전시킨다.

✅ 128. Gate가 너무 많으면 배포가 느려진다

안전성을 위해 만든 시스템이:

배포 한 번에 1시간

걸리면 작은 변경도 부담스러워진다.

그래서 Gate도 ROI를 따져야 한다.

✅ 129. Fast Gate와 Slow Gate

예:

Fast

Lint

Type Check

Config Validation

Unit Test

Slow

Full Integration Test

Reliability Test

Large E2E

모든 Commit마다 Slow Test를 돌릴 필요는 없을 수 있다.

✅ 130. 위험도에 따라 Test 수준을 조정

예:

LOW Risk
Fast Gates

HIGH Risk
Fast + Integration + Reliability

처럼 운영할 수 있다.

✅ 131. 주문 로직 변경은 Reliability Test 대상

예:

Notification

Webhook

Order State

Transaction

변경은:

Duplicate

Retry

Rollback

Idempotency

관련 테스트를 추가로 돌리는 것이 좋다.

✅ 132. 변경 파일 기반 Gate 선택도 가능하다

예:

prisma/

변경:

Migration Gate 실행

notification/

변경:

Notification Reliability Test

이런 방식이다.

✅ 133. 처음부터 너무 똑똑한 선택 로직은 만들지 않는다

테스트 누락 위험이 있기 때문이다.

초기에는:

핵심 테스트 전체 실행

이 더 안전하다.

규모가 커진 뒤 최적화한다.

✅ 134. Deployment Runbook

예:

1. Release ID 확인

2. Gate PASS 확인

3. Migration 확인

4. Rollback Target 확인

5. Production Deploy

6. Version 확인

7. Health 확인

8. 핵심 API 확인

9. 10분 Monitoring

10. Release SUCCESS 처리

✅ 135. Rollback Runbook

1. 장애 영향 확인

2. 현재 Release 확인

3. Migration Compatibility 확인

4. Feature Flag Off 가능 여부 확인

5. Rollback Target 확인

6. Rollback 실행

7. Health 확인

8. Business Metric 확인

9. Incident Timeline 기록

✅ 136. 배포에서 가장 중요한 질문 5개

무엇이 바뀌는가?

무엇이 깨질 수 있는가?

어떻게 확인할 것인가?

문제면 어떻게 멈출 것인가?

어떻게 원래 상태로 돌아갈 것인가?

이 다섯 가지에 답할 수 있으면 배포 품질이 크게 높아진다.

✅ 137. 현재 프로젝트에 바로 적용할 우선순위

1단계

Release ID

Commit SHA

Build/Test Gate

Health Version

2단계

Config Validation

Migration Checklist

Rollback Target

3단계

Deploy Monitoring Window

Release Timeline

Feature Flag

4단계

Canary

Metric Gate

Semi-Automatic Rollback

5단계

AI Release Report

Risk Analysis

Automated Release Summary

✅ 138. 현재 규모에서 과한 것

당장은 다음까지 할 필요는 없다.

복잡한 Deployment Platform

완전 자동 Canary Controller

Multi-region Rollout

Service Mesh Traffic Shifting

AI Autonomous Rollback

오히려 유지보수 대상만 늘어난다.

✅ 139. 가장 ROI 높은 것

현재 환경이라면 우선:

1. Release ID 기록

2. 배포 전 Checklist

3. Health / Version Endpoint

4. 직전 Stable Release 유지

5. 배포 후 10분 Monitoring

이 다섯 가지가 가장 현실적이다.

✅ 140. 그다음 자동화

반복해서 사람이 확인하는 항목부터 자동화한다.

Build

Test

Config

Health

Version

반면 위험 판단은 당분간 사람이 한다.

✅ 141. Codex 구현 프롬프트

현재 NestJS + Prisma + GitHub Actions 기반 프로젝트에
간단한 Release Gate / Deployment Verification 구조를 추가해줘.

목표는 복잡한 배포 플랫폼을 만드는 것이 아니라,
Production 배포 전후에 반드시 확인해야 하는 조건을
자동으로 검증하고 Release 이력을 남기는 것이다.

기존 배포 방식과 Infrastructure를 먼저 분석하고,
없는 도구를 새로 가정해서 만들지 않는다.

요구사항:

1. Release 개념을 추가한다.

최소 필드:
- id
- commitSha
- status
- riskLevel
- createdAt
- deployedAt
- rollbackTo

2. Release 상태는 다음을 지원한다.

- DRAFT
- VALIDATING
- READY
- DEPLOYING
- VERIFYING
- MONITORING
- SUCCESS
- FAILED
- ROLLBACK_PENDING
- ROLLING_BACK
- ROLLED_BACK

3. Deployment를 환경별로 관리할 수 있게 한다.

필드:
- releaseId
- environment
- status
- correlationId
- startedAt
- completedAt

동일 environment + releaseId 배포 요청은
중복 실행되지 않도록 한다.

4. Release Gate 구조를 만든다.

초기 Gate:
- BUILD
- TEST
- TYPE_CHECK
- CONFIG
- MIGRATION
- HEALTH

Gate 결과:
- PASS
- WARN
- FAIL

5. FAIL인 Blocking Gate가 존재하면
Production 배포를 진행하지 않는다.

6. Config Gate에서는 실제 Secret 값을 로그에 남기지 않고,
필수 환경변수 또는 SSM Parameter 존재 여부만 확인한다.

7. Prisma Migration이 있다면
배포 전 Migration 존재 여부와 위험 변경 여부를
확인할 수 있는 구조를 만든다.

자동으로 DROP 등의 SQL을 실행하지 않는다.

8. Health / Version 정보를 확인할 수 있도록 한다.

가능하다면 다음 정보를 반환한다.
- status
- releaseId
- commitSha
- environment

Secret이나 Infrastructure 상세 정보는 노출하지 않는다.

9. Deploy 후 즉시 SUCCESS 처리하지 않는다.

DEPLOYING
→ VERIFYING
→ MONITORING
→ SUCCESS

흐름을 사용한다.

10. VERIFYING 단계에서
Health Check와 Running Release를 확인한다.

11. Rollback 대상 Release를 명시적으로 기록한다.

12. Migration 때문에 단순 Rollback이 위험한 경우
자동 Rollback하지 않고
MANUAL_REQUIRED에 준하는 흐름으로 처리한다.

13. Release와 Deployment 상태 전이는
허용된 Transition만 가능하도록 한다.

14. Production Deploy가 동시에 두 개 실행되지 않도록
Lock 또는 Atomic State Transition을 사용한다.

15. Deployment Worker가 중간에 종료될 경우를 고려해
현재 실제 Running Release를 확인하여
상태를 복구할 수 있도록 한다.

16. 동일 Release를 다시 배포 요청했을 때
이미 SUCCESS라면 중복 Side Effect 없이
기존 결과를 반환할 수 있게 한다.

17. GitHub Actions에서 가능한 범위 내에서
다음 순서로 구성한다.

validate
→ build
→ test
→ release
→ deploy
→ verify

18. Production 배포 전
수동 Approval을 적용할 수 있는 구조를 유지한다.

19. 배포 완료 후 Release Summary를 생성할 수 있게 한다.

예:
- releaseId
- commitSha
- gate 결과
- deployment 결과
- health 결과
- rollback 여부

20. 테스트를 작성한다.

- Blocking Gate 실패 시 배포 차단
- 모든 Gate PASS 시 READY
- 동일 Release 중복 배포 방지
- Health 실패
- Running Release 불일치
- 잘못된 상태 전이 차단
- Rollback Target 저장
- Secret 로그 미노출

✅ 142. AI Release Report 프롬프트

현재 배포 예정 Git Diff와 Test 결과를 분석해서
Production Release Review를 작성해줘.

직접 배포를 실행하거나 승인하지 말고
판단에 필요한 정보만 정리한다.

다음 구조로 작성한다.

## 변경 요약

## 영향 영역

## 위험도

LOW / MEDIUM / HIGH

## DB Migration

- 존재 여부
- 주요 변경
- Rollback 영향

## External Dependency

## Feature Flag

## 누락 가능 테스트

## 배포 후 확인할 Metric

## Rollback 시 주의점

## 최종 체크리스트

특히 다음 영역 변경은 명확히 표시한다.

- 주문
- 고객 데이터
- Auth
- Prisma / DB
- Notification
- Webhook
- AWS
- Production Automation

실제 Diff에서 확인할 수 없는 내용은
추정해서 사실처럼 작성하지 않는다.

✅ 143. 실무 체크리스트

Release

Release ID가 있는가?
Commit SHA를 알고 있는가?
변경 내용을 설명할 수 있는가?
위험도가 정의되어 있는가?

Gate

Rollback

이전 Stable Release가 있는가?
Rollback 방법을 알고 있는가?
DB가 이전 코드와 호환되는가?
Feature Flag로 먼저 차단할 수 있는가?

Deployment

동시 Production Deploy를 막는가?
Running Release를 확인하는가?
Health Check가 있는가?
배포 후 Monitoring 시간을 갖는가?

Metric

Error Rate를 확인하는가?
Latency를 확인하는가?
Queue 상태를 확인하는가?
핵심 Business Flow가 정상인가?

Migration

파괴적 변경이 있는가?
이전 코드와 호환되는가?
Expand → Migrate → Contract를 고려했는가?
단순 Rollback이 가능한가?

AI

AI가 Diff 요약을 할 수 있는가?
위험 변경을 표시하는가?
AI가 Production 배포를 독단적으로 실행하지 않는가?
결정 가능한 검증은 코드 기반 Gate가 담당하는가?

📌 요약

지금까지는:

장애를 감지하고

장애가 퍼지는 것을 막고

실패해도 복구하는 방법

을 주로 다뤘다.

0927에서는 한 단계 앞에서:

애초에 위험한 변경이 Production 전체에 들어가기 전에 어떻게 걸러낼 것인가

를 다뤘다.

핵심 개념은:

Release Gate

다.

배포 흐름을 단순히:

Build
→ Deploy

로 보지 않고:

Change
↓
Validate
↓
Build
↓
Test
↓
Gate
↓
Approval
↓
Deploy
↓
Verify
↓
Monitor
↓
Success

라는 Workflow로 관리한다.

특히 중요한 것은:

배포 명령이 성공했다

와

서비스가 정상적으로 동작한다

를 구분하는 것이다.

그래서 배포 이후에도:

Health Check

Running Release

Error Rate

Latency

Queue

Business Flow

를 확인해야 한다.

그리고 Release를 최종 SUCCESS 처리하기 전에:

MONITORING

단계를 두는 것이 안전하다.

Rollback 역시 배포 후 생각하는 것이 아니다.

배포 전에
Rollback 가능 여부부터 판단

해야 한다.

특히 DB Migration이 포함되면:

새 코드 배포
→ 문제
→ 이전 코드

가 단순하게 되지 않을 수 있다.

그래서:

Expand
→ Migrate
→ Contract

형태로 DB 변경을 단계적으로 진행하면 Rollback 가능성이 높아진다.

0926에서 다룬 Feature Flag·Canary와 연결하면:

Release
↓
Gate
↓
작은 범위 Deploy
↓
Metric 확인
↓
Promotion
↓
다시 확인
↓
100%

형태가 된다.

AI 자동화에서도 마찬가지다.

AI에게:

코드 작성
→ Production 배포

권한을 바로 주는 것이 아니라:

AI 수정

↓

Build / Test

↓

Deterministic Gate

↓

AI Risk Report

↓

Human Approval

↓

Deploy

순서로 두는 것이 훨씬 안전하다.

현재 프로젝트에서는 거창한 Deployment Platform보다 먼저:

Release ID

Commit SHA 기록

Build/Test Gate

Health Version

Rollback Target

배포 후 Monitoring

만 제대로 갖춰도 큰 개선이 된다.

전체 흐름을 지금까지의 시리즈와 연결하면:

Change
↓
Gate
↓
Progressive Release
↓
Observe
↓
Verify
↓
Detect Regression
↓
Stop / Rollback
↓
Reconcile
↓
Recover
↓
Learn

이 된다.

결국 안전한 배포의 핵심은

“배포가 성공했는가”를 보는 것이 아니라, 변경사항이 실제 운영 환경에서 안전하다는 증거를 단계적으로 확인하면서 다음 단계로 넘어가는 것

이다.

juni

이전 포스트

TIL - 20260925

다음 포스트