GitHub Actions를 이용한 CI/CD 구축 완벽 가이드

1. 개요

GitHub Actions는 GitHub 저장소에서 직접 워크플로우를 자동화할 수 있는 강력한 CI/CD(Continuous Integration / Continuous Deployment) 도구입니다. 코드 푸시, 브랜치 병합, PR 생성 등의 이벤트에 따라 자동으로 테스트, 빌드, 배포 작업을 수행할 수 있습니다.

이번 포스팅에서는 GitHub Actions를 이용한 자동 빌드 및 배포 파이프라인 구축 방법을 단계별로 정리합니다.

2. 사전 준비

✅ 1) GitHub 저장소 생성

GitHub에 새 저장소를 생성합니다. 예를 들어 프로젝트 이름을 my-app으로 설정합니다.

✅ 2) 프로젝트 준비

Node.js, React, Spring Boot 등 원하는 프로젝트를 준비합니다.
여기서는 예시로 React 앱(N + TypeScript)을 사용합니다.

✅ 3) 배포 환경 설정

• Vercel, Netlify, Render, AWS EC2, 또는 개인 서버 중 하나를 선택합니다.

• SSH 또는 API 토큰 방식으로 GitHub Actions가 접근할 수 있도록 합니다.

3. GitHub Actions 워크플로우 생성

경로

.github/workflows/deploy.yml

 예시 코드

name: Deploy to Production

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

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

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

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

      - name: Install Dependencies
        run: npm ci

      - name: Build Project
        run: npm run build

      - name: Deploy to Server via SSH
        uses: appleboy/scp-action@v0.1.5
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: 'dist/'
          target: '/var/www/my-app'

docker 배포 예

name: Build and Deploy

on:
    push:
        branches:
            - main

jobs:
    build-and-push:
        runs-on: ubuntu-latest

        steps:
            - name: Checkout Code
              uses: actions/checkout@v3

            - name: Set Up Docker Buildx
              uses: docker/setup-buildx-action@v2

            - name: Log In To Docker Hub
              uses: docker/login-action@v2
              with:
                  username: ${{ secrets.DOCKER_USERNAME }}
                  password: ${{ secrets.DOCKER_PASSWORD }}

            - name: Build And Push Docker Image
              run: |
                  docker buildx build --platform linux/amd64,linux/arm64 -t testDocker/fc-nestjs-gateway:latest -t testDocker/fc-nestjs-gateway:${{ github.sha }} -f ./apps/gateway/Dockerfile --target production --push .
                  docker buildx build --platform linux/amd64,linux/arm64 -t testDocker/fc-nestjs-notification:latest -t testDocker/fc-nestjs-notification:${{ github.sha }} -f ./apps/notification/Dockerfile --target production --push .
                  docker buildx build --platform linux/amd64,linux/arm64 -t testDocker/fc-nestjs-order:latest -t testDocker/fc-nestjs-order:${{ github.sha }} -f ./apps/order/Dockerfile --target production --push .
                  docker buildx build --platform linux/amd64,linux/arm64 -t testDocker/fc-nestjs-payment:latest -t testDocker/fc-nestjs-payment:${{ github.sha }} -f ./apps/payment/Dockerfile --target production --push .
                  docker buildx build --platform linux/amd64,linux/arm64 -t testDocker/fc-nestjs-product:latest -t testDocker/fc-nestjs-product:${{ github.sha }} -f ./apps/product/Dockerfile --target production --push .
                  docker buildx build --platform linux/amd64,linux/arm64 -t testDocker/fc-nestjs-user:latest -t testDocker/fc-nestjs-user:${{ github.sha }} -f ./apps/user/Dockerfile --target production --push .

4. GitHub Secrets 설정

GitHub 저장소 → Settings → Secrets and variables → Actions 로 이동합니다.

다음 변수를 추가하세요:

이름설명

SERVER_HOST서버 IP 또는 도메인

SERVER_USERSSH 접속 계정명

SSH_PRIVATE_KEY개인 SSH 키 (id_rsa 내용 전체)

5. 자동 배포 과정 요약

1. main 브랜치에 코드 푸시

2. GitHub Actions가 자동으로 워크플로우 실행

3. npm build → 빌드 파일 생성

4. SSH를 통해 서버로 업로드

5. 웹서버(Nginx, Apache 등)에서 최신 버전으로 자동 반영

6. 고급 설정 (옵션)

 Branch 별 배포 분기

on:
  push:
    branches:
      - main
      - dev

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to Production
        run: echo "Production Deploy"

  staging:
    if: github.ref == 'refs/heads/dev'
    steps:
      - name: Deploy to Staging
        run: echo "Staging Deploy"

???? 캐시 적용

- name: Cache Node modules
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

7. 배포 후 자동 재시작 (PM2 예시)

SSH 명령을 이용해 서버 내 프로세스를 자동 재시작할 수도 있습니다.

- name: Restart PM2
  uses: appleboy/ssh-action@v1.0.0
  with:
    host: ${{ secrets.SERVER_HOST }}
    username: ${{ secrets.SERVER_USER }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    script: |
      cd /var/www/my-app
      pm2 restart all

8. 마무리

이제 git push origin main 명령만 실행해도 자동으로 빌드와 배포가 이루어지는 완전한 CI/CD 파이프라인이 완성되었습니다.

✅ 핵심 요약:

• GitHub Actions로 서버 배포 자동화 가능

• Secrets 설정으로 보안 강화

• SSH 및 PM2로 실서비스 관리