개발 초보자를 위한 GitHub Actions로 Node.js 프로젝트 자동 테스트·배포(CI/CD) 처음부터 설정하기

처음엔 “로컬에서 잘 되는데 서버에서만 왜 깨지지?”가 반복됩니다. 더 큰 문제는, 배포할 때마다 손으로 테스트하고 파일 올리다 보면 실수는 언젠가 반드시 난다는 것. 그래서 오늘은 Node.js 프로젝트에 GitHub Actions로 자동 테스트와 배포 흐름을 초보자 눈높이에서 한 번에 잡아보겠습니다. 한 번만 제대로 설정해두면, 이후엔 코드 푸시 → 테스트 → 배포가 자연스럽게 굴러갑니다.

준비물 체크리스트

• GitHub 저장소(Repository)
• Node.js 프로젝트(예: Express)
• package.json에 테스트 스크립트 존재(없으면 만들어도 됨)
• 배포 대상(예: 리눅스 서버, 또는 빌드 산출물 업로드)

예시 프로젝트 스크립트(최소 구성)

{
  "scripts": {
    "test": "node -e \"console.log('test ok')\"",
    "build": "node -e \"console.log('build ok')\""
  }
}

테스트가 아직 없다면 위처럼 임시로라도 시작해 두고, 나중에 Jest 같은 테스트 도구로 확장하면 됩니다.

GitHub Actions 기본 구조 이해하기

GitHub Actions는 저장소의 .github/workflows/ 폴더에 있는 YAML 파일을 읽어 자동 실행합니다.

• on: 언제 실행할지(푸시, PR 등)
• jobs: 어떤 작업을 할지
• steps: 작업을 이루는 단계들(체크아웃, 설치, 테스트 등)

1단계: 자동 테스트(CI) 워크플로 만들기

파일 생성: .github/workflows/ci.yml

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18, 20]

    steps:
      - name: 체크아웃
        uses: actions/checkout@v4

      - name: Node.js 설정
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"

      - name: 의존성 설치
        run: npm ci

      - name: 테스트 실행
        run: npm test

여기서 초보자가 자주 막히는 포인트

• npm install 대신 npm ci: 잠금 파일(package-lock.json) 기준으로 더 안정적으로 설치합니다.
• pull_request에도 실행: PR 단계에서 미리 깨지는 걸 잡아줍니다.
• Node 버전 2개 돌리기: “내 컴퓨터 버전에서만 되는” 상황을 줄여줍니다.

2단계: 자동 배포(CD)까지 연결하기

배포는 환경이 다양합니다. 여기서는 서버에 SSH로 접속해서 배포하는 방식을 예시로 잡겠습니다. (가장 흔하고 이해도 쉬움)

서버 배포 흐름(예시)

1. main 브랜치에 푸시
2. 테스트 통과
3. 서버에 접속
4. 코드 업데이트 + 설치 + 빌드 + 재시작 파일 생성: .github/workflows/cd.yml

name: CD

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: 체크아웃
        uses: actions/checkout@v4

      - name: Node.js 설정
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: 의존성 설치
        run: npm ci

      - name: 테스트 실행
        run: npm test

      - name: 빌드(필요한 경우)
        run: npm run build --if-present

      - name: 서버 배포(SSH)
        env:
          HOST: ${{ secrets.DEPLOY_HOST }}
          USER: ${{ secrets.DEPLOY_USER }}
          KEY: ${{ secrets.DEPLOY_SSH_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh -o StrictHostKeyChecking=no $USER@$HOST "cd /var/www/myapp && git pull && npm ci && npm run build --if-present && pm2 reload myapp || pm2 start server.js --name myapp"

Secrets 설정(중요)

저장소 설정에서 Secrets에 아래 값을 등록합니다.

• DEPLOY_HOST: 서버 주소
• DEPLOY_USER: 접속 사용자
• DEPLOY_SSH_KEY: 개인키(Private Key) 개인키는 유출되면 끝장입니다. 절대 코드에 직접 적지 말고, 반드시 Secrets로만 다루세요.

실전 팁: 실패했을 때 빠르게 원인 찾는 법

1) “의존성 설치에서 실패”

• package-lock.json이 최신인지 확인
• Node 버전 호환성 확인(로컬과 CI의 버전 차이)

2) “서버에서 pm2 명령이 없다”

• 서버에 pm2 설치 필요: npm i -g pm2
• 또는 systemd 등 본인 방식에 맞게 재시작 명령을 바꾸기

3) “권한/경로 문제”

• 서버의 배포 폴더(/var/www/myapp) 권한 확인
• git pull이 가능한 계정인지 확인

마무리: 한 번 만들어두면 배포가 ‘습관’이 됩니다

개발 초보 시절엔 기능 하나 추가하고도 배포가 부담입니다. 하지만 GitHub Actions로 테스트 자동화 + 배포 자동화까지 연결해두면, 작업 흐름이 깔끔해지고 실수도 줄어듭니다. 오늘은 SSH 배포 예시로 시작했지만, 익숙해지면 빌드 산출물 업로드, 컨테이너 배포 등으로 자연스럽게 확장할 수 있어요.

다음 단계로는 테스트 도구(Jest) 도입, 환경변수 분리, 배포 전용 사용자/권한 최소화를 해보면 더 탄탄해집니다.