GitHub Actions 배포 전략: VPS부터 클라우드 플랫폼까지의 CD 파이프라인

들어가며

새벽 세 시, GitHub Actions 로그 화면을 바라보는데 빨간 오류가 한 줄씩 위로 올라왔습니다. “Host key verification failed.” 또 SSH 문제였습니다.

벌써 다섯 번째 배포 실패였습니다. 로컬 테스트는 전부 통과했는데 GitHub에 push하자마자 터졌습니다. 그 순간 정말 화가 났지만, 한 가지를 깨달았습니다. 배포 전략을 고르는 일은 제가 생각했던 것보다 훨씬 복잡했습니다.

직접 관리하는 VPS든 Vercel이나 Cloudflare Pages 같은 호스팅 플랫폼이든, 모든 방식에는 함정이 있습니다. 잘못 선택하면 한밤중에 디버깅하는 횟수만 늘어납니다.

이 글에서는 GitHub Actions의 여러 배포 전략을 살펴보고, 자신의 프로젝트에 맞는 방법을 찾을 수 있도록 돕겠습니다.

VPS SSH 배포: 전통적이지만 믿을 수 있는 방식

솔직히 처음에는 VPS 배포가 정말 싫었습니다. SSH 키, known_hosts, rsync 옵션 등 챙길 것이 너무 많고 번거롭게 느껴졌습니다.

하지만 몇 번 시행착오를 겪고 나니 오히려 이 “전통적인” 방식이 가장 제어하기 쉽다는 사실을 알게 됐습니다.

SSH 키 설정: 하드코딩하지 마세요

가장 흔한 문제는 SSH 키를 어디에 둘지입니다.

초보자는 비공개 키를 workflow 파일에 직접 넣곤 합니다. 절대 해서는 안 됩니다. 올바른 저장 위치는 GitHub Secrets입니다.

저장소의 Settings → Secrets → Actions에서 SSH_PRIVATE_KEY를 추가합니다. 그리고 workflow에서는 다음과 같이 사용합니다.

- name: Setup SSH
  uses: webfactory/[email protected]
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

이 action은 ssh-agent를 자동으로 시작하고 키를 불러옵니다. 간편합니다.

known_hosts: “Host key verification failed” 피하기

SSH로 서버에 처음 연결하면 해당 host를 신뢰할 것인지 묻습니다. CI 환경에서는 대화형 질문에 답할 수 없으므로 서버 지문을 known_hosts에 미리 추가해야 합니다.

두 가지 방법이 있습니다.

방법 1: action으로 자동 추가

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

- name: Add server to known hosts
  uses: webfactory/[email protected]
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
    known-hosts: ${{ secrets.SSH_KNOWN_HOSTS }}

SSH_KNOWN_HOSTS의 내용은 다음과 같이 가져올 수 있습니다.

ssh-keyscan -H your-server.com >> known_hosts.txt
# 파일 내용을 GitHub Secrets에 복사합니다

방법 2: 직접 설정

- name: Add server to known hosts
  run: |
    mkdir -p ~/.ssh
    ssh-keyscan -H ${{ secrets.SERVER_IP }} >> ~/.ssh/known_hosts

방법 1이 더 깔끔하고, 방법 2는 빠르게 디버깅할 때 적합합니다.

rsync와 scp 중 무엇을 써야 할까요?

배포 파일 전송에는 rsync를 사용합니다. 이유는 간단합니다.

• 변경된 파일만 전송하여 시간을 절약합니다.
• 특정 디렉터리(예: node_modules)를 제외할 수 있습니다.
• 증분 동기화를 지원합니다.

일반적인 rsync 명령은 다음과 같습니다.

- name: Deploy to server
  run: |
    rsync -avz --delete \
      --exclude 'node_modules' \
      --exclude '.git' \
      ./dist/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }}:/var/www/html/

--delete 옵션은 원본 디렉터리에 없는 파일을 대상 디렉터리에서 삭제합니다. 조심해서 사용해야 합니다. 경로를 잘못 지정하면 삭제하면 안 되는 파일까지 지울 수 있습니다.

배포 후 명령: 서비스 재시작

정적 웹사이트는 파일 전송이 끝나면 배포도 끝납니다. 하지만 Node.js 애플리케이션이라면 서비스까지 재시작해야 합니다.

저는 PM2로 Node 프로세스를 관리하는 방식을 선호합니다. 배포 후 다음 명령을 실행합니다.

- name: Restart application
  run: |
    ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
      "cd /var/www/app && pm2 restart all"

더 안전하게 특정 애플리케이션만 재시작할 수도 있습니다.

- name: Restart application
  run: |
    ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
      "pm2 restart my-app --update-env"

--update-env는 환경 변수를 다시 불러오므로 설정이 바뀐 경우에 적합합니다.

클라우드 플랫폼 배포: 호스팅 서비스의 편리함

VPS 배포의 문제는 서버를 직접 관리해야 한다는 점입니다. 보안 패치, SSL 인증서 갱신, 방화벽 규칙 등 자잘한 일이 많습니다.

호스팅 플랫폼은 훨씬 편합니다. 코드를 push하면 자동으로 빌드하고 배포합니다. 개발자는 코드 작성에만 집중하면 됩니다.

Vercel: 프런트엔드 프로젝트의 첫 번째 선택

Vercel의 프런트엔드 프로젝트 지원은 거의 완벽합니다. Next.js, Astro, React 모두 한 번에 배포할 수 있고 별도 설정도 거의 필요 없습니다.

하지만 프로젝트에 백엔드 API가 필요하다면 주의해야 합니다. Vercel의 Serverless Functions에는 실행 시간 제한이 있습니다(무료 버전 10초, Pro 버전 60초). 이 시간을 넘으면 timeout이 발생합니다.

순수 정적 사이트나 간단한 API라면 Vercel로 충분합니다. 복잡한 백엔드 서비스는 여전히 직접 관리하는 편이 낫습니다.

GitHub Actions에서 Vercel로 배포하는 설정은 다음과 같습니다.

name: Deploy to Vercel

on:
  push:
    branches: [main]

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

      - name: Install Vercel CLI
        run: npm i -g vercel@latest

      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

VERCEL_TOKEN은 Vercel 대시보드에서 생성한 뒤 GitHub Secrets에 저장합니다.

Cloudflare Pages: 넉넉한 무료 한도

Cloudflare Pages의 무료 한도는 Vercel보다 훨씬 넉넉합니다. 대역폭은 무제한이고 월 500회까지 빌드할 수 있어 개인 프로젝트에는 충분합니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

Cloudflare의 글로벌 CDN은 실제로 빠릅니다. 직접 테스트해 본 결과 아시아 지역 접속 속도도 Vercel보다 안정적이었습니다.

배포 설정은 다음과 같습니다.

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

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

      - name: Build
        run: npm run build

      - name: Deploy
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-project
          directory: dist

Cloudflare에는 또 다른 장점이 있습니다. R2 스토리지의 무료 한도도 넉넉합니다. 정적 리소스를 R2에 저장하고 Pages의 CDN과 함께 사용하면 로딩 속도를 상당히 높일 수 있습니다.

Netlify: 오랫동안 검증된 안정적인 선택지

Netlify는 앞의 두 플랫폼만큼 자주 사용하지는 않지만, 오래된 호스팅 플랫폼이라 생태계가 성숙했습니다.

배포 설정도 비슷합니다.

- name: Deploy to Netlify
  uses: netlify/actions/cli@master
  with:
    args: deploy --prod
  env:
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Netlify의 Form handling 기능은 꽤 실용적입니다. 양식 제출을 자동으로 처리하므로 간단한 마케팅 페이지에 적합합니다.

호스팅 플랫폼의 제약

물론 호스팅 플랫폼이 만능은 아닙니다.

자주 마주치는 제약은 다음과 같습니다.

1. 제한된 빌드 환경: 메모리와 CPU에 상한이 있어 대규모 프로젝트는 빌드에 실패할 수 있습니다.
2. 낮은 사용자 지정 자유도: nginx 설정을 바꾸고 싶어도 할 수 없습니다.
3. 플랫폼 존속에 대한 의존: 플랫폼이 서비스를 종료하거나 정책을 바꾸면 이전해야 합니다.
4. 중국 내 접속 문제: 일부 플랫폼은 중국에서 접속이 불안정합니다(Cloudflare는 개선되고 있음).

프로젝트를 완전히 제어해야 한다면 결국 VPS로 돌아가야 합니다.

하이브리드 전략: 유연성과 제어권을 동시에

많은 프로젝트는 “순수 정적”도 “순수 백엔드”도 아닙니다. 프런트엔드는 Next.js지만 백엔드는 데이터베이스에 연결하고 예약 작업도 실행해야 할 수 있습니다.

이런 경우에는 하이브리드 배포가 최선의 선택일 수 있습니다.

정적 페이지 호스팅 + API는 VPS에 배포

일반적인 아키텍처는 다음과 같습니다.

• 정적 페이지(HTML/CSS/JS)는 Cloudflare Pages 또는 Vercel에 배포합니다.
• Node.js API 서비스는 자체 VPS에 배포합니다.
• 데이터베이스도 VPS에 두거나 Supabase/PlanetScale 호스팅을 사용합니다.

각 방식의 장점을 활용할 수 있습니다.

• 프런트엔드는 CDN 가속과 자동 HTTPS를 활용합니다.
• 백엔드는 호스팅 플랫폼의 제약 없이 완전한 제어권을 갖습니다.
• API와 데이터베이스가 같은 서버에 있어 데이터베이스 접근 지연이 낮습니다.

GitHub Actions 다단계 배포

하나의 workflow에서 두 곳에 동시에 배포할 수 있습니다.

name: Hybrid Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-path: ./dist
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist

  deploy-frontend:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-frontend
          directory: dist

  deploy-backend:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup SSH
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
      - name: Deploy API to VPS
        run: |
          rsync -avz --delete \
            --exclude 'node_modules' \
            ./api/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }}:/var/www/api/
      - name: Restart API service
        run: |
          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
            "cd /var/www/api && npm install && pm2 restart api"

이 workflow에는 세 개의 job이 있습니다.

1. build: 프로젝트를 빌드하고 정적 파일을 생성합니다.
2. deploy-frontend: 정적 파일을 Cloudflare Pages에 배포합니다.
3. deploy-backend: API를 VPS에 배포하고 서비스를 재시작합니다.

needs: build는 빌드가 끝난 후에만 배포 job이 실행되도록 합니다. upload-artifact와 download-artifact는 job 사이에서 빌드 결과물을 전달합니다.

환경 변수 분리

하이브리드 배포의 한 가지 과제는 프런트엔드와 백엔드에 서로 다른 환경 변수가 필요하다는 점입니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

프런트엔드는 API 주소를 알아야 하고 백엔드는 데이터베이스 비밀번호를 알아야 합니다.

저는 다음과 같이 처리합니다.

# 프런트엔드 job
- name: Set frontend env
  run: |
    echo "API_URL=https://api.mydomain.com" >> $GITHUB_ENV

# 백엔드 job
- name: Deploy with env
  run: |
    ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
      "cd /var/www/api && pm2 restart api --update-env DATABASE_URL=${{ secrets.DATABASE_URL }}"

데이터베이스 비밀번호나 API token 같은 민감한 정보는 항상 GitHub Secrets를 사용합니다. API 주소처럼 민감하지 않은 정보는 workflow에 직접 작성할 수 있습니다.

실전 설정 예시

아래는 앞에서 설명한 모든 핵심 사항을 포함한 완전한 VPS 배포 workflow입니다.

완전한 workflow 파일

name: Deploy to VPS

on:
  push:
    branches: [main]
  workflow_dispatch:  # 수동 배포 실행

env:
  NODE_VERSION: '20'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist
          retention-days: 1

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist

      - name: Setup SSH
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Add server to known hosts
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan -H ${{ secrets.SERVER_HOST }} >> ~/.ssh/known_hosts

      - name: Deploy files
        run: |
          rsync -avz --delete \
            --exclude '.htaccess' \
            ./dist/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }}:${{ secrets.DEPLOY_PATH }}

      - name: Verify deployment
        run: |
          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }} \
            "ls -la ${{ secrets.DEPLOY_PATH }}"

      - name: Send deployment notification
        if: always()
        run: |
          curl -X POST "${{ secrets.NOTIFICATION_WEBHOOK }}" \
            -H "Content-Type: application/json" \
            -d '{"text": "Deployment completed: ${GITHUB_SHA}"}'

설정해야 하는 Secrets

자주 발생하는 문제 해결

배포가 실패하면 로그가 너무 많아 어디부터 봐야 할지 막막할 수 있습니다.

저는 다음 순서로 확인합니다.

1. SSH 연결 문제: “Setup SSH”와 “Add server to known hosts” 단계를 확인합니다.
   • 실패했다면 키 형식과 known_hosts 내용을 확인합니다.
2. rsync 전송 문제: “Deploy files” 단계를 확인합니다.
   • 실패했다면 경로가 존재하는지, 권한이 올바른지 확인합니다.
3. 서비스 재시작 문제: “Verify deployment” 단계를 확인합니다.
   • 실패했다면 대상 경로에 파일이 있는지 확인합니다.

한 가지 팁은 실패한 단계 뒤에 디버그 출력을 추가하는 것입니다.

- name: Debug SSH connection
  if: failure()
  run: |
    echo "SSH config:"
    cat ~/.ssh/config || echo "No config file"
    echo "Known hosts:"
    cat ~/.ssh/known_hosts || echo "No known_hosts file"
    ssh -v ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }} echo "Connection test"

ssh -v는 상세 로그를 출력하므로 문제가 발생한 위치를 확인할 수 있습니다.

마무리

긴 이야기를 한 문장으로 줄이면 이렇습니다. 완벽한 배포 방식은 없고, 프로젝트에 가장 잘 맞는 방식만 있습니다.

선택 가이드:

• 순수 정적 사이트(블로그, 문서): 관리가 편한 Cloudflare Pages 또는 Vercel
• 간단한 API + 프런트엔드: 호스팅 플랫폼으로 충분하므로 굳이 VPS를 운영하지 않아도 됩니다.
• 복잡한 백엔드 + 데이터베이스: 제어권이 중요한 VPS 또는 클라우드 서버
• 하이브리드 아키텍처: 프런트엔드는 호스팅, 백엔드는 VPS에 배포하여 각 방식의 장점을 활용

어떤 방식을 선택하든 GitHub Actions의 설정 패턴은 비슷합니다. 빌드 → 전송 → 재시작입니다. 이 세 단계를 명확히 나누면 디버깅할 때 방향을 잃지 않습니다.

그리고 배포가 실패해도 당황하지 마세요. 로그를 단계별로 살펴 먼저 SSH 연결 문제인지 명령 실행 문제인지 확인하세요. 디버그 단계 하나만 추가해도 문제는 금방 드러납니다.

다음번 새벽 세 시에 배포가 실패한다면, 더 빨리 원인을 찾을 수 있기를 바랍니다.