CI/CD 파이프라인
GitHub Actions로 CI/CD 파이프라인을 구축하는 실전 튜토리얼입니다. 자동화된 빌드, 테스트, 배포를 경험해보세요.
프로젝트 개요
이 튜토리얼에서는 GitHub Actions를 사용하여 CI/CD 파이프라인을 구축합니다. 코드를 푸시하면 자동으로 테스트가 실행되고, 통과하면 배포까지 진행됩니다.
CI(Continuous Integration)는 코드 변경 사항을 자주 통합하며 자동 빌드/테스트로 결함을 조기에 발견하는 방법론이고, CD(Continuous Deployment/Delivery)는 검증된 코드를 자동으로 프로덕션에 배포하는 과정입니다.
- 개발자가 코드 푸시
- GitHub Actions가 워크플로우 트리거
- 린트 및 코드 품질 검사 (CI)
- 단위 테스트 및 통합 테스트 실행 (CI)
- 빌드 아티팩트 생성 (CI)
- 스테이징 환경 배포 (CD)
- 프로덕션 환경 배포 (CD)
AI 도구를 활용하면 CI/CD 파이프라인 설정이 훨씬 쉬워집니다. 복잡한 YAML 문법을 외울 필요 없이 자연어로 원하는 파이프라인을 설명하면 AI가 워크플로우 파일을 생성해줍니다. 다만 생성된 설정을 이해하고 검증하는 능력은 반드시 갖추어야 합니다.
파이프라인 단계별 상세
각 단계를 이해하면 문제 발생 시 빠르게 원인을 파악하고 파이프라인을 최적화할 수 있습니다.
린트(Lint) 단계
린트는 코드 스타일과 잠재적 오류를 자동으로 검사하는 과정입니다. 파이프라인에서 가장 먼저 실행되며, 실행 시간이 짧아 빠른 피드백을 제공합니다. ESLint, Prettier 같은 도구가 대표적입니다.
- name: Lint code
run: |
npm run lint
npm run format:check
- name: Type check
run: npx tsc --noEmit
테스트(Test) 단계
테스트 단계에서는 단위 테스트(Unit Test), 통합 테스트(Integration Test), E2E 테스트를 실행합니다. 테스트 커버리지 리포트를 생성하여 코드 품질을 지속적으로 모니터링할 수 있습니다.
- name: Run unit tests
run: npm test -- --coverage
- name: Upload coverage report
uses: actions/upload-artifact@v4
with:
name: coverage-report
path: coverage/
- name: Run E2E tests
run: npx playwright test
env:
CI: true
테스트 실행 시간을 단축하려면 matrix 전략을 사용하여 여러 환경에서 병렬로 테스트를
실행하세요. Node.js 18, 20, 22 버전에서 동시에 테스트하면 호환성도 확인할 수 있습니다.
빌드(Build) 단계
소스 코드를 컴파일하고 배포 가능한 아티팩트를 생성합니다.
actions/upload-artifact로 빌드 결과물을 저장하면 후속 배포 단계에서 재사용할 수 있습니다.
- name: Build application
run: npm run build
env:
NODE_ENV: production
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: build-output
path: dist/
retention-days: 7
배포(Deploy) 단계
모든 검증 단계를 통과한 코드만 배포됩니다. 빌드된 아티팩트를 대상 환경에 전달하고, 배포 후 헬스 체크가 수행됩니다.
Step 1: GitHub 저장소 설정
먼저 GitHub 저장소를 만들고 로컬 프로젝트를 연결합니다.
# 로컬 프로젝트 폴더로 이동
cd my-project
# Git 초기화
git init
# 모든 파일 스테이징
git add .
# 첫 커밋
git commit -m "Initial commit"
# GitHub 저장소 생성 후 연결
git remote add origin https://github.com/사용자명/저장소명.git
git branch -M main
git push -u origin main
Step 2: CI/CD 워크플로우 요청
AI 도구에게 GitHub Actions 워크플로우 생성을 요청합니다.
GitHub Actions CI/CD 워크플로우를 만들어줘.
요구사항:
1. Node.js 프로젝트용
2. 풀 리퀘스트와 메인 브랜치 푸시 시 실행
3. npm install과 npm test 실행
4. 테스트 통과 시 Vercel이나 Netlify에 자동 배포
5. Node.js 버전은 20.x 사용
Step 3: 생성된 워크플로우 확인
AI 도구가 생성한 GitHub Actions 워크플로우 파일입니다:
name: CI/CD Pipeline
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
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
deploy:
needs: build-and-test
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Deploy to Netlify
uses: nwtgck/actions-netlify@v2.0
with:
publish-dir: './dist'
production-branch: main
github-token: ${{ secrets.GITHUB_TOKEN }}
netlify-auth-token: ${{ secrets.NETLIFY_AUTH_TOKEN }}
netlify-site-id: ${{ secrets.NETLIFY_SITE_ID }}
Netlify 배포를 위해서는 Netlify에서 인증 토큰과 사이트 ID를 생성하여 GitHub Secrets에 추가해야 합니다.
Step 4: GitHub Secrets 설정
보안 민감한 정보는 GitHub Secrets에 저장합니다.
설정 방법
- GitHub 저장소 페이지로 이동
- Settings 탭 클릭
- 왼쪽 메뉴에서 Secrets and variables → Actions 클릭
- New repository secret 버튼 클릭
- 이름과 값을 입력하여 저장
- NETLIFY_AUTH_TOKEN: Netlify에서 생성
- NETLIFY_SITE_ID: Netlify 사이트 설정에서 확인
시크릿 관리 모범 사례
시크릿(비밀 정보)은 CI/CD 파이프라인에서 가장 민감한 부분입니다. GitHub은 세 가지 범위의 시크릿을 지원합니다:
Repository Secrets(단일 저장소), Environment Secrets(특정 환경별),
Organization Secrets(조직 내 여러 저장소 공유). 워크플로우에서는 environment: production을
지정하면 해당 환경의 시크릿에만 접근할 수 있습니다.
- 시크릿 값을 로그에 출력하지 마세요. 인코딩된 형태로 노출될 수 있습니다.
- Fork된 저장소의 PR에서는 시크릿에 접근할 수 없습니다 (의도적 보안 설계).
- 시크릿을 정기적으로 교체(rotation)하고, 불필요한 시크릿은 즉시 삭제하세요.
GITHUB_TOKEN은 자동 생성되며 워크플로우 종료 시 만료됩니다.
Step 5: 파이프라인 실행 확인
코드를 푸시하고 GitHub Actions가 실행되는지 확인합니다.
# 코드 변경 후 커밋
git add .
git commit -m "Add CI/CD workflow"
# GitHub에 푸시
git push origin main
실행 결과 확인
- GitHub 저장소 페이지에서 Actions 탭 클릭
- 실행 중인 워크플로우 클릭
- 각 단계의 로그 확인
- 완료되면 녹색 체크 표시 확인
AI 통합 포인트
CI/CD 파이프라인에 AI를 통합하면 코드 품질을 자동으로 개선하고 리뷰 시간을 단축할 수 있습니다. 특히 PR 단계에서 AI 코드 리뷰와 AI 테스트 생성은 개발 생산성을 크게 향상시킵니다.
AI 코드 리뷰 자동화
PR이 생성되면 AI가 자동으로 코드를 분석하여 잠재적 버그, 보안 취약점, 성능 문제를 지적합니다.
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
permissions:
contents: read
pull-requests: write
jobs:
ai-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: AI Review with Claude
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff origin/main...HEAD > /tmp/diff.txt
# Claude API로 코드 리뷰 요청 후 PR 코멘트 작성
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{...}" > /tmp/review.json
AI 테스트 자동 생성
테스트 커버리지가 낮은 파일을 자동 감지하고 AI가 테스트 케이스를 제안합니다.
npm test -- --coverage로 커버리지 리포트를 생성한 뒤,
80% 미만인 파일 목록을 추출하여 AI API에 전달하면 됩니다.
AI API 호출은 비용이 발생합니다. 변경된 파일만 리뷰 대상으로 제한하고,
paths 필터로 특정 디렉토리 변경 시에만 실행하세요.
Draft PR에서는 실행하지 않도록 조건을 추가하면 비용을 절약할 수 있습니다.
환경별 배포 전략
실제 프로젝트에서는 코드를 곧바로 프로덕션에 배포하지 않습니다. 개발(dev), 스테이징(staging), 프로덕션(production) 환경을 단계적으로 거치며 각 환경에서 충분한 검증을 거친 후 다음 단계로 진행합니다.
환경 구성 개요
- Development: feature 브랜치 푸시 시 실행. 개발자 개별 테스트 용도.
- Staging: develop 브랜치 머지 시 실행. QA팀이 통합 검증 수행.
- Production: main 브랜치 머지 + 승인 후 실행. 실제 서비스 환경.
환경별 배포 워크플로우
핵심 구조는 ci(공통) → deploy-staging(develop 브랜치) → deploy-production(main 브랜치)입니다.
각 배포 job에 environment 키를 지정하면 해당 환경의 시크릿과 보호 규칙이 적용됩니다:
deploy-staging:
needs: ci
if: github.ref == 'refs/heads/develop'
environment: { name: staging, url: 'https://staging.example.com' }
steps:
- uses: actions/download-artifact@v4
with: { name: build-output, path: dist/ }
- run: npx netlify deploy --dir=dist --alias=staging
deploy-production:
needs: ci
if: github.ref == 'refs/heads/main'
environment: { name: production, url: 'https://example.com' }
steps:
- uses: actions/download-artifact@v4
with: { name: build-output, path: dist/ }
- run: npx netlify deploy --dir=dist --prod
GitHub의 Environment Protection Rules를 반드시 설정하세요. 프로덕션 환경에 Required reviewers(필수 승인자)와 Wait timer(대기 시간)를 설정하면 실수로 인한 즉시 배포를 방지할 수 있습니다. Settings > Environments에서 설정합니다.
모니터링 및 롤백 전략
배포가 완료된 후에도 파이프라인의 역할은 끝나지 않습니다. 서비스 상태를 지속적으로 모니터링하고, 문제 발생 시 신속하게 이전 버전으로 롤백할 수 있어야 합니다.
배포 후 헬스 체크
배포 직후 자동으로 서비스 상태를 확인하고, 실패 시 롤백합니다:
- name: Health check
run: |
sleep 30
for i in 1 2 3 4 5; do
STATUS=$(curl -so /dev/null -w "%{http_code}" ${{ vars.SITE_URL }}/health)
[ "$STATUS" = "200" ] && echo "OK" && exit 0
echo "Retry $i: $STATUS"; sleep 10
done
exit 1
- name: Rollback on failure
if: failure()
run: npx netlify rollback
롤백 전략 비교
- 즉시 롤백: 이전 배포 버전으로 되돌리기 (복구 1-2분, 심각한 장애 시)
- 핫픽스 배포: 문제를 수정하여 새 버전 배포 (복구 10-30분, 원인이 명확한 버그)
- 카나리 배포: 일부 트래픽만 새 버전으로 라우팅 (점진적, 위험도 높은 변경 시)
- Blue-Green 배포: 두 환경을 전환하여 배포 (즉시, 무중단 배포 필요 시)
슬랙 알림 통합
배포 성공/실패 시 팀 채널에 자동으로 알림을 보내면 빠른 대응이 가능합니다:
slackapi/slack-github-action 액션을 사용하면 간편합니다.
if: success()와 if: failure() 조건으로 성공/실패 시 다른 메시지를 보낼 수 있으며,
SLACK_WEBHOOK_URL을 시크릿에 등록하여 사용합니다.
모든 빌드마다 알림을 보내면 팀원들이 알림을 무시하게 됩니다. 실패 시에만 알림을 보내거나, 프로덕션 배포 같은 중요 이벤트에만 알림을 설정하세요.
고급 기능 추가
기본 파이프라인이 작동하면 추가 기능을 요청해봅니다.
기능 1: 코드 품질 검사
ESLint와 Prettier로 코드 품질 검사를
추가해줘. npm run lint와 npm run format
스크립트를 실행하고, 실패하면 빌드가
실패하도록 해줘.
기능 2: 보안 스캔
npm audit으로 보안 취약점 스캔을
추가해줘. 취약점이 발견되면 빌드가
실패하도록 해줘.
기능 3: 슬랙 알림
슬랙으로 빌드 결과를 알리도록
추가해줘. 성공과 실패 시 다른
메시지를 보내야 해.
CI/CD 파이프라인 흐름도
완성된 CI/CD 파이프라인의 흐름은 다음과 같습니다:
CI/CD 파이프라인 흐름
다음 단계
CI/CD 파이프라인을 구축하는 방법을 배웠습니다. 더 많은 자동화 기능을탐색해 보세요!
핵심 정리
- 워크플로우:
.github/workflows에 YAML로 파이프라인 정의 - 파이프라인 단계: 린트 → 테스트 → 빌드 → 배포 순서로 구성
- Secrets 관리: 보안 정보는 GitHub Secrets에 저장, 환경별 분리
- 환경별 배포: dev → staging → production 단계적 배포
- AI 통합: AI 코드 리뷰, AI 테스트 생성으로 품질 자동화
- 모니터링/롤백: 헬스 체크, 슬랙 알림, 자동 롤백으로 안정성 확보