website: CD 파이프라인에 스모크 테스트 도입

배포 워크플로우에 실제 공개 도메인을 대상으로 한 스모크 테스트를 추가해, 배포 후 핵심 조회 API들이 실제로 정상 응답하는지 자동 확인하도록 했습니다.

요약

2026년 7월 23일, feat(cd): 스모크 테스트 도입 — 배포 후 핵심 조회 API 실동작 확인이라는 메시지로 PR #160을 머지했습니다. 변경된 파일은 .github/workflows/cd.yml 하나뿐이지만, 배포 파이프라인의 신뢰도를 높이는 데 있어 꽤 의미 있는 변경입니다. 21줄이 추가되고 4줄이 삭제되면서, 그동안 주석으로만 남아있던 "엔드포인트 구현 후 추가" 자리에 실제 검증 로직이 들어갔습니다.

배경 및 목적

기존 CD 워크플로우에는 헬스체크 단계가 있었지만, 이는 "앱이 떴다"는 사실만 확인해줄 뿐이었습니다. 실제로 사용자가 겪는 경로 — DNS, TLS, nginx 라우팅까지 거친 최종 응답 — 은 검증하지 못하는 구조였죠. 스모크 테스트 스텝 자체는 이미 존재했지만 내부 로직은 비어있는 상태였고, 커밋 패치의 주석에 남아있던 # 엔드포인트 구현 후 아래에 추가라는 문구가 이 공백을 잘 보여줍니다.

배포는 성공했는데 정작 API가 502를 뱉거나 nginx 라우팅이 꼬여있는 상황을 방치하지 않기 위해, 배포 직후 자동으로 핵심 조회 API들을 두드려보는 단계가 필요했습니다.

구현 내용

변경된 파일

.github/workflows/cd.yml (+21 / -4)

핵심 변경사항

기존에는 BASE_URL을 http:// $secr e t s . O C I_{H} O S T :$ {{ steps.config.outputs.port }} 형태로, 즉 내부 IP와 포트로 직접 접근하는 방식이었습니다. 이를 실제 공개 도메인으로 바꿨습니다.

BASE_URL="https://api.${{ steps.config.outputs.env }}.likelion-khu.com"

그리고 인증 없이 이미 공개된 조회 엔드포인트 4개(/api/members, /api/staff, /api/posts, /api/projects)를 순회하며 상태 코드를 확인하는 반복문을 추가했습니다.

FAILED=0
for path in /api/members /api/staff /api/posts /api/projects; do
  STATUS= $(c u r l - s - o / d e v / n u l l - w^{'}$ BASE_URL$path" || echo "000")
  if [ "$STATUS" == "200" ]; then
    echo "✅ [ $p a t h] H T T P$ STATUS"
  else
    echo "❌ [ $p a t h] H T T P$ {STATUS}"
    FAILED=1
  fi
done

if [ "$FAILED" == "1" ]; then
  echo "=== 스모크 테스트 실패 ==="
  exit 1
fi

패치의 코드 주석에도 의도가 명확히 남아있습니다. "localhost가 아니라 실제 공개 도메인(nginx 뒤)으로 찌른다"는 표현이 이번 변경의 핵심을 정확히 짚고 있습니다.

기술적 의사결정

내부 IP:포트 방식 대신 공개 도메인을 선택한 이유

헬스체크는 애플리케이션 프로세스가 살아있는지만 확인합니다. 하지만 실제 사용자는 nginx를 거치고, TLS 인증서를 거치고, DNS를 거쳐 API에 도달합니다. 이 경로 전체를 검증하지 않으면 "앱은 떠 있는데 사용자는 접근 못 하는" 상황을 배포 직후에 잡아낼 수 없습니다. 그래서 http://OCI_HOST:PORT가 아니라 https://api.{env}.likelion-khu.com으로 요청을 보내도록 바꾼 것이 이번 변경의 핵심 결정입니다.

대상 엔드포인트를 인증 없는 조회 API로 한정

어드민류 엔드포인트는 대상에서 제외하고, 이미 공개돼 있는 조회 엔드포인트만 스모크 테스트 대상으로 삼았습니다. 인증 토큰을 워크플로우에 심어야 하는 복잡성을 피하면서도, 가장 트래픽이 많이 몰릴 핵심 API들의 정상 동작은 확실히 검증할 수 있는 실용적인 선택입니다.

exit 1로 실패 전파

응답 코드가 200이 아닌 경우 FAILED 플래그를 세우고, 루프가 끝난 뒤 워크플로우 자체를 실패 처리하도록 했습니다. 이렇게 해야 다음 단계(아마도 롤백)로 이어지는 조건 분기가 제대로 작동합니다. 실제로 패치 마지막 줄을 보면 스모크 테스트 다음 스텝이 "롤백"인 것을 확인할 수 있는데, 스모크 테스트 실패가 곧 롤백 트리거로 이어지는 구조로 보입니다.

배운 점 및 개선점

주석으로만 남겨뒀던 TODO를 실제 구현으로 채우는 작업이었는데, 막상 구현하면서 헬스체크와 스모크 테스트의 역할 차이를 다시 한번 명확히 정리하게 됐습니다. 헬스체크는 프로세스 생존 확인, 스모크 테스트는 실제 클라이언트 경로 검증이라는 구분이 이번 변경으로 코드에 그대로 드러난 셈입니다.

앞으로는 대상 엔드포인트를 하드코딩된 4개 경로 대신 설정 파일이나 별도 목록으로 관리하면 엔드포인트가 늘어날 때마다 워크플로우 파일을 직접 수정하지 않아도 될 것 같습니다. 또한 지금은 단순히 200 여부만 확인하는데, 응답 본문의 최소 스키마까지 검증하면 더 견고한 테스트가 될 수 있을 것 같습니다.

요약