CI - 100-hours-a-week/21-iceT-wiki GitHub Wiki

1. 개요

Koco는 개발 및 배포 과정에서 발생할 수 있는 휴먼 에러, 속도 저하, 협업 비효율성 문제를 해결하고자 CI(지속적 통합) 파이프라인을 구축했습니다.

이 문서는 CI를 도입한 배경, 도구 선택 이유, 구성 방식, 실사용 방법까지 정리합니다.

파이프라인 흐름도

---

2. 도입 배경

(1) 휴먼 에러 감소

• 수작업 실수로 인한 서비스 장애 위험 존재
• 자동화된 테스트 및 빌드를 슬랙 알림을 통해 휴먼 에러를 직접 확인 할 수 있도록 함

(2) 속도 개선

• 기존: (프론트, 백엔드, ai) 로컬 빌드 → 테스트 → 배포 준비까지 약 10분 이상 소요
• CI 도입 이후: 테스트 및 빌드 5~10분 이내 완료
• 평균 작업 시간 50% 감소, 개발 생산성 향상

(3) 반복 작업 자동화

• 기존: Git Clone 이후 수동 빌드 및 테스트 반복
• CI 적용 이후: 코드 Push만으로 자동 빌드 및 테스트 수행

(4) 안전성 및 효율성 확보

• 기존: Git Clone 기반 수작업 배포로 보안 및 운영 위험 존재
• CI 도입 이후: 서버 접근 없이 코드 기반 검증, 보안성 및 효율성 향상

(5) 협업 향상

• PR 생성 시 일관된 테스트 및 품질 검증 자동화

따라서, 이러한 문제들을 해결하고자 저희는 CI(지속적 통합)를 도입하였습니다.

자동화로 CI가 하게되는 일

단계	설명
코드 통합	여러 개발자가 작성한 코드를 하나의 브랜치에 자주 병합
자동 빌드	코드가 병합되면 자동으로 빌드(컴파일 등)를 수행
자동 테스트	빌드가 완료되면 테스트 코드(Unit Test, Lint 등)를 자동으로 수행
피드백 제공	빌드/테스트 결과를 개발자에게 즉시 알림(GitHub Checks, Slack 등)

---

3. CI 도구 선택

(1) GitHub Actions를 선택한 이유

• GitHub 저장소 연동 최적화: .github/workflows/*.yml 설정만으로 바로 사용 가능
• 가볍고 빠른 초기 설정: Jenkins처럼 별도 서버 필요 없음
• 비용 효율: Public 저장소 무료, Private 저장소도 월 2,000분 무료
• 500mb / 2000분(월) 무료 사용량 기준으로 5분의 ci 속도를 가정. 하루에 10회씩 커밋 테스트를 실행해도 여유로우므로, 초기 프로젝트 진행 중 크레딧이 모자라지 않을 것으로 추산.
• 풍부한 생태계와 문서: 다양한 예제와 템플릿 제공

(2) 다른 CI 도구를 사용하지 않은 이유

도구	장점	단점	부적합 이유
Jenkins	오픈소스, 유연성	설치·운영 부담 큼	단일 EC2에 Jenkins는 과함
Travis CI	GitHub 연동 쉬움	느린 속도, 요금제 제약	무료 플랜 운영 불가
CircleCI	빠른 빌드	복잡한 YAML 구조	과복잡
GitLab CI	GitLab 통합	GitHub 연동 불편	부적합
Bitbucket Pipelines	Bitbucket 최적화	기능 제한	GitHub 사용 중

CI/CD 도구 예시: Jenkins와 GitHub Actions 비교

---

4. 파이프라인 구성

(1) 브랜치 운영 흐름

브랜치	목적	특징
feature/*	기능 개발	Lint/Unit Test 자동 수행, 빠른 기능 완성
develop	통합 테스트	여러 feature 병합 후 통합 테스트 수행
main	운영 배포	최종 빌드 수행, 품질 검증 완료 코드만 병합
hotfix/*	긴급 수정	운영 중 버그 수정 및 병합 후 재반영

(2) CI 파이프라인 흐름

단계	목적	설명	도구 및 언어
코드 통합 (Checkout)	최신 코드 자동 수신	GitHub에 Push 혹은 PR이 발생하면 CI가 해당 브랜치의 코드를 자동으로 가져옴	actions/checkout
의존성 설치 / 자동 빌드	실행 환경 준비 + 코드 빌드	package.json, pom.xml, requirements.txt에서 의존성 설치 후 빌드 수행 프론트: 번들링 백엔드: 컴파일 AI: 모델 로딩 및 테스트 환경 구성	Node: npm ci, Java: ./gradlew build, Python: pip install -r
정적 분석 (Lint)	코드 스타일 일관성 유지	문법 오류, 스타일 오류 등 자동 분석. 사전 룰을 통과하지 못하면 PR 거부	FE: Prettier BE: Checkstyle AI: flake8
단위 테스트 (Unit Test)	기능 단위 정확성 검증	함수, 클래스 등 최소 단위가 독립적으로 올바르게 작동하는지 자동 검증	FE: Jest BE: JUnit5 AI: pytest
통합 테스트 (Integration Test)	서비스 연동 확인	여러 컴포넌트가 실제처럼 통합되어 동작하는지 테스트	FE: Cypress BE: Spring 환경 AI: FastAPI
테스트 커버리지 측정	테스트 범위 확인	전체 코드 중 테스트가 적용된 비율 측정. 80% 이상 권장	coverage, pytest-cov, jacoco
결과 확인 및 알림	실시간 피드백 제공	Slack으로 알림 전송. 실패 시 빠른 대응 가능	Slack Webhook

(3) 프론트엔드 .github/workflows/frontend-deploy-s3.yml 에서의 ci 주요 구조

name: Deploy Frontend React s3 static hosting

on:
  workflow_dispatch:  

jobs:
  build-deploy-frontend:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20.19.1'

      - name: Install dependencies
        run: npm ci

      - name: Generate .env file for Vite (based on branch)
        run: |
          echo "[FRONTEND] Generating .env file for branch: ${{ github.ref_name }}"
          
          if [ "${{ github.ref_name }}" = "main" ]; then
            echo "VITE_API_BASE_URL=https://ktbkoco.com/" >> .env
            echo "VITE_REDIRECT_URL=https://ktbkoco.com/oauth/kakao/callback" >> .env
            echo "VITE_KAKAO_CLIENT_ID=${{ secrets.KAKAO_CLIENT_ID }}" >> .env
          else
            echo "VITE_API_BASE_URL=https://koco.click/" >> .env
            echo "VITE_REDIRECT_URL=https://koco.click/oauth/kakao/callback" >> .env
            echo "VITE_KAKAO_CLIENT_ID=${{ secrets.KAKAO_CLIENT_ID }}" >> .env
          fi

      - name: Build React App
        run: npm run build

---

(4) 백엔드 .github/workflows/deploy.yml 에서의 ci 주요 구조

name: Deploy Spring Boot App

on:

  workflow_dispatch:
    inputs:
      image_tag:
        description: 'ECR 이미지 태그 (예: v1.0.0)'
        required: true

env:
  AWS_REGION: ap-northeast-2
  ECR_HOST: ${{ secrets.ECR_HOST }}
  IMAGE_TAG: ${{ github.event.inputs.image_tag }}
  DEPLOY_ZIP_KEY: spring-app-deploy.zip

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      # ───────────────────────────────────────────────────────────────
      # 1) Set dynamic S3 bucket and ECR repo name based on branch
      # ───────────────────────────────────────────────────────────────
      - name: Configure environment for branch
        run: |
          BRANCH=${GITHUB_REF#refs/heads/}
          if [ "$BRANCH" = "dev" ]; then
            echo "S3_BUCKET=dev-koco-codedeploy-artifacts" >> $GITHUB_ENV
            echo "ECR_REPO_NAME=dev-app-repo"               >> $GITHUB_ENV
            echo "SSM_PATH=/spring/dev/"                    >> $GITHUB_ENV
            echo "CD_APP_NAME=dev-was-deploy-app"           >> $GITHUB_ENV
            echo "CD_DG_NAME=dev-was-deploy-group"          >> $GITHUB_ENV
          else
            echo "S3_BUCKET=prod-koco-codedeploy-artifacts" >> $GITHUB_ENV
            echo "ECR_REPO_NAME=prod-app-repo"              >> $GITHUB_ENV
            echo "SSM_PATH=/spring/prod/"                   >> $GITHUB_ENV
            echo "CD_APP_NAME=prod-was-deploy-app"          >> $GITHUB_ENV
            echo "CD_DG_NAME=prod-was-deploy-group"         >> $GITHUB_ENV
          fi

      # ───────────────────────────────────────────────────────────────
      # 2) If manual dispatch, check for existing tag
      # ───────────────────────────────────────────────────────────────
      - name: Check if tag already exists in ECR
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          FULL_REPO="$ECR_HOST/$ECR_REPO_NAME"
          echo "🔍 Checking if tag '$IMAGE_TAG' exists at $FULL_REPO..."
          RESULT=$(aws ecr describe-images \
            --registry-id ${ECR_HOST%%.*} \
            --repository-name $ECR_REPO_NAME \
            --image-ids imageTag=$IMAGE_TAG \
            --region $AWS_REGION 2>/dev/null || true)
          if echo "$RESULT" | grep -q imageDigest; then
            echo "❌ ERROR: Tag '$IMAGE_TAG' already exists in $FULL_REPO."
            exit 1
          fi

      # ───────────────────────────────────────────────────────────────
      # 3) Build & Push Docker image for both dev and main
      # ───────────────────────────────────────────────────────────────
      - name: Build and Push Docker image to ECR
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          FULL_REPO="$ECR_HOST/$ECR_REPO_NAME"
          echo "🔐 Logging in to Amazon ECR at $FULL_REPO..."
          aws ecr get-login-password --region $AWS_REGION \
            | docker login --username AWS --password-stdin $ECR_HOST

          echo "🔧 Building Docker image..."
          docker build -t my-spring-app .

          echo "🏷 Tagging image with version: $IMAGE_TAG"
          docker tag my-spring-app:latest $FULL_REPO:$IMAGE_TAG

          echo "🏷 Tagging image as latest"
          docker tag my-spring-app:latest $FULL_REPO:latest

          echo "📤 Pushing image $FULL_REPO:$IMAGE_TAG"
          docker push $FULL_REPO:$IMAGE_TAG

          echo "📤 Pushing image $FULL_REPO:latest"
          docker push $FULL_REPO:latest

---

5. 테스트 커버리지 목표

• 커버리지 기준: 80% 이상 권장
• 사용 도구 예시:
  • Frontend: Jest + coverage
  • Backend: Jacoco
  • AI: pytest-cov
• Slack 메시지나 PR 코멘트에 커버리지 요약 포함

---

6. 빌드 성공 조건

항목	조건
린트	모든 서비스에서 통과
테스트	모든 서비스에서 실패 없이 통과
커버리지	선택적 기준 만족 (권장 80% 이상)
슬랙 알림	성공/실패 여부 무관하게 항상 전송
종료	실패 시 단계 중단 및 상태코드 반환