배포 가능한 상태: 브랜치의 최신 커밋이 정적 분석/테스트(단위/전체)/빌드/Docker 이미지 빌드까지 모두 통과해서, 그대로 운영 서버에 배포해도 문제가 없는 상태

---

우리 팀은 현재 서비스 개발이 본격화되면서 코드 변경 및 통합 빈도가 급격히 증가하고 있다.

• 개발 인력 구성: 총 6명
  • 풀스택(FE/BE) 2명: Spring Boot 및 React 기능 개발 담당
  • AI 2명: FastAPI 기반 AI 기능 개발 담당
  • 클라우드 2명: 인프라 구성, 배포 및 운영 자동화 담당
• 기술 스택:
  • Backend (Java, Spring Boot, Gradle)
  • Frontend (TypeScript, React, Vite)
  • AI Server (Python, FastAPI)
  • Database & Cache

---

개발 인원이 각자의 로컬 환경에서 작업하고 수동으로 코드를 통합하면서 다음과 같은 문제가 필연적으로 발생한다.

발생 문제	구체적인 원인 및 영향
Merge 이후 빌드 실패	로컬에서는 정상 동작했으나, 다른 팀원의 최신 코드와 통합되었을 때 의존성 충돌이나 컴파일 오류 발생
미검증 코드의 dev 브랜치 유입	바쁜 개발 일정으로 인해 테스트 코드를 실행하지 않은 상태에서 PR이 승인되어 dev에 Merge될 수 있음
개발 환경 차이로 인한 오류	의존성 버전 차이 등으로 개발자의 로컬 PC에서는 잘 돌아가는데 배포 서버에서는 에러가 발생하는 환경 불일치 문제 발생
Docker Image 수동 Build 실수	담당자가 로컬에서 이미지를 수동 빌드/푸시할 경우 태그 오타, 필수 설정 누락 등으로 잘못된 버전이 생성될 위험
컨테이너 이미지 취약점 발생	담당자가 이미지를 빌드 시에 비밀값이 포함되는 등 이미지로 인해 취약점이 발생할 수 있음

---

단순히 배포 스크립트를 줄이는 것이 아니라, 누가 코드를 작성하든 일관된 검증을 거쳐 항상 배포 가능한 상태를 유지하기 위해 CI(지속적 통합) 파이프라인이 필요하다.

• Merge 후 빌드 실패, 코드 오류 문제를 해결하기 위해, PR 요청 시 개발자가 직접 빌드하고 테스트할 수 있다. 이는 human error 가능성을 가진다.
• 테스트를 통과해야만 Dev 브랜치에 Merge되며, 테스트를 통과하지 못한 코드는 Dev 브랜치로 Merge되지 않도록 진입을 차단하여, Dev 브랜치를 항상 로컬에서 검증 가능하며 배포 가능한 상태로 유지한다.
  • 운영 배포 가능 여부는 이후 전체 테스트를 거치는 main 승격 시점에 확정된다.
• 브랜치 등을 병합할 때 틈틈이 지속적으로 검증하여 원활한 협업을 위한 하나의 수단이 되기도 한다.

• 개발 환경 차이로 인한 오류를 해결하기 위해, 개발자의 로컬 머신 설정에 의존하지 않고, 운영 환경과 동일한 환경을 제공하는 표준화된 CI 러너 환경이 필요하다.

• Docker Image 수동 빌드 실수를 방지하기 위해 빌드 스크립트를 문서화하고 체크리스트를 만들어 해결할 수 있으나 이 방법도 human error를 원천 차단할 수는 없다.
• 따라서 코드 검증에 성공한 커밋에 대해서만 자동으로 Docker 이미지를 빌드하고 레지스트리에 푸시하는 일관된 파이프라인 흐름이 필요하다.

CI 설계 시 기준

1. 개발 시에 CI 가용성이 필요함: 개발의 흐름을 방해하지 않아야 함
2. 추가 비용이 크지 않아야 함

CI 환경은 아래 세 가지로 나뉜다.

1. 로컬 PC 컨테이너
   • 컴퓨터가 재부팅되거나 와이파이가 끊기면 다른 팀원들의 PR 빌드와 테스트가 멈춤
2. 클라우드 자체 호스팅
   • CI 서버 가용성 유지는 가능하나, EC2 인스턴스를 사용해 비용이 발생
3. 클라우드 기반 CI
   • 서버 관리가 필요없으며 가용성이 유지되며, 트리거가 발동되었을 때에만 작동함
   • 코드베이스를 서비스하는 곳과 같은 CI 서비스를 사용하면 연동성이 좋음
   • 사용량에 따른 비용이 청구되지만, 현재 팀 상황에서는 무료 한도 내에서 CI 작업을 할 수 있다고 판단됨

가용성 유지와 비용을 줄이는 기준에 의해, 클라우드 기반 CI서비스를 사용한다.

대표적인 클라우드 기반 CI로는 크게 세 가지로 나뉜다.

• 클라우드 플랫폼: AWS CodeBuild, Google Cloud Build, Azure Pipelines
• SaaS: Circle CI, Travis CI
• 소스코드 저장소 일체형: Github Actions, GitLab CI/CD, BitBucket Pipelines

---

1. 세가지 모두 가용성은 충족한다.
2. 월간 예상 CI/CD 시간을 고려한 비용면에서는 CircleCI, Google Cloud Build, Github Actions 모두 동일하게 무료로 사용할 수 있다.
3. 세가지 모두 비용면에서도 동일하기 때문에, 큰 차이가 나지 않았다. 이때, 운영의 편의성 부분을 고려해 Github 레포지토리를 사용할 때 별도 인증이 필요하지 않은 Github Actions를 사용한다.
   • CircleCI, Google Cloud Build 모두 Github와 연동성이 나쁘지 않다. 그러나 Github 생태계를 통해서 별도로 설정할 것 없이 서로 즉시 연동되는 점을 선택의 근거로 삼았다.

월간 예상 CI/CD 시간 (클릭하여 펼치기)

작업	작업 내용	시간	일일 빈도	예상 시간(20일)
프론트엔드 CI	정적 분석, 정적 파일 빌드	2분	일 5회	200분
백엔드 CI	정적 분석, 컴파일, 단위 테스트	3분	일 5회	300분
AI 서버 CI	정적 분석, API 단위 검증	3분	일 5회	300분
Docker Image 빌드	빌드 산출물 기반 Docker Image 빌드 및 Push	3분	일 5회	300분
CD	EC2 접속, docker compose pull & up, 헬스체크	4분	일 5회	400분
		총합		1500분

클라우드 기반 CI 서비스 비용표 (클릭하여 펼치기)

서비스	월간 무료 제공량	분당 요금
AWS CodeBuild	월 100분	$0.005 / 분
Google Cloud Build	월 2500분	$0.006 / 분
Azure Pipelines	월 1800분	$0.008 / 분
CircleCI	월 30,000 크레딧(최대 6000분)	$0.003 / 분(최소)
Travis CI	없음	월 $15, 700분
Github Actions	Private 2000분(Public 무료)	$0.008 / 분
GitLab CI/CD	월 400분	$0.01/분
BitBucket Pipelines	월 50분	$0.01/분

레포지토리 전략: 멀티 레포(프론트, 백, AI)

• 브랜치 종류: main, dev, feat, hotfix
• main: 당장 운영 환경에 배포해도 문제가 없는, 검증된 상태. 배포 시점에만 갱신
• dev: feat에서 merge된 변경이 계속 쌓이는 통합 브랜치. 배포 주기와 무관하게 실시간 갱신
• feat: 기능 개발 브랜치
• hotfix: 운영 중(main) 버전의 긴급 버그 수정 전용 브랜치. main에서 분기

브랜치와 태그

• feat -> dev PR: 정적 분석, 단위 테스트, 빌드, docker image build
• dev push(merge): 통합 이미지 빌드/push (태그: latest, dev-<short SHA>) -> 로컬/개인 EC2에서 latest pull 받아 docker-compose로 동작 검증
• dev -> main (정기 배포): 전체 테스트 후 merge. 단, PR merge만으로는 이미지가 빌드되지 않으며, merge 후 release 태그(v*..)를 push해야 Semantic Version 태그로 이미지 빌드/push/배포가 트리거된다.
• hotfix -> main (수시, 긴급 배포): 절대 실패 불가 기능(채팅하기, 교환 제안) 영향 버그 대상. merge 후 patch 버전(e.g. v1.0.1) release 태그를 push해 즉시 배포하고, dev에도 반영
• 지연 허용 기능(목록/상세조회, AI 기능 등) 버그는 hotfix가 아닌 다음 정기 배포(dev -> main)에 포함
• release 태그는 GitHub Release 생성(Target: main, 새 태그 v1.0.1 형식 입력 후 Publish)으로 push한다. main으로 병합하는 시점과 배포용 이미지를 만드는 시점을 의도적으로 분리하기 위함이다.

Trigger	실행 항목	비고
feat -> dev PR	정적 분석, 단위 테스트, 빌드, docker image build	검증용, docker image push 없음
dev push(merge)	docker image build, push	태그: latest, dev-<short SHA>
dev -> main PR	전체 테스트	정기 배포 전, 검증용
hotfix -> main PR	정적 분석, 단위 테스트, 빌드, docker image build	긴급 버그 수정, 검증용, push 없음
release 태그(v*.*.*) push	docker image build, push	main push(merge)가 아닌 release 태그 push가 트리거. 태그: Semantic Version만 사용 메타데이터: 이미지 라벨에 빌드 타임스탬프, 커밋 작성자, Git SHA를 OCI(Open Container Initiative) 표준으로 주입

• PR 단계에서는 merge가 거절되어 코드가 수정될 수 있으므로 Docker Image를 build만 하고 push하지 않는다.
  • PR 단계에서 Docker Image를 build하는 이유는, PR 단계에서 build 실패를 확인하지 못하고 dev나 main에 merge되면 dev, main 브랜치가 배포 가능하지 않은 상태가 되어, 배포 가능한 상태와 그렇지 않은 상태를 따로 구분해야 하기 때문이다.
• dev 브랜치를 Docker Image로 빌드하고 push하는 이유는, main 브랜치에는 운영 중인 코드가 존재하므로, 정기 배포 이전까지 변경 사항을 가지고 검증하기 위함이다.

• Concurrency 제어
  • 동일 브랜치/PR에 연속 Push 발생 시 진행 중이던 이전 실행 자동 취소 => GitHub Actions 큐 낭비 방지
• 브랜치 보호
  • main, dev 브랜치에 Direct Push 차단
  • 반드시 PR을 거쳐야 하며, 지정된 CI 워크플로우가 성공해야 Merge 버튼 활성화

정기 배포 주기(매주 월요일 오전 10시)와 시스템 유지보수 지원

• 정기 릴리즈 빌드 검증
  • 매주 월요일 오전 8시 실행
  • 오전 10시 정기 배포 전 최종 병합된 main 브랜치의 최신 상태에 대해 E2E 테스트 및 배포 대상 이미지 태그 확정
• 보안 취약점 주기적 스캔
  • 매주 일요일 오전 3시 실행
  • 새로운 CVE 발생 여부 확인을 위해 베이스 이미지 및 종속성 라이브러리를 주기적으로 재검사 => 외부 라이브러리의 신규 취약점이나 의존성 소프트웨어 노후화 탐지
    • 업데이트가 자주 없는 프로젝트면 필요하지만 우리 프로젝트는 최소 3일 1회 CI 시스템이 동작할 것이고 주 1회 업데이트가 있어 필수적이지 않다.

이미지 크기 다이어트

• Multi-stage build로 빌드 도구를 최종 런타임 이미지에서 제외
• 경량 베이스 이미지 채택(alpine, slim)

[!NOTICE] GitHub Actions의 private 레포는 GitHub-hosted 러너에 월별 2,000분과 스토리지는 무료다. => 불필요한 작업을 최소화하여 시간과 리소스를 절약해야 한다.

1. 코드 품질 검증

• Spring Boot
  • SpotBugs: NPE, 자원 미반환 등 잠재적 버그 탐지
  • PMD: 미사용 변수, 복잡도 높은 코드 탐지
  • Checkstyle과 같은 코드 스타일 탐지는 BE 인원이 1명이라 개인 IDE 검사로 충분할 것으로 예상
• FastAPI
  • Ruff: Linting, Formatting, import 정리 => 타 도구보다 10배 이상 빠르며(1초 미만) 레퍼런스가 많다.
• React
  • ESLint: 선언되지 않은 변수 사용, 잘못된 React Hooks 규칙 준수 등 버그로 이어지는 오류 탐지
  • Prettier, Biome와 같은 코드 스타일 탐지는 FE 인원이 1명이라 개인 IDE 검사로 충분할 것으로 예상
• 레포 루트에 .editorconfig 파일을 정의하여 일관된 규칙으로 Formatting => OS 차이로 인해 줄바꿈이나 들여쓰기 불일치 방지

2. 빌드 및 격리 테스트

• 종속성 캐싱 활용(Gradle, pip, npm/pnpm 캐시)
• 외부 의존성(DB) 없이 통과 가능한 단위 테스트 위주 실행 => DB 연동 테스트 필요 시 Testcontainers 또는 경량 H2/인메모리 DB로 격리하여 실행 속도 보장 => Testcontainers 사용 시 리소스 낭비로 이어질 수 있어 필수적인지 고민해야 한다.

3. 컨테이너 패키징

• GitHub Hosted 러너에서 ARM64 타겟 이미지 생성 효율성을 위해 ARM64 전용 러너 라벨 지정
• Dockerfile에서 소스 코드 복사 전에 패키지 정의 파일을 우선 복사 및 의존성 설치 명령어 배치(의존성 레이어 분리) => 소스 코드가 수정되어도 레이어 캐시 유지 => v1에서 실제로 적용됨
• BuildKit cache mount는 v1 범위에서 제외 => v1 규모(적은 CI 실행 빈도)에서는 빌드 속도가 아직 문제가 아니라고 판단해, 이미지 크기 축소와 의존성 레이어 분리만 v1 최적화 대상으로 좁힘

4. 보안 검증 게이트

• 빌드된 컨테이너 이미지를 대상으로 Trivy 또는 Grype로 OS 패키지 및 라이브러리 취약점 검사 => Trivy(약 815초, 캐시 활용 1.2초)와 Grype(약 920초, 캐시 활용 0.7초)는 검증 시간에 차이가 30% 정도 있지만 이미지 크기가 150MB 정도로 예상되는 현재 상황에서는 큰 차이가 없다. => 초기 구현 단계이기 때문에 패키지 취약점만 집중 탐색하는 Grype 대신 Trivy로 설정, Secrets, IaC 파일 등을 포함하여 종합적으로 검사한다.
• CRITICAL 등급 취약점 발견 시 빌드 실패 처리 => 유저가 제한적이기 때문에 즉각적인 조치가 필요한 수준이 아니면 다음 버전에 반영

5. 산출물 저장

• 모든 검증이 완료된 이미지에 태그를 부여하고 레지스트리에 Push

• 3개의 Private 컨테이너 레지스트리 환경에서 GHCR만 무료로 사용할 수 있다.
• CI/CD 단계에서 Docker hub와 ECR, Google Artifact Registry는 각각 시크릿 관리가 필요하지만, GHCR는 github에서 제공하는 인증 토큰을 사용할 수 있어 편리하다.(${{ secrets.GITHUB_TOKEN }})

따라서 비용적으로 우수하고 팀이 사용하는 github 생태계(github repo, github actions) 내에서 편의성이 높은 GHCR를 컨테이너 레지스트리로 사용한다.

비교 항목	AWS ECR	GitHub Packages (GHCR)	Docker Hub Pro	Google Artifact Registry
기본 스토리지 요금	$0.10 / GB / 월 (신규 1년 500MB 무료)	현재 무료(currently free) $0.25 / GB / 월 (Free 500MB, Team 2GB 무료)	월 $15 고정 (무제한 Private Repo) 1개 free	$0.10 / GiB / 월 (계정당 0.5GiB 무료)

컨테이너 이미지 레포지토리 정책

• 각 코드 저장소(프론트, 백, AI)에 대해 각각의 컨테이너 이미지 레포지토리를 생성해 관리한다.

• latest를 사용하는 이유는 로컬 테스트 시 편의를 위한 포인터로 사용하기 위함이다.
• dev의 commit SHA를 사용하는 이유는 원본 커밋을 참조하는 불변값을 태그로 달아 추적하기 위함이다.
• main은 dev나 hotfix에서만 병합되므로, main에 push되는 커밋은 항상 배포 가능한 버전이다. 그래서 매번 Semantic Version 태그를 부여하며, commit SHA는 태그 대신 아래 메타데이터에 기록해 추적한다.
• 이미지 빌드 트리거는 main push(merge)가 아닌 release 태그(v*.*.*) push다. 버전을 코드 파일(package.json류)로 관리하면 매 배포마다 그 파일을 고치는 PR이 별도로 필요하지만, Git tag를 단일 진실 공급원으로 삼으면 그 절차가 사라진다.
• 태그는 dev/hotfix -> main PR을 merge한 뒤 GitHub Release를 생성(Target: main, 태그 v1.0.1 형식)해 push한다. main으로 merge만 해서는 이미지가 만들어지지 않는다.

[!NOTICE] Semantic Version: MAJOR.MINOR.PATCH 예시: 1.0.1

• MAJOR: 기존 API와 호환되지 않는 변경
• MINOR: 기존 API와 호환되면서 새로운 기능이 추가된 경우
• PATCH: API/기능 변화 없는 사소한 수정 (버그 수정, 성능 개선 등)

메타데이터

• 메타데이터: 이미지 라벨에 빌드 타임스탬프, 커밋 작성자, Git SHA를 OCI(Open Container Initiative) 표준으로 주입 => 운영 환경에서 장애 발생 시 Git 로그 추적 용이 => OCI 표준 사용 시 보안 스캐닝, CI/CD 도구들이 별도 추가 설정이나 손실 없이 일관되게 분석 가능

main 배포시 Semantic Version 책정 규칙

• Semantic Version은 배포마다 MAJOR, MINOR, PATCH를 통틀어서 숫자 하나만을 올린다. (e.g. 1.0.0 -> 1.0.1)
• hotfix -> main (긴급 배포): 항상 PATCH
• dev -> main (정기 배포): 그 주 dev에 쌓인 변경 중 가장 영향도 높은 등급으로 결정 (MAJOR > MINOR > PATCH 우선)

• 롤백을 위한 최신 5개(운영 버전을 포함) - release 태그 push(배포)마다 FIFO로 교체
  • 일주일에 release 태그 push로 생성되는 이미지의 수는 3회(평일 2, 주말 1) 정도 예상된다.
• 테스트용 dev 이미지 최신 2개 - dev push마다 FIFO로 교체, latest는 그중 최신 것을 가리킨다.

• PR시 CI: 정적 분석, 단위/전체 테스트, 빌드, Docker Image 빌드
• PR 단계 CI가 실패하는 경우, 배포 가능한 코드만 통합해야 하므로 merge를 막음
• 따로 알림은 발송하지 않고 PR 작성자가 확인

• dev push 이후 CI: Docker Image 빌드, Docker Image push
• dev push가 실패하는 경우, 운영에는 영향이 없으나 PR 단계에서 Docker Image 빌드를 통과했으므로, 1회 재시도 하며 실패 시 워크플로우 중단
• 이후 인프라 담당자(tobby/janna)가 대응한다.

• release 태그(v*.*.*) push 이후 CI: 전체 테스트, Docker Image 빌드, Docker Image push
• release 태그 push 단계가 실패하는 경우, 팀 디스코드에 Webhook으로 CI 실패 알림을 보낸다.
• 알림을 확인한 인프라 담당자(tobby/janna)가 대응한다.

release 태그 push 실패 대응 정책

• release 태그 push가 실패해도 실제 이미지 registry에 push되지 않으므로 운영 서버에는 문제가 없다.(롤백 필요 없음)
• 실패 알림을 받은 인프라 담당자는 로그 확인 후 원인을 파악하여 해결한 뒤, 필요하면 태그를 다시 push하거나 워크플로우를 재실행한다.