GitHub Actions CI/CD 완벽 세팅 가이드 - 자동 빌드부터 배포까지

GitHub Actions CI/CD 완벽 세팅 가이드

요약: GitHub Actions를 사용해서 코드 푸시 시 자동으로 테스트, 빌드, 배포하는 파이프라인을 구축하는 방법을 알아봅니다.

---

1. 기본 워크플로우 구조

GitHub Actions는 .github/workflows 폴더에 YAML 파일로 정의합니다.

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run tests
      run: npm test
    
    - name: Build
      run: npm run build

2. 비밀 값 관리

API 키나 토큰은 GitHub Secrets에 저장하세요.

# Settings > Secrets and variables > Actions 에서 추가

# 워크플로우에서 사용
- name: Deploy
  env:
    API_KEY: ${{ secrets.API_KEY }}
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
  run: |
    echo "Deploying with token..."
    ./deploy.sh

3. 조건부 실행

특정 조건에서만 스텝을 실행할 수 있습니다.

# main 브랜치에서만 배포
- name: Deploy to Production
  if: github.ref == 'refs/heads/main'
  run: ./deploy-prod.sh

# PR에서만 실행
- name: Comment on PR
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: 'Build passed!'
      })

4. 캐싱으로 빌드 속도 향상

- name: Cache node modules
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

5. 매트릭스 빌드

여러 환경에서 동시에 테스트할 수 있습니다.

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
    
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node }}
    - run: npm test

자주 발생하는 에러

• Permission denied: checkout 후 실행 권한 부여 필요 - chmod +x script.sh
• Secret not found: Repository Settings에서 secret 이름 확인
• Rate limit: GitHub API 호출 제한 - 캐싱 활용

참고 자료

• GitHub Actions 공식 문서
• 공식 Actions 모음

---

작성: 밤비스