이런 기법을 통틀어 테스트 영향 분석(test impact analysis)이라고 하는데, testmon은 Python에서 이걸 무료 오픈소스로 쓰는 방법입니다. git과는 아무 상관이 없습니다. 커밋을 했든 안 했든, 지난 실행에서 본 것과 비교할 뿐입니다.

이번 주에 제 마켓플레이스 앱의 Python 테스트에 이걸 넣었습니다. 속도 자체가 목적은 아니었습니다.

넣은 이유

#

기능 요청은 대개 작습니다. 화면 하나, 엔드포인트 하나, 다르게 동작해야 하는 규칙 하나. 그런데 테스트 스위트를 통째로 돌리다 보니 요청마다 실제보다 커졌습니다. 스위트는 Django 테스트 2,248개로, 프로세스 넷이면 3분 반쯤, 하나면 11분이 걸립니다. 그런데 수정할 때마다 이걸 전부 돌렸습니다. 그 거의 전부가 요청과는 아무 상관 없는 것을 확인하는데도요. 상관없는 테스트가 실패하거나 그냥 실행이 오래 걸리면 기능은 기다려야 했습니다. 기능 요청과 무관한 사정에 발이 묶인 건데, 발목을 잡은 게 다름 아닌 제 테스트 스위트였죠.

그렇다고 다른 길이 더 나은 것도 아니었습니다. 전체 실행을 건너뛰고, 변경을 다루는 테스트 파일이 어느 건지 짐작하고, 가끔은 틀리는 겁니다. 빠르긴 해도 정확하지는 않습니다. 그리고 테스트 없이 내보낸 변경은 같은 기능 요청을 두 번 처리하게 만듭니다.

제가 기다리는 테스트는 변경이 닿을 수 있는 테스트와 정확히 같아야 합니다. 더도 덜도 말고요. testmon은 그 집합을 짐작이 아니라 기록으로 줍니다. 전체 스위트는 여전히 CI에서 돕니다. 거기서는 제가 다음에 할 작업을 붙잡지 않습니다.

돌릴 테스트를 고르는 방식

#

testmon은 Python 파일 하나를 여러 블록으로 나눕니다. 모듈 최상위, 각 클래스, 각 함수가 블록이 되고, 중첩 함수의 본문은 바깥 블록에서 잘라 냅니다. 저장하는 건 블록마다의 체크섬이고, 코드 자체는 저장하지 않습니다. 테스트가 도는 동안 coverage.py가 실행된 줄을 기록하면, testmon은 그 줄이 어느 블록에 속하는지 적어 둡니다. 정적 분석도 없고, import를 보고 짐작하지도 않습니다. 테스트는 정확히 자기가 실행한 블록에만 의존합니다.

이런 모듈이 있다고 해 보죠.

# pricing.py
def subtotal(items):
    return sum(item.price * item.quantity for item in items)

def discount(total, code):
    if code == "WELCOME10":
        return total * 0.9
    return total

subtotal()만 호출하는 테스트는 모듈 최상위와 subtotal의 본문에 의존합니다. discount()를 어떻게 고쳐 쓰든 testmon은 그 테스트를 다시 돌리지 않습니다. discount의 줄을 하나도 실행한 적이 없으니까요. 반대로 subtotal 안에서 글자 하나만 바꿔도, 결과가 달라질 수 없는 변경이라 해도 테스트는 다시 돕니다. testmon은 부작용을 두고 머리를 굴리지 않습니다. 실행한 블록이 바뀌었으면 다시 돌 뿐입니다.

코드를 둘러싼 환경도 추적합니다. 기록에는 Python 버전, 그리고 설치된 패키지와 그 버전이 들어갑니다. 환경 변수는 보지 않습니다. 같은 코드를 설정 모듈 두 개로 돌린다면 --testmon-env(8단계)로 이름을 붙여 주지 않으면 기록 하나를 같이 쓰게 됩니다. Django를 업그레이드하면 Django를 건드린 테스트가 전부 다시 영향을 받는데, Django 앱에서는 그게 곧 전부입니다.

보지 못하는 것

#

testmon이 추적하는 건 테스트가 실행하는 Python입니다. 테스트가 읽는 다른 파일, 그러니까 템플릿, JSON, 텍스트, 그 밖에 디스크에 있는 무엇이든 추적하지 않습니다. 네트워크 너머의 서비스도 추적하지 않습니다. 그리고 테스트가 시작되기 전에 한 번 실행되는 것은 어느 특정 테스트에도 묶을 수 없습니다.

Django 프로젝트라면 우선 마이그레이션입니다. 테스트 데이터베이스를 만들 때 한 번 실행되기 때문에 어느 테스트의 기록에도 들어가지 않습니다(아래 래퍼는 새 마이그레이션이 생기면 테스트 데이터베이스를 다시 만듭니다). 다음은 설정과 시작 코드로, pytest가 시작하는 동안 어느 한 테스트의 바깥에서 실행됩니다. 그리고 템플릿과 데이터 파일입니다. 템플릿은 Python이 아니라서, 고쳐도 그걸 렌더링하는 테스트가 하나도 다시 돌지 않습니다.

제 스위트에는 이런 게 몇 가지 더 있습니다. 어떤 테스트는 모바일 앱의 테스트와 함께 쓰는 픽스처 JSON 파일을 읽습니다. 어떤 테스트는 빌드된 웹 번들을 확인하고, 또 어떤 테스트는 같은 저장소에서 생성하는 정적 사이트의 결과물을 확인합니다. 이 중 무엇을 바꾸든 testmon은 태연하게 돌릴 게 없다고 할 겁니다. 아래 방법에서 testmon을 스크립트로 감싸고, 이런 파일이 바뀌면 알아채서 전부 돌리게 하는 이유가 이겁니다.

Django 프로젝트에 넣는 방법

#

아래 단계는 pytest와 pytest-django를 쓰고, 의존성은 uv로 관리한다고 가정합니다. pip를 쓴다면 uv add --dev를 pip install로 바꾸고 uv run은 빼세요.

1. 설치합니다.

uv add --dev pytest-testmon

2. pytest로 스위트를 돌릴 수 있는지 확인합니다. testmon은 pytest 플러그인이라 python manage.py test에서는 아무 일도 하지 않습니다. pytest-django에는 설정 모듈과 테스트가 쓰는 파일 패턴을 알려 줘야 합니다.

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
python_files = tests.py test_*.py *_tests.py
python_classes = Test* *Tests *TestCase

지금까지 Django의 러너로만 스위트를 돌렸다면, testmon을 넣기 전에 pytest로 한 번 돌려 보고 결과가 달라지는 부분부터 고치세요. 그러지 않으면 두 가지를 한꺼번에 디버깅하게 됩니다.

3. 기록은 git에 넣지 않습니다. testmon은 pytest 루트 디렉터리에 .testmondata를 씁니다. SQLite 데이터베이스라서 옆에 -shm과 -wal 파일도 생기고, 아래 스크립트가 스탬프 파일을 하나 더 만듭니다. 패턴 하나로 전부 처리됩니다.

# .gitignore
.testmondata*

4. 스위트 전체를 한 번 기록합니다. testmon은 모든 테스트가 도는 걸 한 번 보기 전까지는 아무것도 고를 수 없습니다.

uv run pytest --testmon

새로 받은 체크아웃에서는 이 첫 실행이 프로세스 하나로 스위트 전체를 돕니다. 제 경우엔 테스트 2,248개에 12분쯤 걸립니다. 그다음부터는 같은 명령이 영향받는 테스트만 돌립니다. 바뀐 게 없으면 아무것도 돌리지 않습니다.

주의할 점이 두 가지 있습니다. testmon 2.2.0 이하에서는 pytest의 캐시 플러그인이 필요합니다. 처음에는 -p no:cacheprovider를 붙여 돌렸다가 KeyError: 'lf'로 죽었습니다(2.3.0은 --lf가 없으면 미지정으로 처리합니다). 그리고 Python 3.14 이상이라면 기록하기 전에 COVERAGE_CORE=ctrace를 설정하세요. 이유는 뒤에 나오는 “초록불처럼 보였던 버그"에서 설명합니다. 아래 스크립트에서 가장 중요한 한 줄입니다.

업데이트(11월 7일): 11월 2일에 나온 testmon 2.3.0은 coverage의 C 트레이서를 스스로 강제하므로, 그 버전에서는 이 export가 혹시 몰라 두는 줄이 됩니다. 2.2.0 이하라면 그대로 두세요. 그리고 일부러 망가뜨려 확인하는 검사는 버전과 상관없이 계속하세요.

5. testmon이 보지 못하는 파일까지 챙기도록 감쌉니다. 매일 안심하고 쓸 수 있게 해 주는 게 이 부분입니다. 스크립트는 지난 실행이 시작된 시점의 스탬프 파일을 남겨 둡니다. testmon이 추적할 수 없는 파일 중 스탬프보다 새로운 게 하나라도 있으면 전부 돌리고 처음부터 다시 기록합니다. 새 마이그레이션이라면 테스트 데이터베이스만 다시 만듭니다. 그 밖에는 testmon에게 고르게 맡깁니다. 줄인 예제입니다.

#!/usr/bin/env bash
# scripts/test-changed.sh: the tests a change can affect, or all when in doubt.
#   scripts/test-changed.sh            # affected tests
#   scripts/test-changed.sh --all      # everything, re-recorded
#   scripts/test-changed.sh -k orders  # anything else goes to pytest
set -euo pipefail
cd "$(dirname "$0")/.."

# coverage's C tracer: from Python 3.14 coverage defaults to sys.monitoring,
# which reports a line only the first time a process runs it, so testmon
# would credit each line to one test. Changing this means --all.
export COVERAGE_CORE=ctrace

STAMP=.testmondata.started
full=false
rebuild=false
if [ "${1:-}" = "--all" ]; then
    full=true; shift
elif [ ! -f .testmondata ] || [ ! -f "$STAMP" ]; then
    echo "No record yet: running everything once."
    full=true
else
    # Changed since the last run started, and not traceable per test:
    # anything that isn't Python, plus settings and conftest.
    newer="$(find myapp myproject fixtures pytest.ini \
        -type f -newer "$STAMP" ! -path '*/migrations/*' \
        \( ! -name '*.py' -o -path 'myproject/settings*' -o -name 'conftest.py' \) \
        ! -path '*/__pycache__/*' | head -5)"
    if [ -n "$newer" ]; then
        echo "Changed, and not traceable per test:"; printf '  %s\n' $newer
        full=true
    fi
    # A new migration needs a fresh test database, not a full run.
    [ -n "$(find myapp -path '*/migrations/*.py' -newer "$STAMP" | head -1)" ] && rebuild=true
fi

# Stamp the start, so an edit made while the tests run counts next time.
started="$(mktemp .testmondata.run.XXXXXX)"
args=(--testmon --reuse-db)
# --create-db alone deletes the database when the run ends; with
# --reuse-db as well, the rebuilt one is kept for next time.
[ "$rebuild" = true ] && args=(--testmon --reuse-db --create-db)
[ "$full" = true ] && args=(--testmon-noselect --reuse-db --create-db)

status=0
uv run pytest "${args[@]}" -q "$@" || status=$?
# 0: passed, or nothing selected. 1: some failed (still recorded).
# 5: nothing collected at all.
case "$status" in 0|1|5) mv "$started" "$STAMP" ;; *) rm -f "$started" ;; esac
[ "$status" = 5 ] && exit 0
exit "$status"

여기서 두 가지는 짚고 넘어갈 만합니다. --reuse-db는 실행 사이에 테스트 데이터베이스를 유지하는 pytest-django의 플래그입니다. 실행이 몇 초로 줄어들면 이게 중요해집니다. 매번 데이터베이스를 새로 만드는 데 테스트 자체보다 오래 걸릴 수도 있거든요. 전체 실행이나 새 마이그레이션 뒤의 실행에서는 데이터베이스가 현재 스키마를 갖도록 --create-db를 더합니다. 이때 --reuse-db도 옆에 남겨 두세요. --create-db만 쓰면 pytest-django가 실행이 끝날 때 데이터베이스를 지워 버려서, 다음 실행이 처음부터 다시 만들어야 합니다.

그리고 testmon이 모든 테스트를 선택에서 빼면 실행은 0으로 끝나니, “바뀐 것 없음"은 통과로 칩니다. 종료 코드 5는 pytest의 “수집된 테스트 없음"인데, 스크립트는 이것도 문제없는 것으로 봅니다.

목록에 없는 것도 눈여겨보세요. pyproject.toml과 락 파일입니다. 첫 버전은 락 파일이 바뀔 때마다 전부 돌렸는데, 그러다 보니 느린 대체 경로가 거의 매일 작동해서 오히려 전보다 나빠졌습니다. testmon은 설치된 패키지 버전을 이미 직접 추적하니, 도와줄 필요가 없습니다.

6. 전용 데이터베이스와 캐시를 줍니다. 같은 머신에서 다른 것도 테스트를 돌린다면, 이를테면 두 번째 터미널이나 코딩 에이전트, manage.py test 같은 것이 있다면, 스크립트가 자기만의 테스트 데이터베이스와 캐시 번호를 쓰게 하세요. 그래야 유지해 둔 데이터베이스가 남의 실행과 마주칠 일이 없습니다.

export DATABASE_URL="postgresql://myapp:myapp@localhost:5432/myapp_changed"
export REDIS_URL="redis://localhost:6379/8"

7. 실행할 때마다 먼저 그 캐시를 비웁니다. 이건 호되게 겪고 배웠습니다. 전체 실행에서는 나지 않던 KeyError로 부분 실행이 실패하기 시작했습니다. 카테고리 라벨 몇 개가 만료 없이 캐시되어 있었는데, 한 실행에서 유지한 테스트 데이터베이스가 그보다 앞선 실행이 데워 둔 캐시와 만난 겁니다. 스크립트 맨 위에서 캐시를 비우니 해결됐습니다.

uv run python -c "import os, redis; redis.Redis.from_url(os.environ['REDIS_URL']).flushdb()"

testmon은 문서에 적힌 대로 일했을 뿐입니다. 매번 다른 부분 집합을 돌리면, 앞서 돈 테스트 덕분에 통과하던 테스트가 드러납니다. 고칠 곳은 testmon이 아니라 테스트 설정입니다.

8. 선택이 틀렸을 때 쓸 플래그를 알아 둡니다.

• --testmon-noselect는 모든 테스트를 돌리되 실패할 가능성이 높은 것부터 돌립니다. -k, -m, --lf나 테스트의 노드 ID를 함께 넘기면 testmon이 알아서 이 모드로 바꿉니다.
• --testmon-forceselect는 영향받는 테스트 중 -k나 -m에도 맞는 것만 돌립니다.
• --testmon-nocollect는 기존 기록을 쓰되 거기에 보태지는 않습니다. 디버거 아래에서나 coverage가 이미 돌고 있을 때는 강제로 이 모드가 됩니다.
• --no-testmon은 한 번의 실행에서만 testmon을 끕니다. addopts에 넣어 두었을 때 씁니다.
• --testmon-env=<name>은 한 파일 안에 기록을 따로따로 둡니다. 설정 모듈 두 개로 돌리는 스위트에 씁니다.

프로젝트에 JavaScript 쪽도 있다면, Jest에는 같은 기능이 내장돼 있습니다. jest --changedSince=main은 main 이후 바뀐 것을 import하는 테스트를 돌리는데, coverage가 아니라 import를 따라갑니다. 저는 이걸 앱의 package.json에 npm run test:changed로 넣어서 양쪽이 같은 습관을 갖게 했습니다. 유틸리티 모듈 하나를 고쳤더니 앱의 테스트 파일 121개 중 7개가 선택됐습니다.

얼마나 아껴 주나

#

래퍼를 넣고 다음 절의 버그까지 고친 뒤, 시작 시간을 포함해서 재 봤습니다.

평소의 수정이라면 병렬 스위트보다 25배쯤 빠르고, 바뀐 게 없을 때는 200배쯤 빠릅니다.

기록도 더 넓은 범위에서 같은 말을 합니다. 스위트가 실행하는, 테스트가 아닌 Python 파일 307개 가운데 중앙값에 해당하는 파일을 바꾸면 테스트 22개, 테스트 시간으로 8초쯤에 닿습니다. 반대쪽 끝에는 핵심 모듈 몇 개가 있습니다. 거의 모든 테스트가 이 모듈들을 실행하니, 여기를 바꾸면 1,500개 안팎의 테스트에 닿고 testmon은 스위트 대부분을 다시 돌립니다. 그게 맞는 답이지, 실패가 아닙니다. 이 수치들은 파일별 상한입니다. testmon은 블록 단위로 일하니까, 함수 하나를 바꾸면 그 함수를 실행한 테스트만 고릅니다.

비용은 래퍼가 대체 경로로 넘어갈 때 드러납니다. 전체 실행은 첫 실행과 똑같이 프로세스 하나로 기록하는 실행이라 12분쯤 걸리고, 그건 이 래퍼가 대신하는 병렬 스위트보다 느립니다. 프로세스 하나로 도는 건 testmon을 pytest-xdist와 함께 아직 안 써 봤기 때문입니다. xdist는 1.4부터 지원하니, 다음에 재 볼 건 그쪽이죠. 그래서 전체 실행을 촉발하는 파일 목록은 정직하게 줄일 수 있는 데까지 짧아야 합니다.

초록불처럼 보였던 버그

#

처음 잰 수치는 이것보다 좋았습니다. 수정 한 번에 테스트 6개, 3.3초. 그런데 틀린 수치였고, 화면 어디에도 그런 말은 없었습니다.

Python 3.14부터 coverage.py는 인터프리터의 sys.monitoring 위에 만든 새 코어를 기본으로 씁니다. 이 코어는 한 프로세스가 어떤 줄을 처음 실행할 때만 그 줄을 보고합니다. testmon은 어느 테스트가 어느 줄을 실행했는지를 coverage에서 받아 기록을 만드니, 각 줄은 우연히 그 줄을 처음 실행한 테스트 하나에만 돌아가고 다른 테스트에는 하나도 돌아가지 않았습니다. 테스트 여덟 개가 함께 거치는 줄을 고치면 testmon은 그중 하나만 고르는 거죠.

이걸 잡아낸 건 이 설정을 그대로 가져다 쓴 제 다른 작은 프로젝트였습니다. 거기에 도입하면서 일부러 한 줄을 망가뜨리고 결과를 비교해 봤는데, 숫자가 맞지 않았습니다. 이 스위트로 돌아와 같은 확인을 해 봤습니다. 홈 화면 배너 코드에서 슬라이드 제목 한 줄을 망가뜨렸더니, 그냥 pytest는 실패한 테스트 8개를 보고했고 testmon은 4개를 골랐습니다. 망가진 나머지 4개는 한 번도 돌지 않았고, 출력 어디에도 그것들이 빠졌다는 말은 없었습니다.

고치는 건 한 줄, export COVERAGE_CORE=ctrace입니다. coverage를 예전의 C 트레이서로 되돌리는 설정이죠. 트레이서가 다르면 기록도 달라지니 다시 기록했습니다. 테스트 2,248개에 12분 3초. 그 뒤로는 같은 식으로 망가뜨리는 수정을 하면, 그 수정으로 깨진 테스트 11개가 전부 돌았습니다.

업데이트(11월 7일): 11월 2일에 나온 testmon 2.3.0은 프로세스 안에서도, 서브프로세스에서도 C 트레이서를 스스로 설정하므로 새로 설치하면 이 export는 더 이상 필요 없습니다. 다음 문단의 검사는 여전히 필요합니다.

이 글에서 무엇보다 먼저 전하고 싶은 교훈이 이겁니다. 너무 적게 고르는 테스트 선택기는 성공과 똑같이 생겼습니다. 테스트는 적고, 실행은 빠르고, 전부 초록불이죠. 그러니 선택기를 설정할 때는 여러 테스트가 함께 쓰는 무언가를 일부러 망가뜨리고, 그냥 스위트와 선택기를 둘 다 돌려서 같은 테스트가 실패하는지 확인하세요. 그리고 Python이나 coverage.py의 버전이 바뀔 때마다 다시 확인하세요.

코딩 에이전트가 들어오는 자리

#

이제 그 저장소의 변경을 전부 제 손으로 하지는 않습니다. 작은 변경은 코딩 에이전트가, 제 경우엔 Claude Code가 많이 맡는데, 좋은 에이전트는 수정할 때마다 테스트를 돌립니다. 11분짜리 스위트 앞에서는 에이전트도 제가 겪던 나쁜 선택지 두 개를 똑같이 마주합니다. 기다리거나, 어느 테스트 파일이 중요한지 짐작하거나.

그래서 저장소의 에이전트 지침에 이제 이렇게 적혀 있습니다. 작업 중에 테스트를 돌리는 기본 방법은 래퍼 스크립트이고, 전체 실행은 --all. 에이전트는 수정할 때마다 저와 똑같이 정확한 테스트 집합을 몇 초 만에 받습니다. 6단계에서 스크립트에 전용 데이터베이스와 캐시를 준 것도 이 때문입니다. 바쁜 날에는 같은 머신에서 테스트를 돌리는 세션이 하나가 아니고, 유지해 둔 데이터베이스가 남의 실행과 마주쳐서는 절대 안 되니까요.

testmon에 AI 전용 기능이 따로 필요한 건 하나도 없습니다. 같은 기록, 같은 선택입니다. 다만 변경을 만드는 쪽이 변경을 아주 많이 만들 때 더 중요해질 뿐이죠.

CI에는 왜 더 거친 버전을 넣었나

#

testmon에는 CI 모드가 없습니다. 러너에서도 노트북에서와 똑같이 동작하고, 작성자는 CI 러너끼리 .testmondata를 공유하거나 캐시하는 방식이 자기네 호스팅 서비스인 testmon.net보다 훨씬 덜 효과적이라고 적어 두었습니다. 캐시된 기록은 앞에서 말한 모든 면에서 눈이 먼 채일 테고, 제 CI는 Django의 러너로 프로세스 넷에서 스위트를 돌리니, testmon은 빼 두었습니다.

대신 CI에는 같은 아이디어를 파일 단위로 넣었습니다. 체크 워크플로는 이제 작은 잡 하나로 시작하는데, 이 잡이 push의 diff를 보고 저장소의 어느 쪽을 건드렸는지 정합니다. Python API인지, 모바일 앱인지, 둘 다인지, 둘 다 아닌지. 전에는 문서만 바꾼 push까지 포함해 모든 push에서 Python 잡과 앱 잡을 둘 다 돌렸습니다. 이제 문서만 바꾼 push는 아무것도 돌리지 않고, 앱만 바꾼 push는 Django 스위트를 건너뜁니다. 실제 커밋 다섯 개에 대고 이 잡을 시험 삼아 돌려 봤더니, 문서만 바꾼 커밋은 아무것도 돌리지 않았고, 앱만 바꾼 커밋은 Python 잡을, 백엔드만 바꾼 커밋은 앱 잡을 건너뛰었습니다. 줄인 예제입니다.

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.diff.outputs.python }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: diff
        env:
          BEFORE: ${{ github.event.before }}
          HEAD: ${{ github.sha }}
        run: |
          FILES="$(git diff --name-only "$BEFORE" "$HEAD")"
          # Python's inputs include the non-Python files its tests read.
          PY='^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)'
          if printf '%s\n' "$FILES" | grep -qE "$PY"; then
            echo "python=true" >> "$GITHUB_OUTPUT"
          else
            echo "python=false" >> "$GITHUB_OUTPUT"
          fi

  python:
    needs: changes
    if: needs.changes.outputs.python == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: uv run python manage.py test --parallel 4 --noinput

실제 워크플로는 비교할 범위가 없을 때도 전부 돌립니다. 새 브랜치, 강제 push, 수동 실행이 그런 경우입니다.

사각지대는 모양만 다를 뿐 그대로입니다. testmon이 JSON 파일을 못 보듯, 경로 필터도 목록에 적어 주지 않으면 못 봅니다. 그래서 패턴에 공유 픽스처, 빌드된 번들, 생성된 사이트를 명시적으로 적고, 이걸 고치는 사람은 목록을 정직하게 유지해 달라는 주석을 달아 두었습니다. 파일 단위 버전은 더 투박하지만, 실패하더라도 안전한 쪽으로 실패합니다. Python 쪽에서 뭐든 바뀌었으면 스위트 전체가 돕니다.

써 볼 만한가요?

#

몇 분씩 걸리는 스위트라면, 네. 진짜 비용은 testmon이 보지 못하는 것들이고, 래퍼 스크립트가 그걸 위해 있습니다. 그렇다 해도 testmon이 있어야 할 자리는 노트북에서 도는 작업 루프입니다. CI는 Python 쪽이 바뀔 때마다 여전히 스위트 전체를 돌리고, 배포 전에 제가 믿는 건 그 실행입니다.

GitHub Actions에서 Docker Compose를 돌리는 법을 찾아 오셨다면, 결론부터. 저는 그걸 2년 하다가 그만뒀습니다. 지금 CI는 같은 Postgres와 Valkey 이미지를 services:로 선언하고, 같은 uv run …과 npm run … 명령을 러너에서 바로 돌립니다. Compose는 개발자가 로컬에서 돌리는 것으로 남았고요. 나머지는 그 이유와 실제 파일들입니다.

2024년에 플랫폼 종속 YAML 대신 Docker Compose로 CI/CD 하기라는 글을 썼습니다. 빌드 로직은 Compose에 두고 CI 도구는 그걸 호출하는 일만 하게 하라는 내용이었죠. 2년이 지나 제가 실제로 배포하는 저장소를 전부 다시 훑어봤습니다. 워크플로가 있는 저장소는 넷이고, 커미터는 모두 저 한 명입니다. 그리고 그 워크플로 중 docker compose를 호출하는 건 이제 하나도 없습니다. 원칙은 살아남았고, 방법은 살아남지 못했습니다. 아래는 그 자리를 대신한 것들입니다. 줄여서 예제로 만든 파일, GitHub가 기록한 단계별 소요 시간, 그리고 CI/CD 다이어그램이 바라는 것보다 덜 자동화된 부분까지 적었습니다.

제가 돌리는 파이프라인 전부, 표 하나로

#

교과서 용어로 말하면 두 Hugo 사이트는 지속적 배포이고, 앱(제가 만드는 마켓플레이스 겸 커뮤니티 앱)은 지속적 통합에 명령 한 줄짜리 릴리스를 더한 지속적 전달입니다. 체크는 뭔가 잘못됐다고 알려 줄 뿐, 배포를 막지는 않습니다. 일부러 이렇게 나눴습니다. OTA 업데이트는 대상 바이너리 버전을 쓰는 모든 휴대폰에 닿으니, 머지의 부작용이 아니라 결정이어야 합니다. 그리고 API는 데이터베이스 마이그레이션이 실행되는 곳입니다. 제 나머지 Django 앱 두 개에는 워크플로가 아예 없습니다.

CI 쪽: 워크플로 하나, 잡 두 개

#

앱의 CI는 .github/workflows/checks.yml 파일 하나입니다. 10월 11일 전까지는 이것조차 없었습니다. 아래는 그 구조를 줄여서 만든 예제입니다.

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

두 잡은 나란히 돕니다. 지금까지 성공한 35번의 실행에서 앱 잡의 중앙값은 7분쯤, Python 잡은 12분 반쯤입니다.

services: 블록이 바로 Compose 파일이 옮겨 간 자리인데, 다음 절에서 다룹니다. 환경 변수는 몇 개와 플래그 하나뿐입니다. 나머지는 전부 개발자가 docker compose up에서 받는 개발용 기본값으로 떨어지기 때문에, 테스트에는 시크릿이 하나도 필요 없습니다. 정말 그런지 보려고 딱 그 환경만, 다른 건 아무것도 없이 테스트 일부를 돌려 확인했습니다.

CI는 제 노트북, 프로덕션 이미지와 같은 인터프리터, 즉 uv가 직접 빌드한 Python 3.15.0으로 돕니다. uv sync가 .python-version을 읽고 정확히 그 빌드를 내려받기 때문입니다. (실제 파일에서는 setup-uv에 python-version-file 입력도 넘기는데, 이건 아무 일도 하지 않습니다. setup-uv v6에는 그런 입력이 없고, 매 실행마다 그렇다는 경고가 붙어 있습니다. 이 글을 쓰다가야 알았습니다.)

인터프리터를 맞춘 보람은 워크플로를 넣은 지 8일 만에 나타났습니다. 10월 19일에 3.15의 JIT 컴파일러를 켰더니, 켠 뒤 첫 실행에서 테스트 하나가 실패했습니다. 앱이 저장할 때마다 지나가는 코드 경로의 평범한 yield from이 AttributeError: 'list' object has no attribute 'send'를 던진 겁니다. 같은 커밋을 JIT를 끄고 돌리면 통과했습니다. 제 Mac은 arm64라서 이 문제를 한 번도 만나지 않았고, 러너는 프로덕션 머신과 같은 x86_64입니다. JIT는 CI에서도 Dockerfile에서도 다시 꺼 두었고, 버그는 프로덕션에 닿지 않았습니다. python/cpython#155823로 올라가 있던 버그로, 3.15.0이 나온 뒤인 10월 13일에 업스트림에서 고쳐졌습니다.

사실 맨 첫 실행도 실패했는데, 이유는 더 시시했습니다. Expo는 expo start를 할 때 expo-env.d.ts를 만들고 이 파일은 gitignore되어 있습니다. 그래서 제가 쓰던 작업 사본에는 모두 있었고, 새로 받은 체크아웃에는 없었죠. TypeScript가 로컬에서는 한 번도 보지 못한 오류 다섯 개를 냈습니다. 그 파일을 써 주는 단계가 해결책입니다.

concurrency는 같은 브랜치에 더 새로운 push가 오면 이전 실행을 취소합니다. 지금까지 취소된 12번의 실행은 모두 이렇게 끝났습니다. 커밋 전 훅(pre-commit hook)이 린터를 돌리고, Python이나 TypeScript가 스테이징돼 있으면 타입 체커도 돌리기 때문에 실수는 대부분 push까지 가지도 않습니다.

Docker Compose 파일은 어디로 갔나

#

앱의 docker-compose.yml에서 CI와 관련된 부분을 예제로 옮긴 것입니다. 실제 파일에는 서비스도 더 있고 환경 변수도 훨씬 많습니다.

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

checks.yml의 services: 블록 옆에 놓고 보면 같은 이미지 두 개입니다. Postgres 17(여기서는 Alpine 빌드, CI에서는 Debian 빌드)과 valkey/valkey:8-alpine. 지금의 관계는 이렇습니다. Compose 파일은 개발자가 돌리는 것이고, CI는 같은 이미지를 서비스 컨테이너로 선언한 다음 개발자가 돌리는 것과 같은 명령, uv run …과 npm run …을 러너에서 바로 돌립니다.

2024년 글과 비교하면, 제가 가장 신경 쓰던 부분은 살아남았습니다. CI 도구는 얇고, 체크와 배포는 제가 직접 돌릴 수 있는 명령입니다. 살아남지 못한 건 CI가 Compose를 호출하는 방식입니다.

앱의 CI는 Docker 이미지를 아예 빌드하지 않습니다. 이미지는 배포할 때 Fly의 빌더가 한 번 빌드하고, CI는 코드가 괜찮은지만 말해 주면 됩니다. 툴체인이 캐시돼 있으면 그건 6초짜리 설치로 끝납니다. 게다가 Compose 파일은 작업 사본을 바인드 마운트하고 데이터를 시드하는데, 테스트 실행이 할 일은 아닙니다. 그러니 CI용 Compose 파일이 따로 필요했을 테고, 그건 같은 서비스를 두 번째로 정의해 손으로 맞춰 가야 한다는 뜻입니다.

그리고 2024년 예제에는 당시 눈치채지 못한 버그가 있었습니다. docker compose build는 이미지를 빌드할 뿐 서비스의 command를 실행하지 않습니다. 그러니 그 파일의 npm test는 CI에서 한 번도 돌지 않았고, 워크플로는 테스트가 통과하든 말든 초록불이었습니다.

그 글이 가장 걱정했던 위험, 즉 CI 업체를 바꾸는 일은 결국 일어나지 않았습니다. 실제로 일어난 이동은 반대쪽 끝에서였습니다. 이 블로그와 그 클라이언트 사이트가 호스팅을 Cloudflare Pages로 옮겼는데, 블로그 쪽은 45줄짜리 워크플로 하나를 새로 쓰는 걸로 끝났습니다. 빌드가 원래 명령 한 줄이었기 때문이죠. 그리고 제가 경고했던 300줄짜리 워크플로요? 하나 있습니다. pyhtml2text의 워크플로입니다. wheel을 Linux, macOS, Windows 러너에서 각각 여러 아키텍처로 빌드해야 해서 긴 건데, 그래서 플랫폼 전용 YAML이 맞는 도구인 유일한 작업이기도 합니다.

캐싱: 단계별 소요 시간부터 읽기

#

GitHub는 모든 단계의 소요 시간을 기록해 두고, gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs로 꺼내 볼 수 있습니다. 아래는 10월 20일, 앱의 가장 최근 성공 실행입니다.

의존성 캐시 두 개는 모두 켜져 있고, 둘 다 저렴한 부분입니다. GitHub가 이 저장소용으로 보관하는 uv 캐시는 200KB 정도인데, setup-uv가 다시 내려받으면 되는 것들은 정리해 버리기 때문입니다. npm 캐시는 400MB에 가깝습니다. 시간이 드는 곳은 테스트이고, 테스트는 이미 4갈래로 병렬 실행됩니다. 실행을 더 빠르게 하고 싶다면 캐시가 아니라 테스트 스위트를 손보겠습니다.

블로그는 정반대입니다. Hugo가 처리한 이미지는 gitignore된 resources/_gen에 있어서, 새 러너마다 커버, 본문 이미지, 플레이스홀더를 전부 다시 인코딩했습니다. 아래 워크플로는 actions/cache로 이것을 복원합니다. 키는 사진 자체의 해시이고, 키가 맞지 않으면 가장 최근의 이전 캐시로 대신합니다. Hugo는 빠진 것만 처리하니까요. 캐시를 넣기 전 마지막 8번의 실행에서 빌드 단계는 3376초 걸렸고, 넣은 뒤 26번은 620초였습니다. 94초가 한 번 있었을 뿐이고, 같은 커밋에서 플레이스홀더와 두 번째 카드 크기까지 추가했는데도 그렇습니다.

앱의 이미지는 Fly의 빌더에서 빌드되고, 의존성 파일을 코드보다 먼저 복사하며 uv의 다운로드 캐시는 BuildKit 캐시 마운트(RUN --mount=type=cache,target=/root/.cache/uv)에 둡니다. 하지만 더 큰 개선은 캐시가 아니었습니다. 예전 .dockerignore는 블록리스트였는데, 추가 git worktree들을 모아 둔 폴더를 빠뜨렸습니다. worktree마다 자기 의존성과 빌드 산출물이 들어 있었죠. 그래서 파일 27만 7천 개, 7.7GB가 배포할 때마다 빌더로 올라갔습니다. 허용 목록으로 다시 쓴 지금은 빌드 컨텍스트가 40MB 정도입니다. 그 패턴을 예제로 보면 이렇습니다.

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

시크릿은 최대한 적은 곳에

#

시크릿은 세 군데에 있습니다. GitHub Actions 시크릿은 워크플로가 하는 일을 위한 것이고, 두 Hugo 저장소에는 CLOUDFLARE_API_TOKEN 딱 하나씩만 있습니다. Fly 시크릿은 앱의 런타임 설정으로 flyctl secrets set으로 넣고, Actions를 거치지 않습니다. 그리고 제 노트북의 gitignore된 .env에는 배포 스크립트가 Cloudflare 캐시를 비울 때 쓰는 토큰이 있습니다.

PyPI에는 시크릿이 아예 필요 없습니다. pyhtml2text는 신뢰할 수 있는 게시(trusted publishing)를 씁니다. PyPI가 GitHub이 워크플로에 발급하는 수명 짧은 OIDC 토큰을 받아 주기 때문에, 릴리스 잡은 id-token: write만 요청하고 저장소의 시크릿 페이지는 비어 있습니다. 샐 것도, 교체할 것도 없죠.

토큰에는 필요한 만큼만 줍니다. GitHub에 있는 앱의 Fly 토큰은 머신 목록만 조회하는 예약 체크용이라 fly tokens create readonly로 만들었습니다. Pages 배포는 contents: read와 deployments: write만 요청하고 그 이상은 없습니다.

입력값은 스크립트에 바로 넣지 않고 반드시 env:를 거칩니다. OTA 워크플로는 자유롭게 쓰는 릴리스 노트를 받습니다. 이걸 run: 안에 ${{ inputs.notes }}로 쓰면 bash가 읽기 전에 텍스트가 스크립트에 그대로 붙여 넣어지니, 따옴표와 세미콜론이 든 노트는 코드가 되어 버립니다. 환경 변수로 넘기면 데이터로 남습니다. 패턴을 예제로 보면 이렇습니다.

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

아예 GitHub 밖에 두는 키도 있습니다. 예약 리포트 하나에는 앱의 로그인 백엔드에 대한 관리자 권한이 있는 키가 필요해서, 그 리포트는 예약 워크플로에서 제 Mac의 예약 작업으로 옮겼습니다. 워크플로는 수동 예비용으로 남아 있고, 그 키가 필요한 섹션은 빼고 게시합니다.

배포: push마다, 스크립트로, 태그로

#

Hugo 사이트는 push마다 배포됩니다

#

블로그 워크플로를 예제로 옮긴 것입니다. Pages 프로젝트를 처음 만드는 단계는 뺐습니다.

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }} 덕분에 main은 프로덕션이 되고 다른 브랜치는 모두 미리보기 URL을 받습니다. 클라이언트 사이트의 워크플로는 이것과 같은 구조에 빌드 전 rm -rf public 한 줄이 더 있습니다. 그쪽은 public/이 커밋되어 있어서, 안 그러면 삭제한 페이지가 업로드에 계속 남기 때문입니다.

Hugo 버전은 여기에서만 고정합니다. 10월에 패키지 매니저 업그레이드로 제 노트북의 Hugo가 0.168이 됐는데, 테마가 지원하는 최신 버전보다 하나 높습니다. 배포는 0.165에 머물렀고 아무 일도 없었습니다.

그리고 빌드가 곧 테스트입니다. 9월 14일, 한 브랜치의 미리보기 배포가 세 번 연달아 실패했습니다. 그 브랜치의 글 하나가 Hugo의 ref로 아직 초안인 글을 가리키고 있었거든요. CI는 프로덕션이 빌드하는 것과 똑같이, 초안을 빼고 빌드합니다. 그러니 링크는 아무것도 가리키지 않았고 Hugo는 REF_NOT_FOUND로 멈췄습니다. 그동안에도 main은 계속 배포되고 있었습니다.

앱의 API는 스크립트로 배포합니다

#

배포 스크립트의 핵심을 예제로 옮긴 것입니다.

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

그리고 fly.toml에서 짝이 되는 부분입니다.

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

이미지는 한 번 빌드해서 커밋과 시각으로 만든 라벨을 붙여 Fly 레지스트리에 올리고, 그 라벨로 배포합니다. 그래서 롤아웃되는 건 정확히 빌드한 그것입니다.

무중단 배포를 가능하게 하는 건 예비 머신을 먼저 깨우는 단계입니다. max_unavailable = 1은 실행 중인 머신만 셉니다. 그런데 앱은 한가할 때 실행 중인 머신을 하나도 두지 않습니다(일시 정지된 머신은 1초 남짓이면 깨어납니다). 그래서 깨어 있던 머신 하나가 잠든 머신들과 같은 묶음에서 교체되곤 했고, 그 뒤에는 따뜻한 머신이 하나도 없었습니다. 9월 28일에 오리진에 프로브를 계속 보내 봤더니, 그냥 flyctl deploy를 할 때는 타임아웃 7번과 7.3초의 공백이 있었고, 먼저 빌드하고 롤아웃 전에 머신 하나를 깨워 두는 스크립트 배포로는 요청 2,514개 중 실패가 하나도 없었습니다.

스크립트의 나머지는 오류 알림이 오는 팀 채팅 채널에 배포 표시를 남깁니다. 그래야 오류가 몰렸을 때 방금 무엇이 바뀌었는지와 맞춰 볼 수 있죠. 그리고 Cloudflare 캐시를 비우고 머신들을 데워 둡니다. 웹 프런트엔드는 이미지를 아예 거치지 않는데, 그건 프론트엔드와 백엔드 따로 배포하기에 적었습니다.

마이그레이션은 파이프라인 단계가 아닙니다. Fly의 release_command가 제 환경에서는 멈춰 버려서, 새 이미지로 처음 부팅하는 머신이 락을 잡고 마이그레이션하는 동안 나머지는 기다립니다. 그러니 모든 마이그레이션은 아직 돌고 있는 코드와도 맞아야 합니다. 컬럼은 한 배포에서 추가하고, 다음 배포에서 쓰지 않게 하고, 세 번째 배포에서 지웁니다.

이 스크립트에 꼭 제 노트북이어야 하는 부분은 없지만, 노트북에만 있는 파일 몇 개가 스크립트를 거기 묶어 둡니다. Cloudflare 자격 증명, 그리고 마지막으로 무엇을 배포했는지 적어 둔 기록입니다. 새 러너에는 이 파일들이 없죠. 커밋하지 않은 변경도 배포해 버리고 채팅 채널에 그렇다고 알리는데, 웹 릴리스 스크립트는 더러운 작업 트리를 거부합니다.

브랜치별 프리뷰 환경에서 저는 이걸 손으로 하는 건 혼자일 때는 괜찮지만, 두 번째 개발자부터는 git에서 뭔가 일어났기 때문에 일어나야 한다고 썼습니다. 앱의 개발자는 아직 한 명입니다. 그 글의 브랜치 환경 워크플로는 제가 만들었던 브랜치에 그대로 있습니다.

OTA 워크플로는 수동 전용입니다. 게시는 결정이어야 하고, 업데이트 서비스는 부분 롤아웃이 열려 있는 동안 새 릴리스를 거부하기 때문에 push 트리거라면 카나리 배포 때마다 걸릴 테니까요. 이 워크플로는 한 번도 실행된 적이 없습니다. 지금까지 OTA 업데이트는 전부 제 노트북에서, 워크플로가 호출하는 것과 같은 스크립트로 나갔습니다. 얇은 워크플로를 쓰는 이유가 한 줄로 이겁니다. 릴리스를 어떻게 시작하든 같은 스크립트죠.

pyhtml2text는 태그로 릴리스합니다

#

릴리스 잡입니다. 패키지 이름은 일반적인 이름으로 바꿨습니다.

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

릴리스 잡은 모든 빌드 잡을 기다리고, 실제 게시는 태그일 때만 합니다. 수동 실행은 빌드하고 증명(attestation)까지 만들지만 아무것도 올리지 않습니다. actions/attest는 어느 워크플로가 각 wheel을 빌드했는지 기록하고, uv publish --trusted-publishing always는 비밀번호 대신 OIDC 토큰으로 업로드합니다. 패키지 자체에 대해서는 닫힌 풀 리퀘스트, 포크, 그리고 PyPI 패키지에 썼습니다.

예약 워크플로는 최선을 다할 뿐입니다

#

앱에는 예약 워크플로가 하나 있습니다. Fly가 기준치보다 머신을 더 띄우지 않았는지 보는 체크로, 그냥 두면 청구서에서 처음 알게 될 일입니다. 알림은 일부러 실패하는 방식으로 보냅니다. 예약 실행이 실패하면 GitHub이 소유자에게 메일을 보내니까요.

설정은 cron: '*/15 * * * *', 하루 96번입니다. 그런데 지난 2주 동안은 하루 3~8번만 돌았고, 실행 간격의 중앙값은 3시간 40분쯤이었습니다. GitHub 문서가 내놓는 설명은 부하뿐입니다. Actions가 바쁘면 예약 실행이 늦어질 수 있고, 아주 바쁘면 빠질 수도 있다는 거죠. 계속되는 스케일 아웃이라면 몇 시간이면 충분합니다. 몇 분 안에 울려야 하는 것이라면 GitHub의 cron은 모니터링이 아닙니다.

파이프라인에 던져 볼 질문

#

파이프라인을 만들고 있거나 이미 있는 걸 들여다보고 있다면:

1. GitHub Actions가 하루 동안 멈추면 그래도 릴리스할 수 있나요? 못 한다면 릴리스 로직이 YAML 안에 있는 것이고, 2024년 글이 여전히 유효합니다.
2. CI가 프로덕션과 같은 인터프리터, 같은 CPU 아키텍처, 같은 데이터베이스 메이저 버전으로 도나요? 제 CI가 컴파일러 버그를 잡은 건 러너와 프로덕션은 둘 다 x86_64이고 제 노트북은 아니었기 때문입니다.
3. 새로 받은 체크아웃이 통과하나요? 안 된다면 대개 생성되고 gitignore된 파일 때문입니다.
4. 실행 시간은 실제로 어디에 쓰이나요? 캐시를 넣기 전에 단계별 소요 시간부터 읽어 보세요.
5. 시크릿마다 몇 군데에 있나요? 그리고 정말 GitHub에 있어야 하나요?

앱 하나를 만드는 작은 팀을 떠올려 보세요. 개발자 둘일 수도, 다섯일 수도 있습니다. 전문 분야가 나뉜 사람들이 아니라, 각자 자기 브랜치에서 데이터베이스 마이그레이션부터 API를 거쳐 모바일 앱 화면까지 기능 하나를 처음부터 끝까지 맡는 사람들입니다. 팀을 굴리기에 좋은 방식이고, 두 번째 개발자가 합류하는 순간부터 반복되는 실패가 하나 있습니다. “지금 스테이징 쓰는 사람 있어요?“라는 메시지입니다.

그 메시지 뒤에는 기능을 다 만들고 테스터나 디자이너에게 보여주고 싶은데 그럴 수 없는 개발자가 있습니다. 스테이징에는 두 번째 개발자의 브랜치가 올라가 있고, dev에는 세 번째 개발자의 브랜치가 올라가 있는데 그건 이틀 전에 로그인을 망가뜨린 뒤로 다시 배포되지 않았습니다. 몇 사람, 공유 환경 둘, 그리고 일정 조율을 떠맡은 채팅 스레드.

이건 사람 문제가 아닙니다. 토폴로지 문제입니다. 모든 개발자가 환경을 “내 브랜치가 실제가 되는 곳"으로 다루니, 환경이 머지가 해야 할 일을 브랜치 하나씩 차례로 대신하고 있고, 나머지 전부는 줄을 서 있는 겁니다.

제 스택의 프로덕션 형태는 My Current Stack에 적었습니다. Fly.io의 가장 싼 머신 위의 Django, 커넥션 풀러 뒤의 Postgres, 캐시와 Channels 레이어용 Redis, 별도의 WebSocket 앱, 백그라운드 워커, 파일용 S3 호환 버킷, 호스팅형 인증 서비스, 앞단의 Cloudflare, 그리고 이 모든 것과 통신하는 모바일 앱입니다. 이 글은 그 스택을, 어떤 브랜치든 개발자가 PR에 라벨 하나를 붙이면 몇 분 안에 HTTPS가 붙은 공개 복사본 전체를 얻는 것으로 바꾼 이야기입니다. 다른 누구에게 부탁하지도, 누가 프로비저닝해 주지도 않고요. Postgres 클러스터를 하나 더 두지도, Redis를 하나 더 두지도, 버킷을 하나 더 두지도 않고요. 인프라는 공유된 채로 남습니다. 달라지는 건 모든 공유 자원이 이름으로 잘리는 법을 배운다는 것이고, 그 이름은 브랜치에서 나옵니다. 여기에 팀 규모를 전제하는 건 없습니다. 개발자 둘이든 스물이든 설계는 같고, 늘어나는 건 앱 목록뿐이며 그건 스위퍼가 처리합니다. 오후 한나절에 만들고, 브랜치 셋을 동시에 띄우고, 예상 못 한 두 군데에서 부러뜨리고, 다시 걷어냈습니다. 아래 출력은 그 실행에서 나온 것입니다.

공유 환경 하나가 개발자 한 명 이상으로 늘어나지 못하는 이유

#

공유 dev 환경에는 전제가 하나 깔려 있습니다. 모두가 보고 싶어 하는 “현재 코드 버전"이 하나라는 전제입니다. 개발자가 한 명이거나, 팀이 변경 흐름 하나를 발맞춰 작업할 때는 맞는 말입니다. 두 번째 개발자가 다른 일정으로 기능을 시작하는 순간 틀린 말이 되고, 처음부터 끝까지 맡는 방식에서는 모든 기능이 그렇습니다. 그때부터 환경이 쥐고 있는 모든 것이 쟁탈 대상이 됩니다.

• 배포된 코드. 마지막에 배포한 사람이 이깁니다. 나머지 사람들의 작업은 다시 배포하기 전까지 보이지 않고, 다시 배포하면 앞사람 것이 지워집니다.
• 데이터베이스 스키마. 개발자마다 자기 기능의 데이터 모델을 소유할 때 가장 아프게 무는 부분입니다. 첫 브랜치가 컬럼을 추가합니다. 한 시간 뒤 배포된 두 번째 브랜치는 그 컬럼을 모르고, ORM이 insert에서 실패하기 시작합니다. 아니면 두 브랜치 모두 0042_* 마이그레이션을 갖고 있어서, 공유 데이터베이스가 누구의 마이그레이션 이력과도 맞지 않는 상태가 되고, 누군가 초기화하면서 세 번째 개발자가 오후 내내 세팅한 테스트 데이터를 지웁니다.
• 캐시. 한 브랜치의 serializer 변경이 다른 브랜치 코드가 읽는 것과 같은 Redis 키 아래 캐시됩니다. 그래서 나오는 버그 리포트는 어리둥절하고, 하나에 오전 한나절씩 잡아먹습니다.
• 서드파티 연동. OAuth 콜백 하나, 웹훅 URL 하나, 푸시 인증서 하나. 누구 브랜치가 배포돼 있든 그 브랜치가 이벤트를 받습니다.
• 테스터. 배포된 것만 테스트할 수 있으니, 기능이 준비된 순서가 아니라 환경이 우연히 점유된 순서대로 한 번에 하나씩 테스트합니다.

팀은 예약 시스템으로 대응합니다. 채팅 스레드, 고정 메시지, /claim staging 봇. 그건 락입니다. 작업을 보여줄 수 있는 유일한 장소에 걸린 락은 전달 속도에 걸린 락입니다. 개발자 둘이면 성가신 정도입니다. 셋이면 좋은 주에는 견딜 만합니다. 네 번째가 합류하거나, 기능 하나가 디자이너와 사흘간 주고받느라 스테이징을 붙들고 있으면 견딜 수 없게 됩니다.

사람들이 먼저 손대는 해결책은 세 번째 공유 환경, “dev2"나 “uat"입니다. 몇 주는 벌어 줍니다. 줄이 두 갈래가 됐을 뿐입니다.

진짜 해결책은 dev와 스테이징이 애초에 환경이 아니었다는 걸 알아차리는 것입니다. 그것들은 누군가의 브랜치의 현재 상태에 URL이 붙은 것이었습니다. 그렇다면 알맞은 개수는 지금 팀이 신경 쓰는 브랜치의 개수이고, 알맞은 수명은 브랜치의 수명입니다.

모델: 브랜치가 곧 환경

#

목표 상태는 이렇습니다.

표에서 누가 만들고 누가 없애는지를 다시 보세요. 전부 git 이벤트 아니면 시계입니다. git이 컨트롤 플레인입니다. 존재해야 할 환경의 집합은 존재하는 브랜치의 집합에서 그대로 따라 나오고, 자동화가 하는 일은 현실을 거기에 맞춰 두는 것뿐입니다. PR의 라벨이 만들고, 그 뒤의 push마다 갱신하고, PR을 닫거나 머지하면 없애고, 매일 밤 도는 잡이 앞의 셋이 놓친 것을 정리합니다. 모든 브랜치가 환경을 얻는 것도 아닙니다. 라벨이 게이트이고 개발자의 클릭 한 번이니, 백업 push나 봇의 의존성 업데이트는 비용이 없습니다. 아무도 환경을 프로비저닝하지 않습니다. 티켓을 받은 DevOps 엔지니어도, 채팅에서 부르는 봇도, 매번 프롬프트를 넣어야 하는 AI 에이전트도 아닙니다. 열 번째 개발자의 첫 브랜치도 첫 번째 개발자의 브랜치와 똑같은 방법으로, PR에 라벨을 붙였다는 이유로 환경을 얻습니다. 사람에게 부탁해야 한다면 확장된 게 아니라 줄이 자리를 옮긴 것뿐입니다.

그리고 이걸 굴러가게 하는 규칙은 하나입니다. 환경이 건드리는 모든 자원은 브랜치 이름을 따서, 결정론적으로 이름 붙인다. 개발자 이름도 아니고, 티켓 번호도 아니고, 누군가 열기 전까지는 존재하지도 않는 PR 번호도 아닙니다. 브랜치입니다. 개발자가 실제로 다루는 것이 브랜치이고, 이름이 결정론적이면 같은 브랜치에서 ./scripts/env up을 두 번째 실행했을 때 새 환경을 또 만드는 대신 이미 만든 환경을 찾아내기 때문입니다.

이름은 사람을 위한 슬러그와 유일성을 위한 짧은 해시입니다.

branch=$(git rev-parse --abbrev-ref HEAD)              # feature/payments-retry
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20)
hash=$(printf '%s' "$branch" | sha256sum | cut -c1-6)
ENV="${slug%-}-${hash}"                                 # feature-payments-retr-3f9a1c

feature-payments-retr-3f9a1c가 환경입니다. 이 문자열이 Fly 앱 이름, Postgres 데이터베이스 이름(하이픈은 밑줄로), Redis 키 접두사, 버킷의 객체 접두사, 에러 트래커의 environment, 그리고 호스트명의 맨 왼쪽 라벨이 됩니다. 브랜치 이름을 아는 사람은 누구나 계산할 수 있습니다. 어디서도 찾아볼 필요가 없습니다.

마지막 문장이 곧 설계입니다. 환경 목록도 없고 조정자도 없습니다. env up, env down, 호스트명을 라우팅하는 Cloudflare Worker, 밤마다 도는 스위퍼가 각자 브랜치에서 이름을 독립적으로 다시 계산하고, 구조적으로 서로 일치합니다. 특히 Cloudflare는 아무것도 조정하지 않습니다. Worker는 호스트명에서 Fly 앱으로 가는 순수 함수이고, 환경이 만들어졌는지 없어졌는지 영영 알지 못합니다. 앱이 있으면 요청이 닿고, 없으면 Fly가 자기 오류로 답합니다.

여기서 세 가지가 따라 나옵니다.

첫째, “스테이징 누가 쓰고 있어요"가 더는 질문이 아닙니다. feature-payments-retr-3f9a1c-dev.example.com이 있고 fix-login-redirect-8b21e0-dev.example.com이 있으며, 각각 그 브랜치를 맡은 사람의 것입니다.

둘째, 스테이징이 쓰레기장이 아니라 프로덕션의 정직한 리허설이 됩니다. 프로덕션에 갈 바로 그 이미지로, 몇 분 전 프로덕션 모양의 스냅샷에서 복제한 데이터베이스를 상대로 만들어집니다. 거기서 되면 프로덕션에 남은 변수는 프로덕션 데이터뿐입니다.

셋째, 개발자마다 공유 자원의 root 권한 없이도 힘을 얻습니다. 브랜치 환경의 폭발 반경은 그 브랜치 환경입니다. 네 번째로 합류한 사람이 첫날에 자기 브랜치에 뭘 배포하든, 최악의 결과는 자기 브랜치가 망가지는 것입니다.

fly.io/dashboard/my-org

물리적으로는 공유, 논리적으로는 분리

#

“브랜치마다 환경"의 솔깃한 버전은 통째로 복사하는 것입니다. Postgres 클러스터 하나씩, Redis 하나씩, 버킷 하나씩. 깔끔하지만 잘못된 거래입니다. Fly Postgres 클러스터는 머신 하나에 볼륨 하나에 복원 한 번이고, Redis는 머신 하나 더입니다. 환경마다 몇 분씩 기다리고 놀고 있는 데이터베이스 열두 개 값을 내게 됩니다. 스위퍼가 치울 것도 한 종류가 아니라 네 종류가 됩니다.

대신 각 공유 서비스는 프리뷰 조직 전체에 한 번만, 작은 프로덕션 크기로 마련하고, 모든 환경이 $ENV를 키로 한 조각씩 받습니다. 벽에 붙여 두고 싶은 표입니다.

둘은 한마디씩 덧붙일 만합니다.

Postgres: 스키마가 아니라 데이터베이스. 클러스터 하나를 자르는 다른 방법은 환경마다 스키마를 두고 연결마다 search_path를 설정하는 것입니다. 연결 options로 -c search_path=...를 밀어 넣으면 Django도 해 주지만, 트랜잭션 풀링 모드의 커넥션 풀러는 따로 말해 주지 않는 한 시작 옵션을 버리고, 그러고 나면 어차피 풀의 모든 연결이 한 환경에 속해야 합니다. “왜 내 쿼리가 엉뚱한 테이블을 치지"류의 버그를 낳는 원천이고, 환경마다 데이터베이스를 두면 그냥 없는 문제입니다. 데이터베이스는 단단한 경계이고, CREATE DATABASE ... TEMPLATE은 몇 초 만에 하나를 만들며, DROP DATABASE는 아무것도 남기지 않고 지웁니다. 브랜치 환경은 풀러를 거치지 않고 5433 포트로 Postgres에 직접 붙습니다. 프로덕션의 백그라운드 워커가 하는 것과 같은 방식입니다. 풀러는 프로덕션 동시성에서 제 값을 하는데, 브랜치 환경은 그런 동시성을 볼 일이 없습니다.

시크릿: 공유가 아니라 생성. dev 시크릿 한 벌을 만들어 모든 환경에 복사하면 편할 겁니다. 하지 마세요. env up 스크립트는 환경마다 새 SECRET_KEY(세션 서명), ENCRYPTION_KEY(저장 시 암호화되는 모든 것), ENV_TOKEN(모바일 앱이 제시하는 bearer 토큰, 아래에서 더 설명)을 생성해 그 Fly 앱의 시크릿 저장소에만 넣습니다. 한 브랜치의 세션 쿠키는 다른 브랜치에서 쓸모없고, 유출된 프리뷰 토큰은 프리뷰 하나만 열며, 개발자는 일부러 찾아보지 않는 한 값을 볼 일이 없습니다. Fly만이 아니라 별도의 시크릿 매니저에 시크릿을 둔다면 같은 규칙이 적용됩니다. 경로는 myapp/preview/$ENV/이고, 스위퍼가 환경과 함께 그 경로를 지웁니다. 환경 간에 정말로 공유되는 시크릿은 공유 인프라 자체의 자격 증명(Postgres 관리자 URL, Redis URL, 버킷 키)뿐이고, 그건 어느 환경도 아닌 CI에 삽니다.

Redis 행이 가장 의심하기 쉬우니, 테스트해 봤습니다. 한 환경 안에서 캐시 키를 넣고, 다른 환경에서 읽고, 공유 Redis의 모든 키를 나열합니다.

$ fly ssh console -a myapp-feature-profile-tagl-fa8832 -C "python manage.py shell -c \"from django.core.cache import cache; cache.set('who-am-i', 'tagline-branch', 600)\""
$ fly ssh console -a myapp-feature-profile-webs-dcb2e7 -C "python manage.py shell -c \"from django.core.cache import cache; print(cache.get('who-am-i'))\""
None

$ # every key in the shared Redis
  feature-profile-tagl-fa8832:1:who-am-i
  ...

같은 Redis, 같은 키 이름인데 다른 환경에서는 아무것도 보이지 않습니다.

이 글의 나머지는 저 여덟 행에 $ENV를 찍는 스크립트와, 그걸 정직하게 유지하는 규칙입니다.

./scripts/env up

#

개발자가 자기 브랜치에서 실행하는 스크립트로서의 전부입니다. CI도 같은 스크립트를 실행합니다. 따로 놀다 어긋날 CI 전용 경로가 없습니다. 노트북에 필요한 건 fly와 git뿐입니다. SQL은 fly ssh로 Postgres 앱에 가고, 환경의 Redis 키와 버킷 객체는 없애기 전에 환경 자신의 머신이 지우므로, 노트북은 gitignore된 env 파일 말고는 공유 Redis나 버킷 자격 증명을 쥐고 있지 않습니다. 중요한 줄만 남겨 추리면 이렇습니다.

#!/usr/bin/env bash
# scripts/env up|down|name|url: one environment per branch on shared preview infrastructure
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; PG_APP=${PREVIEW_PG_APP:-myapp-preview-pg}; DOMAIN=${BASE_DOMAIN:-example.com}

branch=${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
[[ "$branch" == "main" ]] && { echo "main has staging, not a branch environment" >&2; exit 1; }
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20); slug=${slug%-}
ENV=${ENV_OVERRIDE:-${slug}-$(printf '%s' "$branch" | shasum -a 256 | cut -c1-6)}   # the sweeper passes the name
APP="myapp-${ENV}"; DB="env_${ENV//-/_}"; HOST="${ENV}-dev.${DOMAIN}"

pg() { fly ssh console -a "$PG_APP" -q -C "psql postgres://postgres:${PG_PASSWORD}@localhost:5433/postgres -At -c \"$1\""; }
exists() { fly apps list --org "$ORG" --json | grep -q "\"Name\": *\"$APP\""; }

up() {
  echo "== $branch -> $ENV"
  exists || fly apps create "$APP" --org "$ORG"                         # idempotent
  [[ "$(pg "SELECT 1 FROM pg_database WHERE datname='$DB'")" == "1" ]] || pg "CREATE DATABASE $DB TEMPLATE seed_template"

  have=$(fly secrets list -a "$APP" --json | grep -o '"Name": *"[^"]*"' | cut -d'"' -f4 || true)
  gen() { grep -qx "$1" <<<"$have" || echo "$1=$(openssl rand -hex 32)"; }   # generated once, never rotated by a later `up`
  { gen SECRET_KEY; gen ENCRYPTION_KEY; gen ENV_TOKEN
    echo "ENV_NAME=$ENV"; echo "ALLOWED_HOSTS=$HOST,$APP.fly.dev"
    echo "DATABASE_URL=postgres://postgres:${PG_PASSWORD}@${PG_APP}.flycast:5432/${DB}"
    # ... plus the shared Redis URL and bucket credentials
  } | fly secrets import -a "$APP" --stage

  fly deploy -a "$APP" --config fly.preview.toml --remote-only --ha=false \
    --build-arg GIT_SHA="$(git rev-parse --short HEAD)" --build-arg GIT_BRANCH="$branch"
  echo "https://$HOST"
}

down() {
  [[ "$APP" =~ ^myapp-[a-z0-9-]+-[0-9a-f]{6}$ ]] || { echo "refusing to destroy $APP" >&2; exit 1; }
  if exists; then
    fly machine start -a "$APP" >/dev/null 2>&1 || true                 # it may be suspended
    fly ssh console -a "$APP" -q -C "python manage.py teardown_env" || echo "warning: cleanup failed; the sweeper will catch it" >&2
    fly apps destroy "$APP" --yes
  fi
  pg "DROP DATABASE IF EXISTS $DB WITH (FORCE)" || true
}

case "${1:-}" in up) up ;; down) down ;; name) echo "$ENV" ;; url) echo "https://$HOST" ;; esac

데모에서는 push하는 대신 제 노트북에서 직접 돌렸습니다. 브랜치 셋이 저장소 히스토리에 남기고 싶지 않은 일회용이었고, 출력이 흘러가는 걸 지켜보고 싶었기 때문입니다. 팀에서 쓸 때는 아무도 이걸 타이핑하지 않습니다. 아래에 나오는 라벨 워크플로가 정확히 이 스크립트를 돌리고, 지금부터 보이는 출력은 Actions 로그에 남을 그것입니다. 툴링 자체를 담은 브랜치에서 처음 실행했을 때 찍힌 출력입니다.

$ ./scripts/env up
== feature/branch-environments -> feature-branch-envir-c65cb4
New app created: myapp-feature-branch-envir-c65cb4
CREATE DATABASE
Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect.
==> Building image
image size: 139 MB
✔ Machine 1a2b3c4d5e6f78 [app] update finished: success
https://feature-branch-envir-c65cb4-dev.example.com

$ curl -s https://feature-branch-envir-c65cb4-dev.example.com/api/version/
{"environment": "feature-branch-envir-c65cb4", "branch": "feature/branch-environments", "commit": "a1b2c3d4", "region": "syd"}

명령에서 URL까지 2분 30초쯤이고, 대부분은 이미지 빌드입니다. 커밋 하나 더 한 뒤 같은 브랜치에서 두 번째 up을 하니 “New app created"도 “CREATE DATABASE"도 찍히지 않았고, 같은 시크릿 이름을 스테이징하되 생성된 것들은 다시 만들지 않았으며, 다시 빌드했습니다. 같은 URL, 새 커밋.

안에 든 선택 몇 가지는 한 문장씩 값을 합니다.

fly.preview.toml은 fly.toml이 아닙니다. 프로덕션은 API, WebSocket 서버, 백그라운드 워커를 별도 Fly 앱과 프로세스 그룹으로 굴려 각자 자기 지표로 스케일하게 하고, 그게 스택 글의 논지 전부입니다. 브랜치 환경은 스케일할 필요가 없습니다. 머신 하나여야 합니다. 그래서 프리뷰 설정은 프로세스가 하나이고, 컨테이너 entrypoint에 프리뷰 모드가 생겨 마이그레이션을 돌린 뒤 WebSocket을 켠 ASGI 서버 하나를 띄웁니다. Channels가 이미 ASGI 애플리케이션 하나 안에서 HTTP와 WebSocket 트래픽을 모두 라우팅하니 프로세스 하나가 앱 전체를 서빙합니다. 그 모드에서 동기 뷰는 thread-sensitive로, 대략 한 번에 요청 하나씩 돕니다. 프로덕션에서 제가 벗어난 바로 그 거래인데, 여기서는 정확히 맞는 거래입니다. 브랜치를 테스트하는 사람은 아무도 눈치채지 못하니까요.

# fly.preview.toml (the app name comes from `fly deploy -a`)
app = 'placeholder'
primary_region = 'syd'

[processes]
  app = "/app/entrypoint.sh preview"   # migrate, then one ASGI server for HTTP and WebSockets

[env]
  DJANGO_SETTINGS_MODULE = 'myapp.settings'
  DEBUG = 'False'

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0
  [[http_service.checks]]
    path = '/healthz'
    [http_service.checks.headers]
      Host = '127.0.0.1'               # the app's own hostname isn't known to a static file

[[vm]]
  size = 'shared-cpu-1x'
  memory = '1gb'

auto_stop_machines = "suspend", min_machines_running = 0. 점심 이후 아무도 열지 않은 브랜치 환경은 비용이 0이어야 합니다. stop 대신 suspend를 쓰면 30초 콜드 스타트 대신 504를 쫓다가 도달한 3초쯤의 재개를 얻는데, 여기서는 30초라도 견딜 만합니다. 데모 환경 셋 중 둘은 배포가 끝나고 1분 만에 fly apps list에서 이미 suspended였습니다.

fly.io/apps/myapp-feature-profile-tagl-fa8832

DEBUG = False, 프로덕션과 같은 settings 모듈. 브랜치 환경은 공개 URL입니다. 테스트에 중요한 모든 면(진짜 HTTPS, 진짜 쿠키, 같은 헬스 체크)에서 프로덕션처럼 굴고, 누군가를 다치게 할 수 있는 모든 면에서는 프로덕션과 달라야 합니다. 별도의 프리뷰용 settings 파일 대신, 차이는 env up이 설정하는 시크릿이 실어 나릅니다. 샌드박스 결제 키, 인증 서비스 관리자 자격 증명 없음, 그리고 아래의 모든 접두사를 켜는 ENV_NAME.

설정 하나가 모든 것을 자릅니다. ENV_NAME은 settings에 새로 들어간 유일한 손잡이이고, 네 곳에 적용됩니다.

ENV_NAME = os.getenv("ENV_NAME", "")
_prefix = f"{ENV_NAME}/" if ENV_NAME else ""

CACHES["default"]["KEY_PREFIX"] = ENV_NAME                           # every cache key
CHANNEL_LAYERS["default"]["CONFIG"]["prefix"] = f"{ENV_NAME}:asgi"  # Channels group and channel names
STORAGES["default"]["OPTIONS"]["location"] = f"{_prefix}media"      # uploads
STORAGES["staticfiles"]["OPTIONS"]["location"] = f"{_prefix}static"

channels 쪽을 빠뜨리면 두 브랜치의 WebSocket 서버가 그룹 이름을 공유해서, 한 환경에서 보낸 메시지가 다른 환경에 나타납니다. 하루를 잡아먹는 종류의 버그입니다.

다섯 번째 자리는 나중에 공유 Redis를 읽어 보고서야 찾았습니다. 504 글의 시작 락, 즉 이미지당 머신 하나가 마이그레이션을 돌리는 동안 나머지가 기다리게 하는 장치는 이미지 참조를 키로 삼고 있었습니다. 같은 커밋에서 빌드된 브랜치 환경 둘은 같은 이미지를 갖습니다. 두 번째 환경은 첫 번째의 “done” 마커를 발견하고, 마이그레이션되지 않은 자기 데이터베이스에 대한 자기 마이그레이션을 건너뛰었을 겁니다. 지금은 환경 이름이 키에 들어가고 키는 접두사 아래에 삽니다. 공유 인프라 설계가 계속 만들어 내는 종류의 문제입니다. 암묵적으로 “배포당"이던 모든 것을 명시적으로 환경당으로 만들어야 하고, 뭐가 암묵적이었는지는 들여다보기 전까지 모릅니다.

데이터베이스는 빈 상태에서 마이그레이션하는 게 아니라 복제합니다. 다음 절입니다.

데이터베이스: 몇 초 만에 복제되는 템플릿

#

브랜치 환경의 데이터베이스는 셋 중 하나일 수 있습니다. 모두와 공유. 우리를 여기까지 데려온 방식입니다. 빈 상태에서 마이그레이션하고 픽스처로 시드. 결정론적이지만, 픽스처는 실제 모양의 데이터만큼 좋았던 적이 없고 언제나 열여덟 달은 묵어 있습니다. 아니면 프로덕션 모양 스냅샷의 복제. 현실적인 행 수, 픽스처는 늘 채워져 있다고 가정했던 컬럼의 현실적인 null, 빈 테이블에서는 즉시 끝나지만 실제 테이블에서는 40분 걸리는 마이그레이션이 제 모습을 드러냅니다.

세 번째로 가되, 두 번째는 CI 전용 검사로 남깁니다. 그리고 세 번째를 브랜치마다 할 만큼 빠르게 만드는 건 대부분이 있는지도 잊은 Postgres 기능입니다.

-- Nightly, on the preview cluster. Restore last night's prod backup into seed_raw,
-- run the anonymiser, then freeze it as a template nobody can connect to.
ALTER DATABASE seed_raw RENAME TO seed_template;
UPDATE pg_database SET datistemplate = true, datallowconn = false WHERE datname = 'seed_template';

-- Per branch, in the time it takes to copy the files:
CREATE DATABASE env_feature_payments_retr_3f9a1c TEMPLATE seed_template;

CREATE DATABASE ... TEMPLATE은 클러스터 안에서의 파일 수준 복사입니다. 몇 기가바이트면 pg_restore가 걸리는 몇 분이 아니라 몇 초입니다. 복제되는 동안 템플릿에는 열린 연결이 있으면 안 되고, datallowconn = false가 그걸 강제합니다. 밤 작업이 살아 있는 템플릿 위에 복원하는 대신 seed_raw에 빌드하고 마지막에 이름을 바꾸는 이유이기도 합니다.

데모에서는 프로덕션 덤프 대신 손으로 템플릿을 만들었습니다. fly proxy로 프리뷰 클러스터에 터널을 뚫고, manage.py migrate, 그다음 저장소에 있는 시드 명령으로 작지만 현실적인 데이터 세트를 넣었습니다. 19메가바이트. 브랜치 셋이 올라오면서 클러스터에 복제본 셋이 나타났고, 각각 19 MB, 각각 1초 미만이었습니다.

$ fly ssh console -a myapp-preview-pg -C "psql ... -c '\l'"
             datname             | template | size
---------------------------------+----------+-------
 env_feature_branch_envir_c65cb4 | f        | 19 MB
 env_feature_profile_tagl_fa8832 | f        | 19 MB
 env_feature_profile_webs_dcb2e7 | f        | 19 MB
 seed_template                   | t        | 19 MB

프리뷰 클러스터는 관리형이 아닌 Fly Postgres 노드 하나, 1 GB 볼륨을 단 shared-cpu-1x로, 한 달에 2달러쯤입니다. 브랜치 환경은 사설 네트워크의 .flycast로 붙습니다. 공개된 것은 아무것도 없습니다.

익명화기는 선택이 아닙니다. 프로덕션 데이터가 -dev 호스트명에서 닿는 순간, 그건 프로덕션 데이터가 아니어야 합니다. 이름, 이메일, 전화번호, 주소, 자유 텍스트, 결제 참조, 토큰을 이름을 바꾸기 전에 전부 덮어씁니다. 익명화기가 실패하면 전날 밤 템플릿이 남고 누군가 메시지를 받습니다. 작은 일이고, 이 접근 전체를 개인정보 설문에 답하는 사람이 받아들일 수 있게 만드는 바로 그 일입니다.

entrypoint가 모든 이미지의 첫 부팅에서 migrate를 돌리므로, 브랜치 자신의 마이그레이션이 템플릿 위에 적용됩니다. “내 마이그레이션이 프로덕션 모양의 데이터에서 되나"의 첫 정직한 테스트이고, 누가 URL을 열어 보기 전에 일어납니다.

호스트명: 와일드카드 하나, Worker 하나, 그리고 문서가 알려주지 않은 두 가지

#

모든 환경에는 공개 HTTPS 호스트명이 필요하고, “공개"가 핵심입니다. 폰을 든 테스터, 다른 네트워크의 디자이너, VPN을 깔지 않을 프로덕트 매니저. Fly는 앱마다 myapp-$ENV.fly.dev를 공짜로 주고, 그것만으로도 됩니다. 하지만 *.fly.dev 호스트명에는 문제가 셋 있습니다. 보내기에 못생겼고, 앞에 Cloudflare가 없어서 프로덕션에 걸어 둔 보호가 하나도 적용되지 않으며, 자기 도메인에 두고 싶으면 환경마다 DNS 레코드 하나와 인증서 하나를 만들어야 하니 스위퍼가 치울 것이 하나 더 생깁니다.

그걸 전부 없애는 버전은 와일드카드 하나와 Cloudflare Worker 하나입니다. 계획은 *.dev.example.com이었습니다. 두 가지가 막았고, 같은 걸 계획하기 전에 둘 다 알아 둘 가치가 있습니다.

Universal SSL은 와일드카드 한 단계만 덮습니다. Cloudflare의 무료 인증서는 example.com과 *.example.com에 발급됩니다. *.dev.example.com은 덮지 않습니다. 두 단계 와일드카드에는 월 10달러의 Advanced Certificate Manager가 필요합니다. feature-branch-envir-c65cb4.dev.example.com으로의 첫 요청은 제 것이 무엇 하나 돌기도 전에 SSL 핸드셰이크 실패로 죽었습니다. 해결은 환경을 첫 라벨에 두는 것입니다. feature-branch-envir-c65cb4-dev.example.com. 이미 있는 인증서가 덮고, 이미 있는 프록시된 *.example.com 레코드가 덮습니다. 지어낸 서브도메인을 훑는 스캐너용 싱크홀로 제가 만들어 둔 그 레코드입니다. 그러니 환경에는 DNS가 아예 필요 없습니다.

Redirect Rules는 Workers보다 먼저 돕니다. 라우트를 걸어 두자 모든 -dev 호스트명이 Worker가 돌지도 않은 채 www 홈페이지로 301을 답했습니다. 싱크홀은 존 수준 리다이렉트 규칙 “그 밖의 모든 서브도메인 → www"이고, Cloudflare의 리다이렉트 단계는 Workers 단계보다 먼저 실행됩니다. 규칙에 절 하나가 필요했습니다. and not ends_with(http.host, "-dev.example.com"). 배포 스크립트가 up에서 넣고 down에서 빼는데, 누군가 손으로 고친 규칙이야말로 잊히는 것이기 때문입니다.

dash.cloudflare.com/…/example.com/rules/redirect-rules/…/edit

DNS 쪽은 이미 있던 그 레코드입니다.

dash.cloudflare.com/…/example.com/dns/records

그 둘을 치우고 나면 라우팅은 *-dev.example.com/*에 걸린 Worker 하나입니다.

// dev-router.js: <env>-dev.example.com -> myapp-<env>.fly.dev
const DEV_SUFFIX = "-dev.example.com";
const ENV_NAME = /^[a-z0-9-]+-[0-9a-f]{6}$/;   // slug-hash, as scripts/env names them

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (!url.hostname.endsWith(DEV_SUFFIX)) return new Response("not a dev hostname", { status: 404 });
    const env = url.hostname.slice(0, -DEV_SUFFIX.length);
    if (!ENV_NAME.test(env)) return new Response(`no such environment: ${env}`, { status: 404 });

    url.hostname = `myapp-${env}.fly.dev`;
    const upstream = new Request(url, request);
    upstream.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");

    const res = await fetch(upstream);
    const out = new Response(res.body, res);
    out.headers.set("X-Robots-Tag", "noindex, nofollow");   // a half-finished branch is not for search engines
    out.headers.set("X-Dev-Environment", env);
    return out;
  },
};

Cloudflare가 와일드카드에서 TLS를 종단하고, Worker가 라벨에서 Fly 호스트명을 계산하며, 머신까지의 구간은 Fly 자체의 *.fly.dev 인증서가 덮습니다. WebSocket 업그레이드는 fetch를 그대로 통과합니다. 그리고 라우트가 존에 있으니 Cloudflare가 프로덕션에 해 주는 모든 것을 쓸 수 있습니다. WAF 규칙, 속도 제한, 봇 대응 모드, 그리고 Access.

dash.cloudflare.com/…/example.com/workers

브랜치 셋을 동시에 띄우고, Worker 하나, 각 호스트명이 답한 것.

모든 200에는 Worker가 붙인 X-Robots-Tag: noindex, nofollow와 X-Dev-Environment: <env>가 함께 왔습니다. 404는 Fly에 묻기도 전에 Worker가 직접 낸 것입니다.

Cloudflare Access는 “공개"를 “닿아야 할 사람에게 닿음"으로 바꾸는 장치입니다. *-dev.example.com에 애플리케이션 하나, “@example.com 이메일이면 누구나” 정책 하나면 브라우저 방문자는 로그인 페이지를 한 번 보고 다시는 신경 쓰지 않습니다. 노트북의 디자이너, PM, 테스터는 그걸로 됩니다. 데모에는 넣지 않았습니다. 환경은 한 시간 동안 noindex를 달고 시드 데이터 말고는 아무것도 없이 떠 있었습니다.

모바일 앱은 덮지 못합니다. 네이티브 앱은 Access 로그인 리다이렉트를 완료할 수 없으니까요. 길은 둘입니다. Access는 로그인을 우회하는 서비스 토큰(CF-Access-Client-Id / CF-Access-Client-Secret 헤더 쌍)을 지원하고, 모바일 앱의 dev 메뉴가 dev 호스트명용 한 쌍을 실을 수 있습니다. 아니면 더 단순하게, /api/에 Access 우회를 넣고 Django가 로그인한 사용자나 환경의 ENV_TOKEN, 즉 env up이 바로 이 환경을 위해 생성한 그 토큰이 없는 요청을 거부하게 합니다. 어느 쪽이든 모바일 쪽은 기본 URL과 토큰 두 필드가 있는 dev 메뉴 화면이고, 테스터가 이미 설치한 앱이 이제 그 브랜치와 통신합니다. 새 빌드는 없습니다. OTA 업데이트 채널은 앱이 빌드된 대로 그대로 두고, API 기본 URL은 빌드 시점이 아니라 런타임 설정이며, 원래 그랬어야 합니다.

인증은 일부러 공유하는 유일한 공유 서비스입니다. 신원은 환경에 따라 다르지 않습니다. 테스터는 모든 브랜치에서 같은 계정으로 로그인하고 싶어 합니다. 승인된 도메인에 example.com을 넣은 인증 서비스의 dev 프로젝트 하나가 모든 -dev 호스트명을 덮고, 모든 환경이 그걸 상대로 ID 토큰을 검증합니다. 각 환경 데이터베이스의 사용자 테이블은 템플릿 사용자의 복사본이니, 테스터의 계정은 템플릿에 있던 모든 곳에 있습니다.

GitHub Actions로 프리뷰 환경 자동화하기: 이벤트가 들어가고 환경이 나온다

#

위의 모든 것을 손으로 하는 건 혼자 할 때는 괜찮습니다. 두 번째 개발자가 생기는 순간부터는 누가 기억해서가 아니라 git에서 뭔가 일어났기 때문에 일어나야 합니다. 자동화 전체는 워크플로 넷, 저장소 설정 하나, 룰셋 하나, GitHub environment 하나이고, 그 하나하나가 git 이벤트를 개발자가 손으로 돌리는 것과 같은 scripts/env 호출에 대응시킵니다. 따로 놀다 어긋날 CI 전용 경로는 없습니다.

라벨, push, delete 워크플로

#

# .github/workflows/branch-env.yml
name: branch environment
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed]
  delete:
  workflow_dispatch:
    inputs:
      branch: { description: branch to bring up without a PR, required: true }

concurrency:
  group: env-${{ github.head_ref || github.event.ref || inputs.branch }}
  cancel-in-progress: true

env:
  FLY_API_TOKEN: ${{ secrets.FLY_PREVIEW_TOKEN }}   # org-scoped deploy token; a separate preview org keeps it away from prod
  PG_PASSWORD: ${{ secrets.PREVIEW_PG_PASSWORD }}
  # ... the shared Redis URL and bucket credentials, the same way

jobs:
  up:
    # the gate: a PR carrying the `env` label, or someone asking for a branch by hand
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' && github.event.action != 'closed'
        && contains(github.event.pull_request.labels.*.name, 'env'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref || inputs.branch }}" }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - id: env
        env: { BRANCH: "${{ github.head_ref || inputs.branch }}" }
        run: scripts/env up && echo "url=$(scripts/env url)" >> "$GITHUB_OUTPUT"
      - if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: env
          message: "Branch environment: ${{ steps.env.outputs.url }}"

  down:
    # label removed, labelled PR closed or merged, or the branch itself deleted
    if: >-
      (github.event_name == 'pull_request' &&
        ((github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'env')) ||
         (github.event.action == 'unlabeled' && github.event.label.name == 'env'))) ||
      (github.event_name == 'delete' && github.event.ref_type == 'branch')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: BRANCH="${{ github.head_ref || github.event.ref }}" scripts/env down

게이트는 env 라벨이고, 제가 가장 강하게 주장하고 싶은 부분입니다. 게이트가 없으면 모든 브랜치가 앱 하나와 데이터베이스 복제본 하나를 비용으로 치릅니다. 노트북 백업용으로 push한 브랜치, 내일 squash될 스파이크, 봇이 새벽 3시에 연 의존성 업데이트까지요. 그래서 push만으로는 아무 일도 일어나지 않고, PR을 여는 것만으로도 아무 일도 일어나지 않습니다. PR에 env를 붙이면 환경이 올라오고, 라벨이 붙어 있는 동안의 push마다 갱신되고, 라벨을 떼거나 PR을 닫거나 머지하면 내려갑니다. 옵트인은 여전히 GitHub 이벤트이지 사람에게 하는 부탁이 아니고, 누가 볼 건지 아는 유일한 사람이 하는 클릭 한 번입니다. 고정 댓글이 사용자 인터페이스입니다. PR에 라벨을 붙이면 누구에게든 보낼 수 있는 URL이 담긴 댓글이 나타나고, push마다 쌓이는 대신 제자리에서 갱신됩니다. PR이 생기기 전에 올리고 싶은 브랜치는 workflow_dispatch가, 나머지는 노트북에서 돌리는 ./scripts/env up이 맡습니다.

알아 둘 만한 게이트가 둘 더 있습니다. 브랜치 이름 필터(branches: ['feature/**', 'fix/**'])는 PR이 필요 없지만 모든 기능 브랜치가 비용을 치릅니다. “드래프트가 아닌 모든 PR"은 가장 자동적이고, 팀이 PR을 늦게, 준비됐을 때만 연다면 맞는 선택입니다. 저는 라벨을 골랐습니다. 비용 결정을 맥락을 아는 사람에게 두고, 아무것도 닫지 않고 되돌릴 수 있기 때문입니다. 마음에 드는 부작용 하나. 포크에서 온 pull_request 실행은 시크릿을 받지 못하니, 포크는 환경을 띄울 수 없습니다.

concurrency는 보기보다 중요합니다. 한 브랜치에 push가 연달아 오면 앞선 배포를 경주시키는 대신 취소합니다. 같은 앱에 fly deploy 둘이 동시에 돌면 하나가 지는 걸로 끝납니다.

PR이 있던 것은 머지됐든 아니든 closed가 철거를 맡습니다. delete 이벤트는 workflow_dispatch로 띄웠는데 끝내 PR이 생기지 않은 브랜치를 위한 뒷받침이고, 브랜치가 실제로 삭제될 때만 발생합니다. 그건 저장소 설정 Automatically delete head branches이고, 기본은 꺼져 있습니다. 켜 두면 Merge를 누르는 것이 PR을 닫고 브랜치를 삭제하니, 두 이벤트 중 어느 하나만으로도 env down이 돌았을 겁니다. 머지 버튼이 철거입니다.

gh api -X PATCH repos/org/myapp -f delete_branch_on_merge=true

FLY_PREVIEW_TOKEN이 파일에서 위험한 줄입니다. 앱을 만들고 없앨 수 있으니, $APP이 브랜치 환경이 아닌 무언가가 되는 순간 프로덕션을 없앨 수도 있습니다. 가드는 둘이고 둘 다 두겠습니다. 토큰을 별도의 Fly 조직에 한정해 프로덕션 조직을 말 그대로 볼 수 없게 하는 것(데모에서는 새 조직에 결제 정보를 붙이는 걸 건너뛰려고 프로덕션 조직을 그대로 썼고, 두 번째 가드 하나에 기댔습니다), 그리고 down()이 slug-hash 패턴에 맞지 않는 앱 이름을 전부 거부하는 것.

브랜치 환경이 스스로 할 수 없는 검사

#

브랜치는 자기 마이그레이션만 봅니다. 그래서 중요한 검사는 pull request에서 main을 머지한 상태를 상대로 돌고, main이 요구하는 유일한 상태 검사입니다.

# .github/workflows/migrations-check.yml
name: migrations
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:18
        env: { POSTGRES_PASSWORD: ci, POSTGRES_DB: ci }
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci@localhost:5432/ci
      SECRET_KEY: ci-only
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - run: pip install -r requirements.txt
      - name: Merge main into the branch (a conflict here fails the check too)
        run: |
          git config user.email ci@example.com && git config user.name ci
          git merge --no-edit origin/main
      - name: One leaf in the migration graph
        run: python manage.py makemigrations --check --dry-run
      - name: The full chain applies from nothing
        run: python manage.py migrate --noinput

30초. 0042 / 0042 충돌을 릴리스 당일의 놀람에서 두 번째 개발자 PR의 빨간 체크로 바꿔 주는 것이 이겁니다. 아래 마이그레이션 절에서 실제로 걸리는 모습을 보여줍니다.

main의 규칙

#

브랜치가 한 달을 살거나 누군가 main에 직접 push하면 이 중 무엇도 버티지 못합니다. 규칙은 보호라기보다 환경을 작게, 마이그레이션을 최신으로 유지하기 위한 것입니다.

• main은 보호되고 언제나 배포 가능합니다. 현재 main을 기준으로 migrations 검사가 초록인 PR로만 머지합니다(strict 상태 검사이니, 지난주에 초록이던 PR은 main이 움직이면 다시 돕니다). 선형 이력, force-push 금지, 삭제 금지.
• 기능 브랜치는 짧습니다. 2주 열려 있는 브랜치는 main보다 2주 뒤처진 환경과, 남의 것과 충돌할 확률이 2주치 더 높은 마이그레이션을 갖습니다. 한 달짜리 기능은 플래그 뒤에서 조각조각 main에 머지합니다. 오래 사는 건 플래그이지 브랜치가 아닙니다.
• 브랜치 하나, 환경 하나, 데이터베이스 하나. 이미 이름이 강제합니다.
• 프로덕션에 가는 건 릴리스 태그뿐입니다. 이미지는 태그에서 한 번 빌드되고, 스테이징과 프로덕션은 그 이미지를 돌립니다. 다시 빌드하지 않습니다.
• migrations/를 건드리는 PR은 나머지 둘 중 하나가 리뷰합니다. 아래에.

룰셋으로는, gh api -X POST repos/org/myapp/rulesets --input ruleset-main.json으로 한 번 적용합니다.

{
  "name": "main", "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "strict_required_status_checks_policy": true,
                      "required_status_checks": [ { "context": "check" } ] } }
  ]
}

솔직한 주름 하나. 이 저장소는 GitHub Free 플랜의 비공개 저장소이고, Free에서 브랜치 보호와 룰셋은 공개 저장소에서만 쓸 수 있습니다. API는 403 Upgrade to GitHub Pro or make this repository public이라고 답합니다. delete_branch_on_merge 설정, environment, 워크플로는 Free에서도 전부 됩니다. 그러니 비공개 Free 저장소의 작은 팀에게 위 룰셋은 관례입니다. migrations 워크플로는 여전히 돌고 여전히 빨개지지만, 머지 버튼을 회색으로 만드는 것은 없습니다. 월 4달러짜리 결정이고, 저라면 두 번째 사람이 머지할 수 있게 되는 순간 하겠습니다.

develop 브랜치도 release/* 브랜치도 없습니다. Git-flow는 통합이 비싸서 묶어서 해야 한다는 전제로 설계됐습니다. 브랜치 환경이 통합을 싸게 만드니, 묶음이 사라집니다.

스테이징은 태그의 환경이고, 프로덕션은 승격이다

#

스테이징은 장치 전부를 재사용합니다. main의 v* 태그가 브랜치 이름 staging/v1.42.0으로 scripts/env up을 돌리고, 이름 규칙이 그걸 staging-v1-42-0-<hash>로 바꿉니다. 같은 템플릿 복제 데이터베이스, 같은 놀면 suspend되는 머신, 같은 호스트명 체계. 차이는 그 뒤에 오는 것입니다.

# .github/workflows/release.yml (abridged)
on:
  push:
    tags: ['v*']
jobs:
  staging:
    steps:
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env up
      - run: echo "image=$(fly image show -a "myapp-$(BRANCH=staging/$GITHUB_REF_NAME scripts/env name)" --json | jq -r '…')" >> "$GITHUB_OUTPUT"
  production:
    needs: staging
    environment: production        # required reviewer on this environment = the promotion gate
    steps:
      - run: fly deploy --config fly.api.toml --image "${{ needs.staging.outputs.image }}"
      - run: fly deploy --config fly.ws.toml  --image "${{ needs.staging.outputs.image }}"
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env down

production 잡은 필수 리뷰어가 있는 GitHub environment를 기다립니다. 누군가 스테이징을 보고 Approve를 누르면, 프로덕션은 스테이징이 돌린 같은 이미지를 참조로 받습니다. 다시 빌드하지 않습니다. 마지막 단계가 스테이징을 없애는 건 제 할 일을 다 했기 때문입니다. 아무도 승인하지 않으면 릴리스 후보는 거절된 것이고, 스위퍼가 그 “브랜치”(staging/v1.42.0은 origin에 존재한 적이 없습니다)가 생존 검사에 실패할 때 스테이징을 치웁니다. 스위퍼가 확인할 수 있는 이유 없이는 아무것도 존재할 수 없습니다.

밤마다 도는 스위퍼

#

# .github/workflows/sweep-envs.yml
on:
  schedule:
    - cron: '0 14 * * *'     # 02:00 NZST
  workflow_dispatch:
jobs:
  sweep:
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: scripts/sweep-envs

fetch-depth: 0은 스위퍼가 Actions가 기본으로 체크아웃하는 커밋 하나가 아니라 모든 원격 브랜치와 마지막 커밋 날짜를 필요로 하기 때문입니다. workflow_dispatch는 사고 뒤에 손으로 돌릴 수 있게 하려는 것입니다.

개발자가 실제로 하는 일

#

브랜치를 push하고, PR을 열고, 누군가 봐 줬으면 할 때 env 라벨을 붙입니다. 목록은 그게 전부입니다. 3분 안에 PR에 URL이 나타나고, push마다 갱신되고, PR이 머지되거나 닫히면 사라집니다. 팀원과 충돌했다면 마이그레이션 검사가 누구보다 먼저 알려줍니다. 차지할 스테이징이 없으니 아무도 스테이징을 차지하지 않고, 철거가 곧 머지이니 아무도 뭘 철거하지 않습니다.

그리고 이걸 세팅한 사람이 그 뒤로 브랜치마다 하는 일은, 없습니다. 공유 Postgres, Redis, 버킷은 한 번 프로비저닝하고, 시크릿은 Actions에 한 번 넣고, 그 뒤로 반복되는 일이라곤 월요일에 스위퍼 로그를 읽는 것뿐입니다. 티켓 큐도, 불러야 할 봇도, 프롬프트를 넣을 대상도 없습니다.

철거를 믿지 않는 철거

#

env down이 보통의 경우이고, 흥미로운 부분은 누가 치우느냐입니다. Redis 키와 버킷 객체는 공유 서비스의 것이고, down을 돌리는 노트북은 어느 쪽 자격 증명도 필요 없습니다. 환경 자신의 머신이 이미 그걸 갖고 있고 자기 접두사를 이미 알기 때문입니다. 그래서 down은 머신이 suspend돼 있으면 깨우고, 거기서 작은 정리 명령을 돌린 다음에야 앱을 없애고 데이터베이스를 드롭합니다. 환경이 스스로 뒷정리를 합니다.

$ BRANCH=feature/profile-website ./scripts/env down
redis: deleted 0 keys under feature-profile-webs-dcb2e7:*
bucket: deleted 278 objects under feature-profile-webs-dcb2e7/
Destroyed app myapp-feature-profile-webs-dcb2e7
DROP DATABASE

$ curl -s -o /dev/null -w '%{http_code}\n' https://feature-profile-webs-dcb2e7-dev.example.com/api/version/
530

530은 조정에 관한 요점을 다시 보여줍니다. Worker는 여전히 호스트명을 라우팅하고, Fly에는 아무것도 없으며, 아무도 Cloudflare에 알릴 필요가 없었습니다.

정리 명령은 ENV_NAME 없이는 실행을 거부합니다. 접두사가 비어 있으면 공유 버킷을 통째로 지우는 일이 되니까요. 그 가드가 이게 셸 스크립트 세 줄이 아니라 앱 안의 명령으로 존재하는 이유 전부입니다.

그래도 환경은 샙니다. GitHub Actions가 장애인 사이에 브랜치가 삭제됩니다. 개발자가 실험용으로 노트북에서 env up을 돌리고 push는 영영 안 합니다. fly apps destroy가 일시적으로 실패하고 || true가 삼킵니다. 석 달 뒤 앱이 마흔 개이고, 누군가 무슨 일이냐고 묻게 만드는 청구서가 옵니다.

그래서 첫 번째를 믿지 않는 두 번째 장치가 있습니다. 위 표의 밤마다 도는 스위퍼입니다. 모든 myapp-* 앱을 나열하고, 각각이 어느 브랜치 것인지 알아내고, 브랜치가 사라졌거나 7일간 push가 없는 것을 전부 없앱니다. 일주일 논 브랜치에 살아 있는 URL은 필요 없고, 다음 push가 2분 만에 다시 만듭니다. 해시는 되돌릴 수 없으니, 스위퍼는 살아 있는 모든 브랜치의 환경 이름을 계산해 그 집합에 없는 앱을 전부 없앤 뒤, 뒤에 앱이 없는 env_* 데이터베이스를 드롭합니다.

#!/usr/bin/env bash
# scripts/sweep-envs: nightly
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; TTL_DAYS=${TTL_DAYS:-7}
cutoff=$(( $(date +%s) - TTL_DAYS*86400 ))

git fetch --prune --quiet origin
live=""
while IFS=$'\t' read -r ts branch; do
  [[ "$branch" == "main" ]] && continue
  (( ts >= cutoff )) || continue
  live+="$(BRANCH="$branch" scripts/env name)"$'\n'
done < <(git for-each-ref --format='%(committerdate:unix)%09%(refname:short)' refs/remotes/origin | sed 's#^\([0-9]*\)\torigin/#\1\t#')

apps=$(fly apps list --org "$ORG" --json | grep -o '"Name": *"myapp-[^"]*"' | cut -d'"' -f4)
for app in $apps; do
  env="${app#myapp-}"
  [[ "$env" =~ ^[a-z0-9-]+-[0-9a-f]{6}$ ]] || continue       # not a branch environment (e.g. myapp-preview-pg)
  grep -qx "$env" <<<"$live" && continue
  echo "sweeping $app: branch gone or idle > ${TTL_DAYS}d"
  ENV_OVERRIDE="$env" scripts/env down || true
done
# ...then any env_* database with no app: DROP DATABASE.

데모 브랜치는 어느 것도 push된 적이 없으니(위의 노트북 실행), 스위퍼 입장에서는 전부 사라진 것이었습니다. 누군가 노트북에서 띄우고 끝내 push하지 않은 스파이크가 일주일 뒤에 놓일 상태가 정확히 이것입니다. 남은 둘을, tagline 환경이 써 둔 Redis 키까지 포함해 해체했습니다.

$ ./scripts/sweep-envs
sweeping myapp-feature-branch-envir-c65cb4: branch gone or idle > 7d
redis: deleted 0 keys under feature-branch-envir-c65cb4:*
bucket: deleted 322 objects under feature-branch-envir-c65cb4/
Destroyed app myapp-feature-branch-envir-c65cb4
DROP DATABASE
sweeping myapp-feature-profile-tagl-fa8832: branch gone or idle > 7d
redis: deleted 3 keys under feature-profile-tagl-fa8832:*
bucket: deleted 278 objects under feature-profile-tagl-fa8832/
Destroyed app myapp-feature-profile-tagl-fa8832
DROP DATABASE

$ fly apps list --org myapp-preview | grep myapp-
 myapp-preview-pg │ myapp-preview │ deployed

(작게 문 것 하나. macOS에는 연관 배열이 없는 bash 3이 딸려 옵니다. 스위퍼 첫 버전은 그걸 썼다가 제 노트북에서 declare -A에서 죽었습니다. 위 버전은 줄바꿈으로 구분한 목록을 써서 어디서든 돕니다.)

비용은 즐거운 부분입니다. suspend된 머신은 rootfs 값만 내고, 한 달에 몇 센트입니다. 데이터베이스는 이미 값을 치른 볼륨 위의 19 MB입니다. Redis는 종량제 플랜으로, 명령 10만 개에 20센트인데 브랜치 테스트 규모에서는 0으로 반올림됩니다. 버킷 접두사는 저장한 만큼 냅니다. 공유 Postgres 노드가 유일한 고정 항목으로, 한 달에 2달러쯤입니다. 활성 브랜치 스무 개는 항상 켜진 shared-cpu-1x 하나 값쯤이고, 스위퍼가 그걸 이백이 아니라 스물로 유지합니다. 데모 전체, 즉 한 시간 동안의 환경 셋과 공유 부품은 그동안 마신 커피보다 쌌습니다.

브랜치를 가로지르는 마이그레이션, 경고해 줄 공유 데이터베이스 없이

#

개발자마다 기능을 처음부터 끝까지 맡으면 모든 브랜치에 마이그레이션이 들어 있습니다. 그래서 이 절이 중요한 절입니다.

공유 환경 세계를 떠날 때 사람들이 놓치는 것이 있습니다. 모두가 dev 데이터베이스 하나에 배포할 때 마이그레이션 충돌은 즉시, 아프게 드러났지만, 어쨌든 드러났습니다. 마이그레이션 하나가 돌고, 다음 배포가 실패하고, 누군가 그날 오후에 고쳤습니다. 브랜치마다 데이터베이스가 있으면 각 마이그레이션은 자기 환경에서 완벽하게 돌고, 둘은 두 번째가 main에 머지될 때 처음 만납니다. 부주의하게 하면 충돌이 싸던 dev에서 싸지 않은 릴리스로 옮겨 갑니다.

규칙 넷, 전부 CI로 강제할 수 있어서 아무도 기억할 필요가 없습니다.

1. main을 머지한 상태에서 마이그레이션 그래프에 리프가 둘이면 CI가 실패합니다. makemigrations --check는 모델과 마이그레이션이 어긋난 걸 잡지만, 중요한 충돌은 두 브랜치가 둘 다 0042_*를 추가한 것입니다. 브랜치 단독이 아니라 main에 머지된 브랜치를 상대로 확인합니다.

git fetch origin main
git merge --no-commit --no-ff origin/main || { echo "merge conflict"; exit 1; }
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan 2>&1 | grep -q "Conflicting migrations" && exit 1

이건 제가 일부러 일으킨 것입니다. 데모 브랜치 셋 중 둘, feature/profile-tagline과 feature/profile-website가 각각 마이그레이션 하나로 사용자 프로필 모델에 필드 하나를 추가했고, 각 환경은 올라오면서 자기 것을 적용했습니다. 새 컬럼은 있어야 할 곳에만 있었습니다.

env_feature_branch_envir_c65cb4      (no new column)
env_feature_profile_tagl_fa8832      tagline
env_feature_profile_webs_dcb2e7      website

둘 다 0042_*입니다. 어느 브랜치도 상대 것을 볼 수 없으니, 어느 환경도 문제가 있다고 말해 주지 못합니다. 하나를 다른 하나에 머지하면 검사가 말해 줍니다.

$ git merge --no-commit --no-ff feature/profile-tagline
$ python manage.py makemigrations --check --dry-run
CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph:
  (0042_profile_tagline, 0042_profile_website in accounts).
To fix them run 'python manage.py makemigrations --merge'

$ python manage.py makemigrations --merge --noinput
Created new merge migration accounts/migrations/0043_merge_20260919_0324.py
    dependencies = [
        ('accounts', '0042_profile_tagline'),
        ('accounts', '0042_profile_website'),
    ]

두 번째 작성자가 자기 브랜치에서, 자기 환경에서, 아무도 귀찮게 하지 않고 그 --merge를 돌리면, 다음 env up이 자기 복제본 위에 0043을 적용합니다. (이 경우 git이 먼저 텍스트 충돌도 표시했습니다. 두 필드가 모델 파일의 같은 줄에 추가됐기 때문입니다. 현실적이고, 텍스트 충돌이 해소되기 전까지 마이그레이션 충돌을 가린다는 걸 알아 둘 가치가 있습니다.)

2. 마이그레이션은 이전 릴리스의 코드와 하위 호환됩니다. 배포 중에는 새 스키마와 옛 코드가 공존하는 창이 있고, 머신이 롤백되면 그 반대도 있습니다. 컬럼은 nullable이거나 기본값을 갖게 추가하고, 한 번에 이름을 바꾸지 않으며, 현재 릴리스가 여전히 읽는 것은 절대 드롭하지 않습니다. 추가하고, 배포하고, 백필하고, 코드를 바꾸고, 나중 릴리스에서 드롭합니다. expand and contract입니다. 여기서 더 중요한 이유는 일회용 환경이 배포를 잦게 만들어서 그 창 안에 더 자주 들어가기 때문입니다. 태그별 스테이징이 그걸 리허설하는 곳입니다.

3. CI는 빈 데이터베이스에 0부터 마이그레이션도 합니다. 템플릿 복제는 “내 마이그레이션이 현실적인 데이터에 적용되나"를 테스트합니다. 빈 실행은 “전체 체인이 여전히 무에서 되나"를 테스트하고, 이전 데이터 마이그레이션이 뭔가 채워 놨다고 가정한 마이그레이션을 잡습니다. 30초이고, 그러지 않으면 다음 새 노트북을 기다리는 부류의 버그를 잡습니다.

4. 스키마 변경에는 두 번째 눈이 붙습니다. 작은 팀에는 CODEOWNERS 파일이 필요 없지만, 규칙은 필요합니다. migrations/를 건드리는 PR은 머지 전에 팀원 하나가 리뷰하고, 리뷰어의 일은 SQL을 확인하는 게 아닙니다. 자기나 팀의 다른 누군가가 이번 2주 안에 같은 테이블을 건드리고 있는지 알고, 그렇다고 말하는 것입니다. 개발자가 열댓 명을 넘어가면 그 지식이 한 사람 머리에 다 들어가지 않으니, 그때는 migrations/에 CODEOWNERS 항목을 두는 게 제값을 합니다. 어떤 툴링도 이걸 대신하지 못합니다. 기계적인 건 툴링이 전부 잡아 주니 2분짜리 일이고, 옛 공유 환경 세계에서 간직할 가치가 있는 유일한 부분입니다. 두 사람이 곧 부딪힐 걸 알아차리는 순간.

버전 관리, URL이 무엇을 돌리는지 말해 주도록

#

공유 환경 하나일 때 “스테이징에 뭐 올라가 있어요"는 채팅으로 묻는 질문이었습니다. 여럿이면 환경의 속성이어야 하고, 아니면 모든 버그 리포트가 고고학으로 시작합니다.

• 모든 이미지는 커밋 SHA를 지니고 앱이 그걸 노출합니다. fly deploy --build-arg GIT_SHA=... --build-arg GIT_BRANCH=...가 이미지에 환경 변수로 찍고, /api/version/이 환경 이름, 리전과 함께 돌려줍니다(위 출력 참고). “feature-profile-tagl-fa8832에서 깨져요"에 누구나 제일 먼저 하는 일은 생각한 커밋을 돌리고 있는지 확인하는 것입니다. 첫 데모 환경은 툴링이 커밋되기 한 커밋 전의 작업 트리에서 배포됐고, 엔드포인트가 그렇게 말했습니다. 제가 예상한 SHA가 아니라 이전 커밋을 보고했죠.
• ENVIRONMENT=$ENV가 모든 로그 줄과 에러 트래커의 environment 태그에 있습니다. 브랜치 오류가 프로덕션 오류 추적을 더럽히지 않고, 클릭 한 번으로 걸러집니다.
• 브랜치는 SHA를, 릴리스는 태그를 갖습니다. feature-payments-retr-3f9a1c에는 버전 번호가 없습니다. 커밋이 있습니다. 스테이징과 프로덕션에는 v1.42.0이 있습니다.
• 모바일 앱은 URL이 아니라 최소 API 버전을 지닙니다. dev 메뉴의 URL 필드가 테스터가 실제 폰을 브랜치에 향하게 하는 방법이고, API 스키마 버전을 실은 버전 엔드포인트가 앱이 이해할 수 있는 상대와 통신하는지 아는 방법입니다.

이걸로 해결되지 않는 것

#

같이 있어야만 말이 되는 기능 둘은 해결하지 못합니다. 브랜치 환경은 브랜치 하나를 보여줍니다. 답은 둘 다 플래그 뒤에 머지하고 main을 보는 것이고, main을 따라가는 상시 환경 하나(main-dev.example.com, 머지마다 재배포)로 할 수 있습니다. 제가 남겨 둘 유일한 장수 비프로덕션 환경이고, 아무도 거기에 배포하지 않습니다. 다음 릴리스가 무엇이 될지 보는 용도입니다.

등록된 콜백을 요구하면서 와일드카드를 받지 않는 제공자는 해결하지 못합니다. 제가 쓰는 인증 서비스는 상위 도메인을 받으니 example.com이 모든 -dev 브랜치 호스트명을 덮습니다. 일부 OAuth와 결제 제공자는 안 되고, 그런 경우 Worker가 마지막으로 차지한 환경으로 라우팅하는 공유 호스트명 하나를 둡니다. 작은 것에 걸린 작은 락이고, 모든 것에 걸린 락보다 훨씬 낫습니다.

마이그레이션의 사람 쪽은 해결하지 못합니다. 툴링은 기계적 충돌을 잡습니다. 같은 2주 안에 둘이 같은 개념을 양립 불가능하게 모델링하는 건 잡지 못하고, 그걸 고치는 유일한 방법은 한 명이 알아차리는 마이그레이션 리뷰입니다.

당신의 환경에서 확인해 볼 것

#

공유 dev나 스테이징이 있고 그걸 예약하는 채팅 스레드가 있다면:

1. 완성된 브랜치가 작성자 아닌 누군가가 도는 걸 볼 수 있기까지 얼마나 기다립니까? 한 시간 넘으면 그 락 값을 전달 시간으로 치르고 있는 것이고, 작은 팀이면 팀의 상당 부분이 기다리는 겁니다.
2. 공유 데이터베이스는 얼마나 자주 초기화되고, 그때 누가 작업을 잃습니까?
3. 새 개발자가 첫날에 누구에게 아무것도 묻지 않고 자기 브랜치가 도는 공개 URL을 얻을 수 있습니까? 물어야 하는 것이 무엇이든, 그게 제일 먼저 자동화할 것입니다.
4. 새 환경은 현실적인 데이터에서 시작합니까? 빈 상태에서 시작하면, 처음으로 못 잡을 버그는 빈 테이블에서는 멀쩡하고 실제 테이블에서는 40분 걸리는 마이그레이션입니다.
5. 비프로덕션 호스팅에 모두가 잊고 한 달 뒤에도 여전히 존재할 것이 있습니까? 있다면 다른 무엇보다 먼저 스위퍼를 쓰세요. 누수는 첫날부터 시작됩니다.

채팅 스레드의 그 질문이 사라지는 건 사람들이 묻기를 그만둬서가 아니라, 답이 언제나 “네, 당신 것에서요"이기 때문입니다.

빌드와 테스트 단계를 GitHub Actions YAML에 직접 쓰는 팀이 많습니다. 그 자체로는 잘 돌아가죠. 문제는 같은 빌드를 내 노트북에서 돌려보고 싶어질 때, 혹은 누군가 “GitLab으로 옮기면 어때요?“라고 말하는 순간입니다. 파이프라인 전체가 특정 벤더의 설정 포맷에 용접돼 있다는 걸 그제야 깨닫게 되니까요. 요즘 제 방식은 꽤 심심합니다. 진짜 로직은 Docker Compose에 두고, CI 도구는 그걸 호출하는 역할만 시키는 겁니다.

빌드 로직을 Actions YAML에 넣지 않는 이유

#

가장 뻔한 문제는 종속성입니다. Actions 워크플로우는 GitLab, Bitbucket, Jenkins 어디에서도 통하지 않으니, 빌드 단계가 워크플로우 파일 안에 있으면 플랫폼을 바꿀 때 전부 다시 써야 합니다. 그런 작업에 시간을 배정해 주는 조직은 본 적이 없네요.

더 은근하게 괴로운 문제는 파이프라인을 로컬에서 돌릴 수 없다는 점입니다. 빌드 수정을 확인할 방법이 “커밋 푸시하고 Actions 탭 쳐다보기"뿐이면, git 히스토리는 금세 “fix ci”, “fix ci again” 같은 커밋으로 가득 찹니다. Compose 파일은 제 노트북에서나 러너에서나 똑같이 돌아가니, “제 컴퓨터에서는 되는데요” 같은 논쟁도 대부분 시작 전에 끝나고요.

그리고 YAML은 자랍니다. 처음엔 깔끔한 20줄이던 것이 캐싱 트릭과 조건문이 붙으면서 300줄이 되고, 개발자들은 Git에 더해 CI 방언까지 배워야 하죠. 스크립트 하나는 한 가지 일만 해야 하는데, 거대한 워크플로우 파일은 모든 걸 한꺼번에 떠안기 마련입니다.

Compose를 쓰면 이 분담이 깔끔해집니다. 빌드와 테스트는 Compose 파일의 책임, CI 플랫폼은 푸시가 있을 때마다 그걸 실행해 주는 존재일 뿐입니다.

설정 방법

#

1. 먼저 Dockerfile을 만들어 이미지 빌드 방법을 한곳에 모읍니다:

# 공식 Node.js 런타임을 베이스 이미지로 사용
FROM node:14

# 컨테이너 내 작업 디렉토리 설정
WORKDIR /app

# package.json 및 package-lock.json 파일을 컨테이너로 복사
COPY package*.json ./

# 종속성 설치
RUN npm install

# 나머지 애플리케이션 코드를 컨테이너로 복사
COPY . .

# 앱이 실행되는 포트 노출
EXPOSE 3000

# 애플리케이션을 실행하는 명령 정의
CMD ["npm", "start"]

2. 다음으로 빌드와 테스트에 필요한 서비스를 정의하는 docker-compose.build.yaml을 만듭니다.

   services:
     app:
       image: myprivaterepo.com/image:latest
       build: .
       volumes:
         - .:/app
       command: sh -c "npm install && npm test"

3. 로컬에서 먼저 돌려봅니다. 사실 이게 이 방식의 핵심이죠.

   docker compose -f docker-compose.build.yaml build

4. 여기까지 동작하면 GitHub Actions 워크플로우(다른 CI 플랫폼이라도 마찬가지입니다)는 단순한 오케스트레이터로 줄어듭니다.

   name: CI/CD Pipeline
   on: [push, pull_request]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v1
         - name: Build and Test with Docker Compose
           run: docker compose -f docker-compose.build.yaml build
         - name: Push the image referenced in the docker compose file
           run: docker compose -f docker-compose.build.yaml push

이제 CI 도구가 하는 일은 빌드와 푸시, 딱 두 가지입니다. 이해할 가치가 있는 부분은 전부, 어떤 플랫폼에서든 어떤 새 팀원이든 바로 실행해 볼 수 있는 파일 안에 있습니다.

이미지 푸시

#

Compose 파일의 반가운 부수 효과 하나는 푸시가 아주 쉬워진다는 겁니다. Docker는 이미지 이름을 보고 푸시할 곳을 판단합니다. image: myprivaterepo.com/image:latest라면 myprivaterepo.com으로 푸시됩니다. 프라이빗 레지스트리라면 액세스 토큰이 필요하니, 그 부분은 사용하는 레지스트리 서비스의 문서를 참고하세요.

지금 GitHub Actions에 만족하고 있다면 서두를 이유는 없습니다. 다만 언젠가 공급자를 바꾸는 날이 오면, 마이그레이션이 “YAML 300줄 이식"이 아니라 “명령어 두 개 복사"로 끝납니다. 그리고 그날이 오기 전까지는, 빌드 디버깅을 커밋 스팸 없이 로컬에서 차분히 할 수 있고요.