CI/CD: 푸시하면 알아서 배포되는 구조
코드를 푸시할 때마다 자동으로 검사하고, 테스트하고, 빌드하고, 배포하는 CI/CD를 배워요. 실제 파이썬 테스트를 돌리는 작은 파이프라인을 만들어 누군가 "간단하게" 고친 코드가 배포 전에 멈추는 모습을 보고, GitHub Actions 설정을 한 줄씩 읽어요. 비밀 값을 안전하게 다루는 법, 커밋 번호로 이미지를 찍어 언제든 되돌리는 법, 새 버전을 1%의 사용자에게 먼저 내보내 오류가 늘면 자동으로 되돌리는 카나리 배포, 배포 중에도 깨지지 않는 데이터베이스 변경 순서까지 다뤄요.
배포를 손으로 한다고 해 볼게요. 서버에 접속하고, 코드를 받고, 라이브러리를 설치하고, 테스트를 돌리고(바쁘면 건너뛰고), 서버를 다시 시작해요. 순서 하나를 빠뜨리거나, 금요일 밤 피곤할 때 하거나, 그 방법을 아는 사람이 휴가를 가면 사고가 나요. CI/CD는 이 과정을 코드로 적어 두고, 코드를 푸시할 때마다 기계가 똑같이 실행하게 하는 방법이에요.
- CI(Continuous Integration, 지속적 통합): 누가 코드를 푸시하거나 변경 요청(PR)을 올릴 때마다 자동으로 검사하고 테스트해요. 문제를 합치기 전에 찾아요.
- CD(Continuous Delivery/Deployment, 지속적 전달/배포): 검사를 통과한 코드를 자동으로 빌드해서 배포할 준비를 하거나 실제로 배포해요.
파이프라인: 정해진 단계를 차례로
CI/CD는 파이프라인으로 일해요. 단계를 차례로 실행하고, 하나라도 실패하면 거기서 멈춰요. 진짜 파이썬 테스트를 돌리는 작은 파이프라인을 만들어 볼게요.
import pathlib
import subprocess
import sys
import tempfile
import textwrap
repo = pathlib.Path(tempfile.mkdtemp()) # 작은 저장소를 하나 만들어요
(repo / "pricing.py").write_text(textwrap.dedent("""
def total(prices, coupon=0):
subtotal = sum(prices)
return max(subtotal - coupon, 0) # 쿠폰이 더 커도 0원 아래로는 안 내려가요
"""), encoding="utf-8")
(repo / "test_pricing.py").write_text(textwrap.dedent("""
import unittest
from pricing import total
class TotalTest(unittest.TestCase):
def test_sum(self):
self.assertEqual(total([1000, 2000]), 3000)
def test_coupon(self):
self.assertEqual(total([5000], coupon=1000), 4000)
def test_never_negative(self):
self.assertEqual(total([1000], coupon=5000), 0)
"""), encoding="utf-8")
def run(cmd):
p = subprocess.run(cmd, cwd=repo, capture_output=True, text=True, encoding="utf-8")
return p.returncode, p.stdout + p.stderr
STAGES = [
("문법 검사", [sys.executable, "-m", "py_compile", "pricing.py"]),
("테스트", [sys.executable, "-m", "unittest", "-q"]),
("빌드", [sys.executable, "-c", "print('이미지를 만들었다고 쳐요')"]),
]
def pipeline(label):
print(f"[{label}]")
for name, cmd in STAGES:
code, out = run(cmd)
if code != 0:
print(f" {name}: 실패 → 여기서 멈춰요. 배포하지 않아요")
for line in out.splitlines():
if line.startswith(("FAIL:", "AssertionError", "FAILED")):
print(" " + line)
return False
print(f" {name}: 통과")
print(" 배포: 운영 서버에 새 버전을 올려요")
return True
pipeline("처음 버전")
(repo / "pricing.py").write_text(textwrap.dedent("""
def total(prices, coupon=0):
return sum(prices) - coupon # 누군가 '간단하게' 고쳤어요
"""), encoding="utf-8")
pipeline("고친 버전")
[처음 버전]
문법 검사: 통과
테스트: 통과
빌드: 통과
배포: 운영 서버에 새 버전을 올려요
[고친 버전]
문법 검사: 통과
테스트: 실패 → 여기서 멈춰요. 배포하지 않아요
FAIL: test_never_negative (test_pricing.TotalTest.test_never_negative)
AssertionError: -4000 != 0
FAILED (failures=1)
누군가 max를 지워 "더 간단하게" 고쳤어요. 문법은 멀쩡해서 첫 단계는 통과했지만, 테스트가 "쿠폰이 더 크면 -4,000원이 된다"는 버그를 잡았고, 파이프라인은 배포 전에 멈췄어요. 손님에게 돈을 돌려주는 계산서가 나가기 전에요. CI의 가치는 여기 있어요. 사람이 깜빡해도 기계는 매번 같은 검사를 해요. 그리고 테스트가 지켜 주는 건 테스트로 적어 둔 것뿐이라, 버그를 하나 고칠 때마다 그 버그를 잡는 테스트를 하나씩 더해 두는 습관이 쌓이면 파이프라인이 점점 든든해져요.
GitHub Actions로 적어 보기
실제로는 GitHub Actions, GitLab CI 같은 도구가 이 일을 해 줘요. 저장소에 설정 파일만 넣어 두면, 푸시할 때마다 깨끗한 가상 컴퓨터를 빌려 단계를 실행해요. 공개 저장소는 무료이고, 비공개 저장소도 매달 일정 시간까지는 무료로 쓸 수 있어요. .github/workflows/ci.yml에 이렇게 써요.
name: CI
on:
push:
branches: [main]
pull_request: # 변경 요청이 올라올 때마다
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.12", "3.13"] # 두 버전에서 각각 테스트해요
steps:
- uses: actions/checkout@v4 # 저장소의 코드를 받아요
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
cache: pip # 설치한 라이브러리를 저장해 다음에 빨리
- run: pip install -r requirements.txt
- run: python -m unittest -v
deploy:
needs: test # 테스트가 모두 통과해야 시작해요
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- run: docker build -t registry.example.com/todo-api:${{ github.sha }} .
- run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login registry.example.com -u ci --password-stdin
- run: docker push registry.example.com/todo-api:${{ github.sha }}
on: 언제 실행할지예요.main에 푸시할 때와 변경 요청이 올라올 때 실행해요.matrix: 같은 테스트를 파이썬 두 버전에서 동시에 돌려요. "내 컴퓨터의 파이썬에서만 되는" 코드를 잡아요.needs: test와if: 테스트가 통과하고,main에 푸시한 경우에만 배포 단계로 가요. 변경 요청은 테스트만 하고 배포하지 않아요.${{ github.sha }}: 커밋 번호로 이미지 이름표를 붙여요. 이유는 조금 뒤에 봐요.secrets.REGISTRY_TOKEN: 이미지 저장소의 비밀번호는 설정 파일에 적지 않고, 저장소 설정의 Secrets에 따로 넣어 둔 걸 불러와요.uses:뒤의 버전 번호(@v4)는 시간이 지나면 새 버전이 나와요. 쓸 때 각 도구의 저장소에서 최신 버전을 확인하세요.
이 가이드북처럼 정적 사이트를 올리는 호스팅 서비스 중에는, 저장소만 연결해 두면 푸시할 때마다 알아서 빌드하고 배포해 주는 곳이 많아요. 그 서비스 안에서 같은 파이프라인이 돌고 있는 거예요.
비밀 값 다루기
파이프라인은 배포를 하니 강력한 열쇠(서버 접속, 이미지 저장소, 클라우드 계정)를 쥐어요. 그만큼 조심해야 해요.
- 설정 파일에 비밀을 적지 않아요. 설정 파일은 저장소에 그대로 남아 모두가 볼 수 있어요. CI 도구의 비밀 저장 기능에 넣어요.
- 기록에 찍지 않아요. CI 도구는 비밀 값을 기록에서
***로 가려 주지만, 비밀을 다른 모양으로 바꿔 찍으면(앞 몇 글자만, 거꾸로 등) 가리지 못해요. 위의--password-stdin처럼 명령줄 인자 대신 입력으로 넘겨요. - 필요한 만큼만 주어요. 배포용 열쇠는 그 일에 필요한 권한만 가지게 만들고, 사람이 쓰는 열쇠와 나눠요.
- 모르는 사람의 변경 요청에는 비밀을 주지 않아요. 남이 올린 변경 요청의 코드는 무엇이든 실행할 수 있으니까요. GitHub Actions는 다른 사람의 복사본(fork)에서 온 변경 요청에는 기본으로 비밀을 넘기지 않아요.
커밋 번호로 이름표 붙이기
이미지에 latest 같은 이름표를 붙이면 "지금 운영 중인 게 정확히 어느 코드인지" 알기 어렵고, 되돌리기도 어려워요. 커밋 번호를 이름표로 쓰면 이미지 하나가 코드 한 시점과 정확히 짝지어져요.
- 지금 운영 중인 이미지의 이름표를 보면 어떤 커밋인지 바로 알아요.
- 문제가 생기면 바로 앞의 이미지로 다시 배포하면 끝이에요. 다시 빌드할 필요가 없어요. 이미지는 바뀌지 않는 상자라, 예전 이미지는 예전 모습 그대로 돌아가요.
- 같은 이미지를 테스트 서버에서 검증한 뒤 그대로 운영 서버에 올려요. "테스트 서버에서는 됐는데"가 줄어요.
조금씩 내보내기: 카나리 배포
테스트가 모든 버그를 잡지는 못해요. 실제 사용자의 데이터와 사용 방식에서만 드러나는 버그도 있어요. 그래서 새 버전을 일부 사용자에게만 먼저 내보내고, 오류가 늘지 않는지 지켜보며 비율을 늘려요. 탄광에서 유독 가스를 먼저 알아채려고 데려갔던 카나리아 새의 이름을 따서 카나리 배포라고 해요. 새 버전에 숨은 버그가 있을 때 결과를 비교해 볼게요.
TOTAL = 10_000 # 그 시간 동안 들어온 요청
ERROR_RATE = {"지금 버전": 0.01, "새 버전": 0.08} # 새 버전에 숨은 버그가 있어요
LIMIT = 0.02 # 오류율이 2%를 넘으면 되돌려요
def errors(version, requests):
return round(requests * ERROR_RATE[version])
print("한 번에 모두 바꾸면 오류:", errors("새 버전", TOTAL), "개")
for percent in (1, 5, 25, 50, 100): # 새 버전에 보내는 비율을 조금씩 늘려요
to_new = TOTAL * percent // 100
bad = errors("새 버전", to_new)
print(f"새 버전 {percent}%: 요청 {to_new}개 중 오류 {bad}개 ({bad / to_new:.0%})")
if bad / to_new > LIMIT:
print(f" 기준 {LIMIT:.0%}를 넘었어요 → 모두 지금 버전으로 되돌려요. 피해를 본 요청 {bad}개")
break
한 번에 모두 바꾸면 오류: 800 개
새 버전 1%: 요청 100개 중 오류 8개 (8%)
기준 2%를 넘었어요 → 모두 지금 버전으로 되돌려요. 피해를 본 요청 8개
한 번에 모두 바꿨다면 800개의 요청이 실패했을 버그를, 1%만 먼저 보내서 8개 만에 알아채고 되돌렸어요. 실제로는 "1% 단계에서 최소 몇 분, 최소 몇 개의 요청을 보고 판단하라"는 조건을 함께 둬요. 요청 몇 개만으로 판단하면 우연에 휘둘리거든요. 확률과 통계 트랙에서 본 표본 크기 이야기예요. 비슷한 방식으로, 똑같은 운영 환경을 두 벌 두고 앞단의 연결을 한 번에 바꿔 끼우는 블루 그린 배포도 있어요. 되돌릴 때도 연결만 다시 바꾸면 돼서 빨라요.
데이터베이스 변경은 두 번에 나눠서
코드는 되돌리면 그만이지만, 데이터베이스는 그렇지 않아요. 그리고 롤링 배포나 카나리 배포 중에는 예전 코드와 새 코드가 동시에 같은 데이터베이스를 써요. 그래서 칸의 이름을 바꾸는 일도 한 번에 하면 안 돼요. 예전 코드가 옛 이름을 찾다가 오류를 내니까요. 넓히고 나서 좁히는 순서로 나눠요.
- 넓히기: 새 칸을 더하고, 새 코드는 두 칸에 모두 쓰게 배포해요. 예전 코드는 옛 칸을 그대로 써요.
- 예전 데이터를 새 칸으로 옮겨요.
- 새 코드가 새 칸만 읽게 배포해요. 모든 서버가 새 코드로 바뀐 걸 확인해요.
- 좁히기: 아무도 옛 칸을 쓰지 않게 된 뒤에 옛 칸을 지워요.
번거롭지만, 이렇게 하면 어느 단계에서 멈추거나 코드를 되돌려도 서비스가 깨지지 않아요. 데이터베이스 변경도 코드처럼 파일(마이그레이션)로 적어 저장소에 두고, 파이프라인이 순서대로 적용하게 해요.
좋은 파이프라인의 조건
- 빨라야 해요. 10분이 넘으면 사람들이 기다리다 지쳐 검사를 우회하기 시작해요. 라이브러리를 캐시하고, 서로 상관없는 단계는 동시에 돌려요.
- 믿을 수 있어야 해요. 가끔 아무 이유 없이 실패하는 테스트는 바로 고쳐요. "원래 가끔 실패해" 하고 다시 돌리는 습관이 들면, 진짜 실패도 그냥 넘기게 돼요.
- 같은 결과를 내야 해요. 언제 돌려도 같은 결과가 나오도록 라이브러리와 바탕 이미지의 버전을 정해 둬요.
- 막아야 할 때는 막아요.
main에는 파이프라인을 통과한 변경 요청만 합칠 수 있게 저장소 설정에서 보호 규칙을 걸어요. - 실패를 알려 줘요. 배포가 실패하면 메신저나 메일로 바로 알려 받아요.
실습
- 파이프라인 예제에 "코드 스타일 검사" 단계를 더해 보세요. 예를 들어
print(가 들어간 줄이 있으면 실패하게 해 보세요. - 고친 버전의 버그를 바로잡고, "쿠폰이 0원일 때"를 확인하는 테스트를 하나 더해 파이프라인이 다시 배포까지 가는지 확인해 보세요.
- 카나리 예제에서 새 버전의 오류율이 1.5%라면 어떻게 되나요? 지금 버전보다 나빠졌는데도 되돌리지 않는 게 맞을까요? 기준을 "지금 버전보다 몇 배 이상 나빠지면"으로 바꿔 보세요.
- 카나리 예제에 "단계마다 요청이 500개 이상 모였을 때만 판단한다"는 조건을 더해 보세요. 1% 단계는 어떻게 되나요?
- GitHub에 연습용 저장소를 만들고, 위 설정에서
deploy일을 뺀test일만 넣어 푸시해 보세요. Actions 탭에서 단계별 기록을 확인할 수 있어요.
자주 하는 실수
- 배포를 손으로 한다. 순서를 빠뜨리거나, 할 줄 아는 사람이 없을 때 멈춰요.
- 테스트가 실패해도 배포할 수 있게 둔다. 파이프라인이 막아 주지 않으면 결국 누군가 급할 때 건너뛰어요.
- 설정 파일에 비밀을 적거나 기록에 찍는다. CI 도구의 비밀 저장 기능을 쓰고, 명령줄 인자로 넘기지 않아요.
latest로만 이미지를 관리한다. 무엇이 운영 중인지, 어디로 되돌릴지 알 수 없어요. 커밋 번호를 붙여요.- 한 번에 모든 사용자에게 내보낸다. 테스트가 놓친 버그가 모두에게 닿아요. 조금씩 내보내고 지켜봐요.
- 칸 이름 바꾸기를 한 번에 한다. 배포 중에 예전 코드가 깨져요. 넓히고, 옮기고, 좁혀요.
- 가끔 실패하는 테스트를 내버려 둔다. 진짜 실패를 알아채지 못하게 돼요.
점검 문제
- CI와 CD는 각각 무엇을 자동으로 하나요?
- 파이프라인이 실패한 단계에서 멈추는 것이 중요한 이유는?
- 예제에서 문법 검사는 통과했는데 테스트에서 걸린 이유는?
- GitHub Actions 설정에서
needs: test와if조건은 무엇을 보장하나요? - 비밀 값을 설정 파일에 적으면 안 되는 이유와, 남의 변경 요청에 비밀을 주지 않는 이유는?
- 이미지에 커밋 번호로 이름표를 붙이면 좋은 점 두 가지는?
- 카나리 배포는 어떻게 피해를 줄이나요? 판단할 때 함께 정해야 할 조건은?
- 배포 중에 칸 이름을 한 번에 바꾸면 안 되는 이유와, 대신 쓰는 순서는?
정답
- CI는 푸시나 변경 요청마다 자동으로 검사하고 테스트해요. CD는 통과한 코드를 자동으로 빌드해서 배포할 준비를 하거나 실제로 배포해요.
- 앞 단계에서 문제가 드러났는데 계속 진행하면 버그가 든 코드가 배포되기 때문이에요. 멈추면 문제가 사용자에게 닿기 전에 막혀요.
- 코드가 파이썬 문법으로는 올바르지만, 쿠폰이 더 클 때 음수가 되는 잘못된 동작을 하기 때문이에요. 동작의 옳고 그름은 테스트만 알아낼 수 있어요.
- 테스트가 모두 통과했을 때만, 그리고
main에 푸시한 경우에만 배포 단계가 실행되게 보장해요. - 설정 파일은 저장소에 남아 볼 수 있는 사람 모두에게 비밀이 드러나기 때문이에요. 남의 변경 요청에는 아무 코드나 들어 있을 수 있어서, 비밀을 주면 그 코드가 비밀을 빼돌릴 수 있기 때문이에요.
- 지금 운영 중인 이미지가 정확히 어떤 코드인지 알 수 있고, 문제가 생기면 다시 빌드하지 않고 바로 앞의 이미지로 되돌릴 수 있어요.
- 새 버전을 일부 사용자에게만 먼저 보내서, 오류가 늘면 그 일부만 피해를 보고 되돌려요. 우연에 휘둘리지 않도록 단계마다 최소 시간과 최소 요청 수를 함께 정해요.
- 배포 중에는 예전 코드와 새 코드가 함께 돌아서, 예전 코드가 사라진 옛 칸을 찾다가 오류를 내기 때문이에요. 새 칸을 더하고(넓히기), 데이터를 옮기고, 새 코드로 모두 바꾼 뒤, 옛 칸을 지워요(좁히기).
다음 강의
이제 푸시하면 알아서 검사하고 배포돼요. 하지만 배포가 끝이 아니에요. 서비스가 지금 잘 돌고 있는지, 느려지고 있지는 않은지, 무슨 일이 있었는지 알 수 있어야 하고, 최악의 순간에 데이터를 되살릴 수 있어야 해요. 서버 트랙의 마지막 강의에서는 모니터링, 로그, 백업을 다뤄요.