CI/CD: 푸시하면 알아서 배포되는 구조

코드를 푸시할 때마다 자동으로 검사하고, 테스트하고, 빌드하고, 배포하는 CI/CD를 배워요. 실제 파이썬 테스트를 돌리는 작은 파이프라인을 만들어 누군가 "간단하게" 고친 코드가 배포 전에 멈추는 모습을 보고, GitHub Actions 설정을 한 줄씩 읽어요. 비밀 값을 안전하게 다루는 법, 커밋 번호로 이미지를 찍어 언제든 되돌리는 법, 새 버전을 1%의 사용자에게 먼저 내보내 오류가 늘면 자동으로 되돌리는 카나리 배포, 배포 중에도 깨지지 않는 데이터베이스 변경 순서까지 다뤄요.

중급강의 5 / 6약 13분

배포를 손으로 한다고 해 볼게요. 서버에 접속하고, 코드를 받고, 라이브러리를 설치하고, 테스트를 돌리고(바쁘면 건너뛰고), 서버를 다시 시작해요. 순서 하나를 빠뜨리거나, 금요일 밤 피곤할 때 하거나, 그 방법을 아는 사람이 휴가를 가면 사고가 나요. 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% 단계에서 최소 몇 분, 최소 몇 개의 요청을 보고 판단하라"는 조건을 함께 둬요. 요청 몇 개만으로 판단하면 우연에 휘둘리거든요. 확률과 통계 트랙에서 본 표본 크기 이야기예요. 비슷한 방식으로, 똑같은 운영 환경을 두 벌 두고 앞단의 연결을 한 번에 바꿔 끼우는 블루 그린 배포도 있어요. 되돌릴 때도 연결만 다시 바꾸면 돼서 빨라요.

데이터베이스 변경은 두 번에 나눠서

코드는 되돌리면 그만이지만, 데이터베이스는 그렇지 않아요. 그리고 롤링 배포나 카나리 배포 중에는 예전 코드와 새 코드가 동시에 같은 데이터베이스를 써요. 그래서 칸의 이름을 바꾸는 일도 한 번에 하면 안 돼요. 예전 코드가 옛 이름을 찾다가 오류를 내니까요. 넓히고 나서 좁히는 순서로 나눠요.

  1. 넓히기: 새 칸을 더하고, 새 코드는 두 칸에 모두 쓰게 배포해요. 예전 코드는 옛 칸을 그대로 써요.
  2. 예전 데이터를 새 칸으로 옮겨요.
  3. 새 코드가 새 칸만 읽게 배포해요. 모든 서버가 새 코드로 바뀐 걸 확인해요.
  4. 좁히기: 아무도 옛 칸을 쓰지 않게 된 뒤에 옛 칸을 지워요.

번거롭지만, 이렇게 하면 어느 단계에서 멈추거나 코드를 되돌려도 서비스가 깨지지 않아요. 데이터베이스 변경도 코드처럼 파일(마이그레이션)로 적어 저장소에 두고, 파이프라인이 순서대로 적용하게 해요.

좋은 파이프라인의 조건

  • 빨라야 해요. 10분이 넘으면 사람들이 기다리다 지쳐 검사를 우회하기 시작해요. 라이브러리를 캐시하고, 서로 상관없는 단계는 동시에 돌려요.
  • 믿을 수 있어야 해요. 가끔 아무 이유 없이 실패하는 테스트는 바로 고쳐요. "원래 가끔 실패해" 하고 다시 돌리는 습관이 들면, 진짜 실패도 그냥 넘기게 돼요.
  • 같은 결과를 내야 해요. 언제 돌려도 같은 결과가 나오도록 라이브러리와 바탕 이미지의 버전을 정해 둬요.
  • 막아야 할 때는 막아요. main에는 파이프라인을 통과한 변경 요청만 합칠 수 있게 저장소 설정에서 보호 규칙을 걸어요.
  • 실패를 알려 줘요. 배포가 실패하면 메신저나 메일로 바로 알려 받아요.

실습

  1. 파이프라인 예제에 "코드 스타일 검사" 단계를 더해 보세요. 예를 들어 print(가 들어간 줄이 있으면 실패하게 해 보세요.
  2. 고친 버전의 버그를 바로잡고, "쿠폰이 0원일 때"를 확인하는 테스트를 하나 더해 파이프라인이 다시 배포까지 가는지 확인해 보세요.
  3. 카나리 예제에서 새 버전의 오류율이 1.5%라면 어떻게 되나요? 지금 버전보다 나빠졌는데도 되돌리지 않는 게 맞을까요? 기준을 "지금 버전보다 몇 배 이상 나빠지면"으로 바꿔 보세요.
  4. 카나리 예제에 "단계마다 요청이 500개 이상 모였을 때만 판단한다"는 조건을 더해 보세요. 1% 단계는 어떻게 되나요?
  5. GitHub에 연습용 저장소를 만들고, 위 설정에서 deploy 일을 뺀 test 일만 넣어 푸시해 보세요. Actions 탭에서 단계별 기록을 확인할 수 있어요.

자주 하는 실수

  • 배포를 손으로 한다. 순서를 빠뜨리거나, 할 줄 아는 사람이 없을 때 멈춰요.
  • 테스트가 실패해도 배포할 수 있게 둔다. 파이프라인이 막아 주지 않으면 결국 누군가 급할 때 건너뛰어요.
  • 설정 파일에 비밀을 적거나 기록에 찍는다. CI 도구의 비밀 저장 기능을 쓰고, 명령줄 인자로 넘기지 않아요.
  • latest로만 이미지를 관리한다. 무엇이 운영 중인지, 어디로 되돌릴지 알 수 없어요. 커밋 번호를 붙여요.
  • 한 번에 모든 사용자에게 내보낸다. 테스트가 놓친 버그가 모두에게 닿아요. 조금씩 내보내고 지켜봐요.
  • 칸 이름 바꾸기를 한 번에 한다. 배포 중에 예전 코드가 깨져요. 넓히고, 옮기고, 좁혀요.
  • 가끔 실패하는 테스트를 내버려 둔다. 진짜 실패를 알아채지 못하게 돼요.

점검 문제

  1. CI와 CD는 각각 무엇을 자동으로 하나요?
  2. 파이프라인이 실패한 단계에서 멈추는 것이 중요한 이유는?
  3. 예제에서 문법 검사는 통과했는데 테스트에서 걸린 이유는?
  4. GitHub Actions 설정에서 needs: test와 if 조건은 무엇을 보장하나요?
  5. 비밀 값을 설정 파일에 적으면 안 되는 이유와, 남의 변경 요청에 비밀을 주지 않는 이유는?
  6. 이미지에 커밋 번호로 이름표를 붙이면 좋은 점 두 가지는?
  7. 카나리 배포는 어떻게 피해를 줄이나요? 판단할 때 함께 정해야 할 조건은?
  8. 배포 중에 칸 이름을 한 번에 바꾸면 안 되는 이유와, 대신 쓰는 순서는?

정답

  1. CI는 푸시나 변경 요청마다 자동으로 검사하고 테스트해요. CD는 통과한 코드를 자동으로 빌드해서 배포할 준비를 하거나 실제로 배포해요.
  2. 앞 단계에서 문제가 드러났는데 계속 진행하면 버그가 든 코드가 배포되기 때문이에요. 멈추면 문제가 사용자에게 닿기 전에 막혀요.
  3. 코드가 파이썬 문법으로는 올바르지만, 쿠폰이 더 클 때 음수가 되는 잘못된 동작을 하기 때문이에요. 동작의 옳고 그름은 테스트만 알아낼 수 있어요.
  4. 테스트가 모두 통과했을 때만, 그리고 main에 푸시한 경우에만 배포 단계가 실행되게 보장해요.
  5. 설정 파일은 저장소에 남아 볼 수 있는 사람 모두에게 비밀이 드러나기 때문이에요. 남의 변경 요청에는 아무 코드나 들어 있을 수 있어서, 비밀을 주면 그 코드가 비밀을 빼돌릴 수 있기 때문이에요.
  6. 지금 운영 중인 이미지가 정확히 어떤 코드인지 알 수 있고, 문제가 생기면 다시 빌드하지 않고 바로 앞의 이미지로 되돌릴 수 있어요.
  7. 새 버전을 일부 사용자에게만 먼저 보내서, 오류가 늘면 그 일부만 피해를 보고 되돌려요. 우연에 휘둘리지 않도록 단계마다 최소 시간과 최소 요청 수를 함께 정해요.
  8. 배포 중에는 예전 코드와 새 코드가 함께 돌아서, 예전 코드가 사라진 옛 칸을 찾다가 오류를 내기 때문이에요. 새 칸을 더하고(넓히기), 데이터를 옮기고, 새 코드로 모두 바꾼 뒤, 옛 칸을 지워요(좁히기).

다음 강의

이제 푸시하면 알아서 검사하고 배포돼요. 하지만 배포가 끝이 아니에요. 서비스가 지금 잘 돌고 있는지, 느려지고 있지는 않은지, 무슨 일이 있었는지 알 수 있어야 하고, 최악의 순간에 데이터를 되살릴 수 있어야 해요. 서버 트랙의 마지막 강의에서는 모니터링, 로그, 백업을 다뤄요.