---
type: knowledge
domain: infra
status: active
last-reviewed: 2026-07-27
---

# CI-CD 파이프라인 실전

> 한 줄 정의
> 파이프라인은 "빌드를 자동으로 돌리는 스크립트"가 아니라 **코드가 운영에 닿는 유일한 길**이다. 최소선(push→테스트→빌드→승인→배포)은 [[인프라 원리]], 내보내는 방법(블루그린·카나리·롤백)은 [[배포 전략 실전]] — 여기는 파이프라인 자체의 설계 규율이다.

## 파이프라인 단계 표 — 각 단계의 실패 규율

| 단계 | 하는 일 | 실패 시 규율 |
|------|--------|-------------|
| 빌드 | 컴파일·의존성 해석·이미지 생성 | 즉시 중단. 빌드가 깨진 브랜치에 새 작업 쌓기 금지 — 고치는 게 전원 최우선 |
| 테스트 | 단위·통합·정적분석·보안 스캔 | 실패 = 진행 불가. "일단 스킵하고 배포"는 게이트를 장식으로 만드는 첫걸음 |
| 아티팩트 | 버전 태그를 붙여 저장소에 발행 | 같은 커밋 = 같은 아티팩트. 발행 실패는 빌드 실패와 동급 |
| 배포 | 저장된 아티팩트를 환경에 반영 | 실패 시 자동 중단 + 이전 버전 유지. 반쯤 배포된 상태로 방치 금지 |

단계 순서는 **싼 실패를 먼저** 배치한다 — 1분짜리 lint가 20분짜리 통합 테스트보다 앞에 온다. 피드백이 느린 파이프라인은 결국 우회당한다.

## 빌드 재현성 — 한 번 빌드, 전 환경 승격

- **같은 아티팩트가 dev→stage→prod로 승격된다. 환경별 재빌드 금지.** 환경마다 다시 빌드하면 "검수한 것"과 "배포된 것"이 다른 바이너리다 — 검수가 무효가 된다.
- 재현성의 전제: 의존성 버전 고정(lockfile), 베이스 이미지 태그 고정(latest 금지), 빌드 도구 버전 명시. "오늘 빌드하면 어제와 다른 결과"는 재현이 아니라 복권이다.
- 환경별 차이는 아티팩트가 아니라 **주입되는 설정**으로만 만든다 → [[환경 구성과 시크릿 관리]].
- 아티팩트에는 커밋 해시·빌드 시각을 박아, 운영에서 "지금 도는 게 어느 커밋인가"를 조회로 끝낸다.

## 게이트 설계 — 자동과 사람의 역할 분담

| 게이트 | 종류 | 원칙 |
|--------|------|------|
| 테스트·정적분석·보안 스캔 | 자동 | 사람이 매번 판단하지 않는다 — 기준은 코드로 고정 |
| 커버리지·품질 기준 | 자동 | 기준 미달 = 차단. "이번만 예외"가 쌓이면 게이트가 아니다 |
| 스테이징 검증 | 자동+사람 | E2E 자동 + 필요 시 수동 확인 |
| **운영 배포 승인** | **사람** | 파이프라인·자동화가 최종 버튼을 누르지 않는다 → [[배포 전략 실전]] 사람 게이트 |

자동 게이트의 존재 이유는 사람 게이트를 **가볍게** 만드는 것이다 — 사람이 테스트 결과를 눈으로 재검사해야 한다면 자동화가 실패한 것이다.

## 파이프라인이 곧 배포 권한 — 수동 경로 봉쇄

- 서버 SSH 접속 후 직접 배포, 로컬 빌드 결과물 업로드 같은 **파이프라인 밖 배포 경로는 기술적으로 막는다** (배포 자격증명을 파이프라인만 보유).
- 수동 경로가 하나라도 살아 있으면: 게이트 전체가 우회 가능해지고, "운영에 뭐가 떠 있는지"를 아무도 확답할 수 없게 된다.
- 긴급 배포도 같은 파이프라인으로 — 단계를 줄인 긴급 트랙을 미리 만들어두는 것이지, 파이프라인을 버리는 것이 아니다.
- 인프라 변경도 같은 원칙(코드·검토·승인)을 따른다 — AWS 구현은 [[13_IaC와 CI-CD]].

## 실패한 빌드 방치 금지

- 메인 브랜치의 빨간 빌드는 **전원의 블로커**다 — 방치가 하루를 넘기면 다들 빨간불에 무감각해지고, 그때부터 파이프라인은 신호가 아니라 배경 소음이다.
- 간헐 실패(flaky) 테스트는 "다시 돌리면 되는 것"이 아니라 결함이다 — 격리하고 티켓을 만들되, 무기한 스킵은 금지.
- 파이프라인 실패도 무성 실패 금지: 실패는 만든 사람에게 즉시 통지되고, 마지막 성공 시각이 감시된다.

## 외주 지점

- **발주사 승인 게이트**: 운영 배포 승인자는 계약상 발주사 담당자다 — 수행사가 임의로 운영에 배포하는 구조는 사고 시 책임 분계가 무너진다. 승인 이력은 검수 근거로 보존한다.
- **배포 창구 단일화**: 수행사 인력 개개인이 아니라 파이프라인 하나가 배포 창구다 — 인력 교체·퇴출 시 배포 권한 회수가 자격증명 하나로 끝난다.
- **검수 환경 = 운영 동형**: 검수를 통과한 아티팩트가 그대로 운영에 승격되는 구조여야 검수가 법적 효력을 가진다. 검수 후 재빌드는 검수 무효 주장의 빌미다.
- 파이프라인 정의·빌드 스크립트도 인수인계 산출물이다 — 소유권은 발주사.

## 안티패턴

- **환경별 재빌드** — 검수한 바이너리와 배포된 바이너리가 다르다.
- **게이트 예외의 일상화** — "급하니까 스킵"이 3번 반복되면 그 게이트는 없는 것이다.
- **파이프라인 설정을 UI에서 수동 관리** — 재현 불가·변경 이력 없음. 파이프라인 정의도 코드로 저장소에.
- **배포 가능 = 배포 완료로 착각** — 파이프라인 성공은 반영의 시작이다. 배포 직후 지표 확인은 [[배포 전략 실전]].

## 관련 문서

- [[00_인프라 허브]] — 08_인프라 진입점
- [[인프라 원리]] — CI/CD 최소선·실행 형태
- [[배포 전략 실전]] — 배포 전략 선택·롤백·피처 플래그·사람 게이트
- [[환경 구성과 시크릿 관리]] — 환경별 설정 주입·시크릿
- [[13_IaC와 CI-CD]] — AWS 구현판 (파이프라인·IaC 불변식)
- [[장애 대응 실전]] — 배포가 사고가 됐을 때