초보자를 위한 GitHub Actions로 Node.js 프로젝트 자동 테스트·배포 (기본 워크플로우 YAML 작성부터)

“커밋했는데 테스트는 누가 돌리지?”, “배포는 또 수동으로 해야 해?” Node.js 프로젝트를 하다 보면 결국 반복 작업이 발목을 잡습니다. GitHub Actions를 쓰면 푸시/PR만으로 테스트가 자동 실행되고, 조건이 맞으면 배포까지 한 번에 이어지게 만들 수 있어요. 오늘은 초보자도 그대로 따라 할 수 있는 기본 워크플로우 YAML을 중심으로, 실무에서 바로 쓰는 형태로 정리합니다.

1) 준비물: 프로젝트에 꼭 필요한 최소 조건

체크리스트

• package.json에 테스트 스크립트가 있어야 합니다.
• 예: "test": "jest" 또는 "test": "vitest run" 등
• Node 버전은 LTS 기준으로 시작하는 것을 권장합니다(예: 20).
• 배포는 예시로 “서버에 SSH로 접속해 배포 스크립트 실행” 흐름을 사용합니다. (가장 범용적)

예시 package.json (핵심만)

{
  "scripts": {
    "test": "npm run lint && npm run unit",
    "lint": "eslint .",
    "unit": "vitest run",
    "build": "tsc -p ."
  }
}

2) 자동 테스트 워크플로우 만들기 (가장 먼저 추천)

레포지토리 루트에 아래 경로로 파일을 만듭니다.

• .github/workflows/ci.yml

기본 CI 워크플로우 (테스트 자동 실행)

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [20]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

포인트 정리

• on: pull_request를 넣으면 PR 올릴 때 자동 검증이 됩니다.
• npm install 대신 npm ci를 쓰면 락파일 기준으로 더 안정적으로 설치됩니다.
• cache: "npm" 덕분에 재실행이 빨라질 수 있습니다.

3) “테스트 통과하면 배포”로 이어 붙이기

여기서부터가 진짜 자동화의 맛입니다. 구조는 간단합니다.

• CI(테스트)가 성공하면
• CD(배포)가 실행되도록 연결 같은 파일에 배포 Job을 추가해도 되고, 분리해도 됩니다. 처음엔 한 파일이 이해하기 쉬워요.

테스트 성공 후 배포(Job 연결)

name: CI-CD

on:
  push:
    branches: [ "main" ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"
      - run: npm ci
      - run: npm test
      - run: npm run build

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: ${{ success() }}

    steps:
      - name: Deploy via SSH
        env:
          SSH_HOST: ${{ secrets.SSH_HOST }}
          SSH_USER: ${{ secrets.SSH_USER 
              
         

4) Secrets 설정: 비밀번호를 코드에 쓰지 않는 방법

위 배포 예시는 secrets를 사용합니다. 레포지토리 설정에서 아래 값을 등록해야 해요.

• SSH_HOST : 서버 주소
• SSH_USER : 접속 사용자
• SSH_KEY : 개인키(보통 PEM 형식) 여기서 중요한 건 개인키는 절대 저장소에 올리지 않는 것입니다. 또한 서버에는 해당 키의 공개키가 등록되어 있어야 SSH 접속이 됩니다.

5) 초보자가 자주 막히는 지점 3가지

1) “테스트가 없어서 실패해요”

npm test가 실제로 실행할 테스트가 없으면 실패할 수 있습니다. 당장 테스트를 못 쓰더라도, 임시로라도 test 스크립트를 정리해 두는 게 좋아요.

2) “main 말고 develop에서만 돌리고 싶어요”

브랜치만 바꾸면 됩니다.

on:
  push:
    branches: ["develop"]

3) “배포가 위험해 보여요”

처음엔 배포 Job을 주석 처리하고, CI만 안정화한 뒤 배포를 붙이세요. 또는 workflow_dispatch(수동 실행)로 배포를 시작하는 것도 안전합니다.

6) 오늘의 정리: 이 순서로 하면 실패 확률이 낮습니다

1. ci.yml로 테스트 자동화부터 붙인다
2. npm ci + 캐시로 실행을 안정화한다
3. needs: test로 테스트 성공 → 배포 흐름을 만든다
4. 민감 정보는 secrets로 관리한다 이 정도만 구축해도, 커밋하는 순간부터 프로젝트가 훨씬 “팀처럼” 굴러가기 시작합니다. 다음 단계로는 테스트 매트릭스(여러 Node 버전), 환경별 배포(dev/staging/prod), 아티팩트 업로드 같은 확장도 자연스럽게 이어갈 수 있어요.