GitHub Actions CI/CD 구축 완벽 가이드: React 앱 AWS S3 + CloudFront 자동 배포

GitHub Actions CI/CD 구축 완벽 가이드: React 앱 AWS S3 + CloudFront 자동 배포

"팀장님, 제가 수동으로 빌드해서 올리다가 실수로 옛날 코드를 덮어씌웠습니다..."

안녕하세요! 항상 더 효율적으로 일할 궁리를 하는 아이디어 뱅크, 프론트엔드 개발자입니다.

처음 현업 프로젝트를 맡았을 때의 기억이 납니다. 기능 개발을 마치면 로컬에서 npm run build를 실행하고, AWS S3 콘솔에 로그인한 뒤, 기존 파일을 삭제하고 새 빌드 파일을 드래그 앤 드롭으로 올리는 일련의 과정을 하루에도 서너 번씩 반복했습니다. 그러다 한 번은 파일을 덜 올리거나 실수로 CloudFront 캐시 무효화를 빼먹어서 서비스 화면이 깨지는 대형 사고를 치기도 했죠.

이런 단순하고 반복적인, 그리고 사람의 실수가 개입하기 쉬운 배포 과정을 100% 자동화해 주는 마법 같은 기술이 바로 CI/CD(지속적 통합/지속적 배포)입니다. 오늘은 주니어 개발자도 쉽게 따라 할 수 있도록 GitHub Actions를 활용해 React 앱을 AWS S3와 CloudFront에 자동으로 배포하는 파이프라인 구축법을 하나부터 열까지 알기 쉽게 설명해 드리겠습니다.

1. CI/CD와 GitHub Actions: 직관적인 비유로 이해하기

'파이프라인', '워크플로우', 'CI/CD' 같은 낯선 기술 용어들이 나오면 지레 겁먹기 쉽습니다. 이를 우리가 익히 아는 '전자동 로봇 공장'에 비유해 보겠습니다.

• 수동 배포 (과거의 나):
• 수제 버거집 사장님입니다. 재료를 썰고(코딩), 패티를 굽고(빌드), 포장해서(압축), 직접 오토바이를 타고 손님 집(AWS S3)까지 배달합니다. 손님이 많아지면 실수가 잦아지고 사장님은 쓰러집니다.
• CI/CD 파이프라인 (GitHub Actions):
• 최첨단 로봇 컨베이어 벨트입니다. 개발자는 레시피(코드)만 작성해서 main 브랜치라는 상자에 툭 던져 넣기만 하면 됩니다(git push). 그러면 대기하고 있던 로봇(GitHub Actions)이 알아서 코드를 검사하고, 빌드하고, 포장해서 AWS 서버까지 0.1초 만에 로켓 배송을 완료합니다.

📊 수동 배포 vs GitHub Actions 자동 배포 비교

비교 항목	기존 수동 배포 방식	GitHub Actions 자동 배포 (CI/CD)
소요 시간	개발자가 직접 5~10분간 화면을 보며 대기해야 함	git push 한 번이면 백그라운드에서 자동 실행 (0분 소요)
안정성 (휴먼 에러)	빌드 명령어 누락, 폴더 업로드 실수 등 위험 존재	사전에 작성된 스크립트(YAML)대로만 100% 동일하게 동작
비용 및 접근성	별도 인프라 지식이 필요	GitHub에서 무료로 제공하며 설정이 매우 간편함
협업 효율	한 사람이 배포 권한을 독점하여 병목 현상 발생	팀원 누구나 브랜치에 병합(Merge)만 하면 자동으로 배포됨

2. CI/CD 파이프라인 구축 1단계: AWS 보안 설정 (가장 중요!)

로봇(GitHub Actions)이 내 AWS 창고(S3)에 물건을 넣으려면 창고 열쇠가 필요합니다. 보안상 내 마스터 계정을 주면 안 되고, "오직 S3 업로드와 CloudFront 갱신만 할 수 있는 알바생용 열쇠(IAM)"를 따로 만들어주어야 합니다.

1. AWS 콘솔에서 IAM (Identity and Access Management) 서비스로 이동합니다.
2. 새로운 사용자(User)를 생성하고 이름을 github-actions-deploy-user 등으로 짓습니다.
3. 권한 설정에서 다음 두 가지 정책(Policy)을 연결합니다.
   • AmazonS3FullAccess (또는 해당 버킷에만 접근하는 커스텀 권한)
   • CloudFrontFullAccess (캐시 무효화 처리를 위해 필요)
4. 사용자 생성 후 보안 자격 증명 탭에서 액세스 키(Access Key) 만들기를 클릭합니다.
5. 발급된 Access Key ID와 Secret Access Key를 복사해 둡니다. (이 창을 닫으면 다시 볼 수 없으니 주의하세요!)

3. CI/CD 파이프라인 구축 2단계: GitHub Secrets에 열쇠 숨기기

발급받은 AWS 열쇠를 소스 코드에 그대로 적어 올리면 전 세계 해커들의 먹잇감이 됩니다. 안전한 금고인 GitHub Secrets에 열쇠를 보관해야 합니다.

1. 배포할 React 프로젝트의 GitHub 레포지토리로 이동합니다.
2. Settings -> Secrets and variables -> Actions 메뉴를 클릭합니다.
3. New repository secret 버튼을 눌러 아까 메모해 둔 AWS 정보들을 등록합니다.
   • AWS_ACCESS_KEY_ID: 복사한 액세스 키 ID
   • AWS_SECRET_ACCESS_KEY: 복사한 시크릿 키
   • AWS_REGION: 서울 리전인 경우 ap-northeast-2

이렇게 금고에 넣어두면, 나중에 작성할 스크립트에서 ${{ secrets.AWS_ACCESS_KEY_ID }}라는 이름표로 안전하게 꺼내 쓸 수 있습니다.

4. 실전! GitHub Actions YAML 스크립트 작성하기

이제 로봇에게 지시할 작업 지시서(Workflow)를 작성할 차례입니다. React 프로젝트 최상단 경로에 .github/workflows/deploy.yml 파일을 만들고 아래 코드를 작성합니다. 주석을 꼼꼼히 읽어보세요!

YAML

 

# 워크플로우의 이름입니다. GitHub Actions 탭에서 이 이름으로 표시됩니다.
name: React App CI/CD to AWS S3 & CloudFront

# 어떤 이벤트가 발생했을 때 이 공장을 가동할지 결정합니다.
on:
  push:
    branches:
      - main # main 브랜치에 push나 merge가 일어날 때만 실행됩니다.

# 로봇이 수행할 작업(jobs) 목록입니다.
jobs:
  deploy:
    runs-on: ubuntu-latest # 최신 우분투 리눅스 환경의 가상 컴퓨터를 한 대 빌립니다.

    steps:
      # 1. 내 GitHub 저장소의 코드를 가상 컴퓨터로 가져옵니다. (Checkout)
      - name: 1. 저장소 코드 가져오기
        uses: actions/checkout@v3

      # 2. React를 빌드하기 위해 Node.js 환경을 세팅합니다.
      - name: 2. Node.js 환경 설정
        uses: actions/setup-node@v3
        with:
          node-version: '18' # 프로젝트에 맞는 노드 버전 사용

      # 3. 패키지(라이브러리)들을 설치합니다.
      - name: 3. 의존성 패키지 설치 (npm ci)
        run: npm ci # npm install보다 빠르고 정확하게 package-lock.json 기준으로 설치합니다.

      # 4. React 소스코드를 브라우저가 읽을 수 있는 정적 파일(HTML/CSS/JS)로 압축(빌드)합니다.
      - name: 4. 프로젝트 빌드하기
        run: npm run build

      # 5. AWS 열쇠(인증 정보)를 가상 컴퓨터에 세팅합니다.
      - name: 5. AWS 자격 증명 구성
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ secrets.AWS_REGION }}

      # 6. 빌드된 결과물(build 폴더)을 AWS S3 버킷으로 업로드(동기화)합니다.
      - name: 6. S3에 빌드 파일 업로드 (Sync)
        run: aws s3 sync ./build s3://my-react-bucket-name --delete
        # --delete 옵션: S3에는 있지만 새 빌드 폴더에는 없는 옛날 파일들을 알아서 삭제해 줍니다.

      # 7. CloudFront의 캐시를 싹 지워줍니다. (이걸 안 하면 사용자는 옛날 화면을 보게 됩니다!)
      - name: 7. CloudFront 캐시 무효화 (Invalidation)
        run: aws cloudfront create-invalidation --distribution-id E1A2B3C4D5E6F7 --paths "/*"
        # E1A2B3C4D5E6F7 부분은 본인의 CloudFront 배포 ID로 변경해야 합니다.

이 파일을 커밋하고 main 브랜치에 푸시(Push)하는 순간, GitHub 레포지토리의 Actions 탭에서 노란색 불이 들어오며 톱니바퀴가 신나게 돌아가는 짜릿한 광경을 목격할 수 있습니다!

5. 실무 경험에서 얻은 트러블슈팅 및 꿀팁 (E-E-A-T)

현업에서 CI/CD를 구성할 때 처음엔 무조건 한두 번의 실패를 겪게 됩니다. 제가 직접 겪었던 시행착오와 해결 팁을 공유합니다.

• 에러 사례 1: CloudFront 캐시 무효화(Invalidation)를 빼먹었을 때
• 초보 시절 S3 업로드까지만 스크립트를 작성하고 "배포 끝!"을 외쳤습니다. 그런데 기획자분이 "버튼 색깔이 그대로인데요?"라고 하시더군요. CloudFront는 한 번 가져간 S3 파일을 엣지 로케이션에 꽉 쥐고(캐싱) 놓아주지 않습니다. 워크플로우 7단계의 create-invalidation 명령어는 선택이 아닌 필수입니다. "/*" 경로를 지정해 모든 캐시를 강제로 비워줘야 새 코드가 즉각 반영됩니다.
• 팁: npm install 대신 npm ci를 사용하세요
• 워크플로우 스크립트를 보면 패키지 설치 시 npm install 대신 npm ci를 적어두었습니다. npm install은 실행할 때마다 패키지 버전을 미세하게 올릴 위험이 있지만, npm ci는 package-lock.json에 명시된 버전과 토씨 하나 틀리지 않고 똑같이 설치합니다. 빌드 서버와 로컬 개발 환경의 환경 불일치를 막아주는 아주 훌륭한 안전장치입니다.
• 보안 고도화 (시니어 레벨업 포인트): OIDC(OpenID Connect) 활용
• 위 가이드에서는 가장 직관적인 Access Key 발급 방식을 설명했습니다. 하지만 실무(엔터프라이즈 환경)에서는 Access Key가 유출될 위험 자체를 없애기 위해 OIDC라는 기술을 씁니다. 키를 발급받지 않고, AWS와 GitHub가 서로 "너희 공장에서 온 로봇이 맞구나" 하고 신뢰 관계를 맺어 임시 권한을 부여하는 방식입니다. 추후 레벨업을 원하신다면 'GitHub Actions AWS OIDC 연동' 키워드로 학습해 보시길 강력히 추천합니다.

이제 여러분은 git push 명령어 단 한 줄로 코드를 전 세계에 배포할 수 있는 CI/CD 파이프라인을 갖게 되었습니다. 수동 배포로 버려지던 시간과 에너지를 아껴, 더 나은 코드를 작성하는 데 집중하시길 응원합니다!