GitHub Actions 배포, import 오류로 서비스 중단? 3단계 안전망으로 해결!

GitHub Actions 배포, import 오류로 서비스 중단? 3단계 안전망으로 해결!

기존 GitHub Actions 배포 파이프라인은 새 코드의 불안정성이나 예기치 못한 import 오류가 발생했을 때 운영 서비스에 직접적인 영향을 미칠 위험이 있었습니다. 특히 Pydantic v2 마이그레이션과 같은 변경 사항은 이런 위험을 더욱 증폭시켰죠.

시도와 함정

처음에는 간단하게 GET /health 엔드포인트를 추가해서 서비스 프로세스가 살아있는지만 확인했습니다. 하지만 이게 전부가 아니더군요. DB 연결 같은 실제 서비스 가능 여부는 전혀 알 수 없었습니다.

# Health Endpoint 추가 (deef1e25)
# GET /health

그 다음으로 배포 파이프라인에서 systemctl restart 전에 python -c "from main import app" 명령으로 코드 import 유효성을 사전 검증하는 시도를 했습니다. 하지만 이것도 import 자체는 성공해도, 실제 서비스 시작 시점에 터지는 오류는 막지 못했습니다.

# 사전 import 검증 강화 (deef1e25)
python -c "from main import app"

결정적으로, /health/ready 엔드포인트가 제대로 응답하지 않으면 이전 커밋(HEAD~1)으로 자동 롤백하고 서비스를 재시작하는 로직을 추가했습니다. 이 과정에서 Gunicorn의 --preload 옵션을 제거하는 것도 중요했습니다. 이 옵션 때문에 단일 워커의 import 에러가 전체 서비스 중단으로 이어지는 경우가 있었거든요.

# 자동 롤백 기능 구현 (deef1e25)
# GET /health/ready (DB 연결 포함 레디니스 확인)
git reset --hard HEAD~1

# Gunicorn --preload 제거 및 워커별 독립 import (6fa120b9)
# --preload 옵션 제거

원인

가장 큰 문제는 배포 후 실제 서비스 가용성을 제대로 검증하지 못했다는 점이었습니다. 단순히 프로세스가 떠 있는 것만으로는 부족했고, DB 연결과 같은 실제 의존성까지 확인해야 했습니다. 또한 Gunicorn의 --preload 옵션은 모든 워커가 동일한 프로세스에서 코드를 미리 로드하기 때문에, 한 워커에서 발생하는 import 오류가 전체 서비스에 치명적인 영향을 미쳤습니다.

해결

최종적으로 GitHub Actions 배포 파이프라인에 다음과 같은 3단계 안전망을 구축했습니다.

1. 사전 import 검증: 배포 스크립트에서 python -c "from main import app" 명령으로 코드 import 유효성을 미리 확인합니다.
2. 상세 헬스 체크 기반 배포 후 검증: DB 연결까지 확인하는 /health/ready 엔드포인트를 활용하여 서비스가 실제로 준비되었는지 확인합니다.
3. 자동 롤백: /health/ready 엔드포인트가 비정상 응답할 경우, 이전 커밋(HEAD~1)으로 자동 git reset --hard 후 서비스를 재시작하여 빠르게 복구합니다.

여기에 더해 Gunicorn의 --preload 옵션을 제거하여 각 워커가 독립적으로 코드를 import 하도록 변경했습니다. 이를 통해 단일 워커의 import 실패가 전체 서비스 중단으로 이어지는 것을 방지했습니다.

# GitHub Actions deploy.yml 예시 (일부)
# ...
# 사전 import 검증
- name: Pre-import check
  run: python -c "from main import app"
서비스 재시작 및 헬스 체크

name: Restart service and check health
run: |
sudo systemctl restart myapp.service
/health/ready 응답 대기 및 검증 (timeoout 설정)
실패 시 자동 롤백 로직 실행


Gunicorn systemd unit 파일 수정 예시 (update_systemd_unit.sh 스크립트 활용)
ExecStart=/path/to/gunicorn --workers 4 --bind 0.0.0.0:8000 main:app --preload  -> --preload 제거

결과

• 배포 과정에서의 import 오류나 코드 불안정성으로 인한 서비스 중단 위험이 크게 감소했습니다.
• /health/ready 기반의 자동 롤백 시스템 덕분에 배포 실패 시에도 빠르게 이전 안정적인 상태로 복구할 수 있게 되었습니다.
• 운영 서비스의 전반적인 안정성이 크게 향상되었습니다.

정리 — 같은 함정 안 빠지려면

• [ ] 배포 파이프라인에 실제 서비스 가용성을 판단할 수 있는 상세한 헬스 체크 로직(GET /health/ready 등)을 통합하세요.
• [ ] 헬스 체크 실패 시 자동으로 이전 버전으로 롤백하는 기능을 구현하여 복구 시간을 단축하세요.
• [ ] Gunicorn의 --preload 옵션은 편리하지만, 워커별 독립 import 방식이 더 높은 안정성을 제공할 수 있음을 인지하고 상황에 맞게 선택하세요. (메모리 사용량 증가 트레이드오프 고려)
• [ ] 배포 전 사전 import 검증 단계를 추가하여 잠재적인 문제를 미리 발견하세요.