[DevOps] GitHub Actions로 Next.js + EC2 + PM2 자동 배포 파이프라인 구축하기

 

지금까지 저는 배포할 때마다 번거로운 과정을 수동으로 반복하며 아까운 시간을 흘려보내곤 했습니다. 그러던 중 GitHub Actions를 사용하면 push만으로 배포가 가능하다는 것을 알게 되었고, 이를 바로 프로젝트에 적용해 보았습니다.

현재 진행 중인 WebRTC 프로젝트의 설정을 바탕으로, GitHub Actions와 AWS EC2, PM2를 조합하여 코드 한 줄로 서버에 마법처럼 반영되는 CI/CD 파이프라인 구축 과정을 공유해 보겠습니다.

 

 

---

왜 자동 배포(CI/CD)가 필요한가요?

---

개발을 하다 보면 코드 수정 후 배포를 위해 매번 반복적인 작업을 하게 됩니다.

1. 서버에 SSH 접속
2. git pull 실행
3. npm install 및 npm run build
4. 서비스 재시작

이 과정은 시간이 아까울 뿐만 아니라, 피곤한 상태에서 명령어를 잘못 입력해 서버를 멈추게 할 위험도 있습니다. GitHub Actions를 사용하면 이 모든 과정을 스크립트 하나로 자동화하여 개발 생산성과 배포 안정성을 동시에 잡을 수 있습니다.

 

 

 

---

사용된 핵심 기술 스택

---

이번 가이드에서는 다음과 같은 도구들을 사용합니다.

• GitHub Actions: 코드 변경을 감지하고 워크플로우를 실행하는 엔진
• AWS EC2 (Ubuntu): 프로젝트가 실행될 가상 서버
• appleboy/ssh-action: GitHub Actions에서 SSH를 통해 원격 서버에 명령을 내릴 수 있게 해주는 라이브러리
• PM2: Node.js 애플리케이션을 무중단으로 관리해주는 프로세스 매니저

 

자동 배포를 처음 접하신다면 낯선 용어들이 많을 수 있습니다. 우리가 사용할 도구들이 각각 어떤 역할을 하는지 쉽게 풀어보겠습니다. 

 

1. GitHub Actions (자동화 로봇) 

"내가 하던 노가다를 대신 해주는 성실한 로봇"

지금까지는 코드를 수정하면 build하고, 서버에 접속해서 pull 받는 과정을 직접 하셨죠? GitHub Actions는 여러분이 시키는 일(워크플로우)을 대신 수행하는 GitHub 내장 자동화 시스템입니다. "내가 main 브랜치에 코드를 올리면, 네가 알아서 테스트하고 서버에 배포까지 해줘!"라고 명령서(YAML 파일)만 적어두면, 24시간 대기하다가 작업을 수행합니다.

2. AWS EC2 (24시간 켜진 컴퓨터) 

"아마존에서 빌린, 절대 꺼지지 않는 컴퓨터"

여러분이 집에서 쓰는 노트북은 덮으면 꺼지지만, 웹 사이트는 24시간 돌아가야 합니다. EC2는 아마존(AWS) 데이터 센터에 있는 컴퓨터 한 대를 원격으로 빌리는 것입니다. 우리는 이 컴퓨터에 우리의 프로젝트 코드를 올려두고 전 세계 사람들이 접속할 수 있게 합니다. (이번 실습에서는 가장 대중적인 Ubuntu 운영체제를 사용합니다.)

3. appleboy/ssh-action (원격 접속 마법사) 

"GitHub 로봇이 내 서버(EC2)에 접속할 수 있게 해주는 출입증"

GitHub Actions(로봇)와 EC2(서버)는 물리적으로 멀리 떨어져 있습니다. 로봇이 서버에 들어가서 배포 명령을 내리려면 로그인을 해야겠죠? 이 도구는 GitHub Actions가 SSH(보안 접속) 를 통해 안전하게 EC2 서버 안으로 쏙 들어가서 명령어를 칠 수 있게 도와주는 GitHub Actions 전용 플러그인입니다. 복잡한 보안 설정을 간단하게 만들어줍니다.

4. PM2 (불사신 관리자) 

"서버가 죽으면 1초 만에 되살리는 관리 소장님"

보통 npm run start로 서버를 켜면 터미널 창을 끄는 순간 서버도 같이 꺼집니다. PM2(Process Manager 2)는 Node.js 프로그램을 백그라운드(뒷단) 에서 계속 실행시켜 줍니다. 더 대단한 점은, 에러가 발생해서 서버가 갑자기 멈추더라도 PM2가 감지하고 즉시 다시 실행(Auto Restart) 시켜준다는 것입니다. 실무 배포에서는 선택이 아닌 필수 도구입니다!

 

 

---

GitHub Actions 5대 핵심 개념

---

본격적인 설정에 앞서, 설정 파일(yml)을 이해하기 위해 꼭 알아야 할 5가지 용어가 있습니다.

1. Workflows (워크플로우): 가장 큰 단위의 '전체 자동화 과정'입니다. 파일 하나가 하나의 워크플로우입니다.
2. Events (이벤트): 워크플로우를 시작시키는 '방아쇠'입니다. (예: push, pull_request)
3. Jobs (잡): 하나의 워크플로우 안에서 실행되는 작업의 단위입니다.
4. Actions (액션): Job 안에서 실행되는 개별 동작이나 명령어입니다. (예: checkout, ssh-action)
5. Runners (러너): 이 작업을 실제로 수행하는 GitHub의 임시 서버(컴퓨터)입니다.

 

---

전체 파이프라인 흐름도

---

우리가 만들 배포 시스템의 작동 원리는 아주 심플한 단방향 흐름입니다.

우리가 만들 배포 시스템의 작동 원리는 아주 심플한 단방향 흐름입니다.graph LR
A[💻 내 컴퓨터] -- git push --> B(🐙 GitHub Repository)
B -- Action 감지 --> C{⚙️ GitHub Actions}
C -- SSH 접속 --> D[☁️ AWS EC2]
D -- 1. git pull --> E[🔄 코드 갱신]
E -- 2. build --> F[📦 빌드]
F -- 3. pm2 reload --> G[🚀 배포 완료]

 

1. Push: 로컬에서 main 브랜치로 코드를 올립니다.
2. Detect: GitHub Actions가 이 신호를 감지합니다.
3. Connect: ssh-action을 통해 로봇이 우리 EC2 서버에 접속합니다.
4. Deploy: 서버 내부에서 [코드 받기 → 빌드하기 → PM2 재시작] 과정을 순차적으로 수행합니다.

 

---

Step 1: GitHub Secrets 설정 (보안 필수)

---

워크플로우 파일에 서버의 IP나 비밀키를 그대로 노출하면 해킹의 위험이 있습니다. GitHub의 Secrets 기능을 이용해 환경변수로 안전하게 관리해야 합니다.

1. GitHub 레포지토리 접속 -> Settings 탭 클릭
2. 좌측 메뉴의 Secrets and variables -> Actions 선택
3. New repository secret 버튼을 눌러 아래 3가지 값을 등록합니다.

이름	설명	값 예시
EC2_HOST	서버의 탄력적 IP (Public IP)	13.124.xx.xx
EC2_USERNAME	서버 접속 계정 이름	ubuntu
EC2_SSH_KEY	.pem 키 파일의 내용 전체	-----BEGIN RSA PRIVATE KEY-----

 

 

EC2_SSH_KEY에는 .pem 파일을 메모장으로 열어서 시작부터 끝까지 전체 내용을 복사해서 넣어야 합니다.

 

 

---

Step 2: 서버 사전 준비 (최초 1회)

---

자동 배포 스크립트가 실행되려면, 서버에 프로젝트가 한 번은 존재해야 하며 PM2가 설치되어 있어야 합니다. EC2 터미널에 접속해서 다음 명령어들을 입력해 주세요.

# 1. 홈 디렉토리로 이동
cd ~

# 2. 프로젝트 클론 (최초 1회만 필요)
git clone [본인의 레포지토리 주소] app

# 3. PM2 전역 설치 (이미 설치했다면 생략)
npm install -g pm2

이제 GitHub Actions는 이 ~/app 폴더를 찾아가서 작업을 수행하게 됩니다.

 

---

Step 3: Workflow 파일 작성 (핵심!)

---

이제 프로젝트 루트 경로에 .github/workflows/deploy.yml 파일을 생성하고 아래 내용을 작성합니다

 

name: Deploy to EC2

on:
  push:
    branches:
      - main # main 브랜치에 푸시될 때마다 실행

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Deploy to EC2
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ${{ secrets.EC2_USERNAME }}
          key: ${{ secrets.EC2_SSH_KEY }}
          script: |
            # 1. 프로젝트 폴더로 이동
            cd ~/app
            
            # 2. 최신 코드 가져오기
            git pull origin main
            
            # 3. 의존성 설치 및 빌드 (경로 주의!)
            cd frontend 
            npm install
            npm run build
            
            # 4. PM2를 이용한 서비스 재시작
            # 기존 프로세스가 있으면 재시작(restart), 없으면 새로 시작(start)
            pm2 restart frontend || pm2 start npm --name "frontend" -- start -- -H 0.0.0.0
            
            echo "✅ Deployment complete!"

주요 코드 포인트

• uses: appleboy/ssh-action@...: 아까 설명한 '원격 접속 마법사'를 불러오는 부분입니다. npm install 필요 없이 이렇게 적기만 하면 됩니다.
• ${{ secrets... }}: Step 1에서 등록한 비밀 변수들을 안전하게 가져옵니다.
• pm2 restart ... || pm2 start ...: 이 부분이 핵심입니다! pm2 restart를 먼저 시도하고, 만약 실행 중인 프로세스가 없다면(에러 발생 시) || 뒤의 start 명령어를 실행하여 서비스를 처음부터 띄웁니다.

 

---

마무리

---

이제 모든 설정이 끝났습니다! 로컬에서 코드를 수정하고 main 브랜치로 git push를 해보세요. GitHub의 Actions 탭에서 초록색 체크 표시(✅)가 뜨고, 실제 사이트가 업데이트되었다면 성공입니다.

이 간단한 설정 하나가 여러분의 개발 퀄리티와 시간을 획기적으로 아껴줄 것입니다. 배포의 귀찮음에서 벗어나 개발에만 집중해 보세요!