배포 자동화·롤백·스마트 빌드 — 초기에 안 만든 후회

신진형 · 에스엘파워 · 2026.06.17

처음엔 손으로 배포했습니다. 한 번 할 땐 5분이면 되니까요. 그런데 하루에 몇 번씩, 몇 주를 그렇게 하다 보면 그 5분들이 쌓여 거대한 낭비가 됩니다. 더 무서운 건 따로 있습니다 — 손 배포는 어느 날 조용히 망가진 걸 올려놓고도 모릅니다. 이 글은 “배포가 뭔지”부터 “왜 빌드 성공이 배포 안전을 보장하지 않는지”까지, 처음 개발하는 분도 알 수 있게 풀어 쓴 기록입니다.

배포가 뭔가 — 그리고 왜 매번 하나

용어부터 짚겠습니다. “배포(deploy)“는 제가 고친 코드를 실제 서버에 올려 사용자가 쓸 수 있게 만드는 일입니다. 코드를 한 줄 고쳤다고 끝이 아닙니다. 그 코드를 서버로 옮기고, 컴퓨터가 실행할 형태로 번역(빌드)하고, 돌고 있던 프로그램을 새 버전으로 다시 띄워야(재시작) 비로소 사용자에게 닿습니다.

활발히 개발할 땐 하루에도 여러 번 배포합니다. 그래서 “한 번에 5분”은 함정입니다. 5분 × 하루 5번 × 한 달이면, 단순 대기 시간만으로도 며칠이 증발합니다. 그런데 시간보다 더 큰 문제는 안전이었습니다.

손 배포의 세 가지 문제

초기 배포는 전부 수작업이었습니다. 코드를 올리고, 빌드하고, 프로세스를 재시작합니다. 이게 반복되면 세 가지가 또렷이 드러납니다.

느리다 — 매번 전체를 다시 빌드합니다. 화면 한 줄만 고쳐도 백엔드까지 통째로 다시 빌드하느라 몇 분을 기다립니다.
위험하다 — 빌드가 사실 실패했는데, 그 전에 성공했던 결과물이 그대로 돌고 있는 일이 생깁니다. 화면은 멀쩡해 보여서 더 무섭습니다. “올렸으니 됐겠지”가 거짓이 되는 순간입니다.
되돌릴 수 없다 — 새 버전이 깨졌을 때, 직전의 멀쩡한 버전으로 돌아가는 “버튼”이 없습니다. 깨진 채로 허둥지둥 원인을 찾아야 합니다.

실제로 이런 사고가 났습니다

화면 코드를 고치고 배포합니다. 스크립트는 “성공” 초록불.
서버에 curl로 확인 → “200 OK”. “오케이, 됐네” 하고 자리를 뜹니다.
그런데 사용자가 브라우저로 들어가면 — 스타일이 다 빠져 글자만 덩그러니 떠 있습니다. 정적 자산 복사 단계가 빠졌던 것.
curl은 “페이지를 줬다”는 사실만 확인했지, “그 페이지가 제대로 보이는가”는 모릅니다. 깨짐을 한참 뒤에야 사람이 발견합니다.

뒤늦게 만든 것들

아픈 일을 몇 번 겪고 나서야 배포 파이프라인을 제대로 짰습니다. 커밋 메시지에 그 결심이 그대로 남아 있습니다 — “파이프라인 근본 해결: 헬스 엔드포인트 + fail-fast + 자동 롤백”. 핵심 장치는 셋이었습니다.

	그때 (손 배포)	지금 (자동 파이프라인)
빌드	전체 재빌드 → 느림	스마트 빌드: 변경된 모듈만 다시 빌드
실패 대응	빌드 실패해도 옛 버전이 그대로 돎	fail-fast: 빌드·헬스 체크 실패 시 즉시 멈춤
되돌리기	깨지면 되돌릴 길 없음	자동 롤백: 건강하지 않으면 직전 정상본으로 복귀

자동 파이프라인의 핵심은 배포 직후의 헬스체크 갈림길입니다. 정상이면 새 버전을 유지하고, 어긋나면 즉시 직전 정상본으로 롤백합니다. 손 배포에는 이 갈림길 자체가 없어, "조용히 망가진 배포"가 그대로 살아 있었습니다.

장치	해결한 손 배포 문제	한 줄 요약
스마트 빌드	① 느리다 (매번 전체 재빌드)	바뀐 것만 다시 빌드
fail-fast + 헬스체크	② 위험하다 (조용히 망가진 배포)	어긋나면 즉시 멈춤
자동 롤백	③ 되돌릴 수 없다	직전 정상본으로 자동 복귀

세 장치가 각각 손 배포의 세 문제와 정확히 짝을 이룹니다. 우연이 아닙니다 — 아팠던 지점을 하나씩 적어 두고, 그 통증마다 장치를 하나씩 붙인 것입니다. 자동화는 거창한 청사진에서 나오지 않았습니다. 겪은 사고의 목록에서 나왔습니다.

그래도 사람 눈은 남겨 둔다

자동화를 갖춘 뒤에도 한 가지 규칙은 끝까지 지켰습니다 — 배포 후엔 실제 브라우저로 한 번 들어가 봅니다. 앞서 본 “스타일이 다 빠진 화면” 같은 시각적 깨짐은, 자동 헬스체크가 “200 OK”로 통과시켜 버리기 때문입니다. 헬스체크는 “서버가 응답하는가”는 알지만 “그 화면이 사람 눈에 제대로 보이는가”는 모릅니다.

그래서 자동화의 위치를 이렇게 정리했습니다 — 자동화는 사람을 대체하는 게 아니라, 사람이 놓치는 걸 잡아주는 보조망입니다. 그리고 사람은 자동화가 못 보는 마지막 한 칸 — 눈으로 보는 검증 — 을 맡습니다. 둘은 역할이 다르지, 어느 한쪽이 다른 쪽을 없애지 않습니다.

점검 종류	잡아내는 것	못 잡는 것
자동 헬스체크 (기계)	서버 죽음 · 버전 불일치	스타일 깨짐 같은 시각적 문제
브라우저 실접속 (사람)	화면이 제대로 보이는가	매번 사람이 해야 함(비용)

처음부터 했어야 할 일

이 모든 장치 — 스마트 빌드, fail-fast, 자동 롤백 — 는 사실 “두 번째 배포 전에” 만들었어야 했습니다. “지금은 손으로 하고 자동화는 나중에”라는 생각이 정확히 이 후회를 만들었습니다. 그 “나중”은 늘 더 비싼 모습으로, 보통은 사고가 한 번 터진 직후에 찾아왔습니다.

거창한 도구가 필요한 일도 아니었습니다. 손 배포 다섯 번이면 자동화 스크립트 하나 짤 시간이 납니다. 그 한 번의 투자가 이후 수십 번의 배포를 빠르고 안전하게 만듭니다. 배포는 “개발이 끝난 뒤 고민할 것”이 아니라 개발 초기부터 함께 설계할 것이라는 게, 비싸게 배운 결론입니다.

이 배포가 올라가는 서버·프록시 이야기는 〈서버를 세 번 옮긴 이야기〉와 〈리버스 프록시는 Caddy로〉에서, 자동 롤백과 짝을 이루는 감사·백업은 〈감사로그와 백업의 자리〉에서 이어집니다. 전체 그림은 〈사례연구: SL.AIMS〉에 있습니다.