GitHub Actions SSH 배포 완벽 가이드 — 서버에 자동 배포하는 방법

GitHub Actions 안전한 SSH 배포를 위한 비밀 키 생성과 서버 권한 설정 요령

서버의 루트 비밀번호를 GitHub Actions 스크립트에 날것으로 적는 것은 자살 행위와 같습니다. 안전한 SSH 통신을 위해 ssh-keygen -t ed25519 명령으로 배포 전용 키 쌍을 새로 굽는 것이 정석이죠. 생성된 공개 키(public key)는 대상 클라우드 서버의 ~/.ssh/authorized_keys에 조심스럽게 기입해 두고, 비밀 키(private key)는 오직 내 깃허브 저장소의 Secrets 안전금고에만 꽁꽁 숨겨둡니다. 여기서 주의할 점은 서버 내 .ssh 폴더 권한은 700, authorized_keys 파일 권한은 600으로 굳건히 잠가두어야 운영체제 보안 커널 수준에서 SSH handshake 요청을 튕겨내지 않고 수락해 줍니다.

GitHub Actions YAML 작성과 SSH 접속 프롬프트 우회 방법

배포 워크플로 YAML 파일을 설계할 때, 첫 SSH 접속 시 터미널이 대기 상태로 머물며 접속 승인 여부를 묻는 대화형 프롬프트(Are you sure you want to continue connecting?)를 만나는 장벽이 있습니다. CI 가상머신에서는 키보드 입력을 줄 수 없으니 배포가 멍하니 멈추다 타임아웃으로 실패하게 되죠. 이를 해소하기 위해 ssh-keyscan 도구를 워크플로 중간에 수배하여 대상 서버의 공개 호스트 키 정보를 사전에 known_hosts에 자동 이식해 놓거나, 편리한 appleboy/ssh-action 서드파티 액션을 기용해 내부에 호스트 접속 인자값들을 정돈해 주는 것이 파이프라인 통과의 지름길입니다.

# .github/workflows/deploy.yml
name: Deploy to Server

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: ${{ secrets.SSH_PORT }}
          script: |
            cd /var/www/myapp
            git pull origin main
            npm ci --production
            npm run build
            pm2 restart myapp

배포 다운타임을 제로로 만드는 PM2 reload 연동 기법

서버 내부에서 코드를 땡겨온(git pull) 뒤 단순히 pm2 restart 명령을 날리면, 기존 Node 프로세스가 완전히 차단되고 새 프로세스가 켜질 때까지 약 2~5초간 사용자가 접속할 수 없는 끔찍한 다운타임이 강제 발생합니다. 이를 극복하려면 PM2의 reload 기능을 기용해야 합니다. PM2 reload는 클러스터 모드로 돌아가는 인스턴스들을 하나씩 차례로 내렸다가 깨우는 롤링 배포 방식을 실행하므로, 배포가 도는 중에도 최소 한 개 이상의 서버 스레드가 유저 요청을 보위하여 완벽한 Zero-downtime 무중단 실무 환경을 완수해 줍니다.

GitHub Actions SSH 배포 성공과 실패를 Slack으로 알림 받는 방법

배포가 성공적으로 안착했는지 혹은 실시간 빌드 중 다운되어 에러가 났는지를 팀 메신저로 전파하는 구조를 구성하는 것이 운영 관리상 현명합니다. 슬랙에서 Incoming Webhook API 주소를 개설한 뒤 깃허브 Secrets에 묻어두고, 워크플로 마지막 절차에 if 조건(always, failure) 분기 매칭을 추가해두면 젠킨스를 빌리지 않고도 배포 생태계 성공 현황판을 안전하게 알림 수령할 수 있습니다.