GitHub Actions로 Node.js CI/CD 파이프라인 구축

소개

CI/CD는 코드 변경을 자동으로 빌드·검증·배포하는 방식이다. 이 글에서는 GitHub Actions를 이용해 Node.js 애플리케이션의 CI/CD 파이프라인을 구성하는 전체 흐름을 설명한다. 초보자도 따라할 수 있도록 준비물, 워크플로 구조, 주요 설정과 실습 예제를 차근차근 다룬다.

사전 준비

필수 요소

• GitHub 저장소
• Node.js 프로젝트(package.json 포함)
• 배포 대상(예: VPS, Docker Registry, 클라우드 서비스)
• 필요한 시크릿 값(GITHUB_TOKEN, SSH 키 또는 클라우드 자격증명)

프로젝트 구조 예

간단한 구조는 다음과 같다.

.
├─ .github/workflows/ci.yml
├─ package.json
├─ src/
└─ test/

파이프라인 개요

파이프라인은 보통 다음 단계로 구성된다.

• 코드 체크아웃
• 의존성 설치
• 정적 분석 또는 린트
• 단위 테스트 실행
• 빌드 및 아티팩트 생성
• 배포(조건부 실행)

이 흐름을 GitHub Actions 워크플로로 구현하면 push나 PR 이벤트마다 자동으로 실행할 수 있다. 검색 노출을 위해 본문에 주요 키워드인 "GitHub Actions Node.js CI 설정", "Node.js 자동 배포 GitHub Actions", "CI/CD Node.js 예제 파이프라인"을 자연스럽게 포함해 설명한다.

워크플로 예제

아래 예제는 push와 PR에서 동작하며, main 브랜치에 머지될 때만 배포를 실행한다.

name: CI/CD

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

jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Run tests
        run: npm test

  deploy:
    needs: build-test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to server
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          rsync -avz --delete ./dist/ user@server:/var/www/myapp

배포 방법과 보안

배포에는 여러 방법이 있다. SSH를 이용해 서버에 복사하거나, Docker 이미지를 빌드해 레지스트리에 푸시한 뒤 클러스터에서 배포할 수 있다. 중요한 점은 자격증명 관리를 GitHub Secrets에 보관하는 것이다. 공개 저장소에서는 민감 정보를 절대 코드에 포함하지 않아야 한다.

시크릿 관리

• SSH 키: SSH_PRIVATE_KEY
• 클라우드 자격증명: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY 등
• 환경 변수로 민감 값 주입

테스트 통합과 조건부 배포

테스트가 실패하면 배포가 일어나지 않아야 한다. GitHub Actions에서는 job 간 의존성(needs)을 사용해 이를 보장한다. 또한 브랜치, 태그, 레이블 같은 조건을 추가해 배포를 제어할 수 있다.

실무 팁

• 캐시를 사용해 설치 속도를 개선(npm cache 또는 actions/cache)
• 빌드 아티팩트를 업로드하고 검증 단계 추가
• 롤백 전략을 사전 정의(버전 태깅, 레이블링)
• 모니터링과 알림 연결(슬랙, 이메일)

예제 배포 스크립트

간단한 서버 복사 방식 배포 예시. 이 스크립트는 워크플로의 deploy 단계에서 실행된다.

# deploy.sh
set -e
BUILD_DIR=dist
TARGET=user@server:/var/www/myapp
rsync -avz --delete "$BUILD_DIR/" "$TARGET"
ssh user@server 'cd /var/www/myapp && pm2 restart myapp || pm2 start ecosystem.config.js'

마무리

GitHub Actions를 활용하면 Node.js 프로젝트의 CI/CD 파이프라인을 효율적으로 자동화할 수 있다. 이 문서에서는 기본 구성, 워크플로 예제, 보안과 배포 방식을 다뤘다. 실제 환경에서는 테스트 커버리지와 배포 안전성을 우선으로 두고 점진적으로 워크플로를 확장하는 것이 좋다.