Github Actions 이용하여 개발서버에 자동배포 만들기

Github Actions 공식 소개란

 

프로젝트를 개발하다 보면, 변경사항을 서버에 자동으로 반영하고 싶은 경우가 많습니다. 특히 GCP(Google Cloud Platform) 같은 클라우드 서버를 개발 서버로 사용하는 경우, 매번 수동으로 접속해서 git pull 하고, 빌드 및 실행 명령을 입력하는 과정은 번거롭고 실수도 발생할 수 있습니다.

이 글에서는 Github Actions를 이용하여 GCP 개발 서버에 자동으로 배포되는 구조를 만드는 방법을 소개합니다. CI는 기본 테스트를, CD는 서버 반영까지 자동으로 수행하는 구조입니다.

 

⛳ 목표 아키텍처

• Github에 코드가 develop 브랜치에 push되면,
• Github Actions가 실행되어,
  • 테스트 코드가 통과한 뒤,
  • GCP 개발 서버에 SSH로 접속해,
  • 최신 코드를 git pull 받고,
  • 준비해 둔 실행 스크립트를 실행하여 서버를 다시 띄웁니다.

 

Github Actions 워크플로우 작성

먼저, Github 저장소 내에 워크플로우 파일을 하나 생성합니다.

📄 .github/workflows/deploy.yml

name: Deploy to GCP via SSH

on:
  push:
    branches: [develop]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: ✅ Checkout the code (optional for test)
        uses: actions/checkout@v3

      - name: ✅ Install dependencies and run tests
        run: |
          yarn install --frozen-lockfile
          yarn test

      - name: 🔐 Setup SSH key
        uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.GCP_SSH_KEY }}

      - name: 🚀 SSH to GCP and deploy
        run: |
          ssh -o StrictHostKeyChecking=no ${{ secrets.GCP_USERNAME }}@${{ secrets.GCP_HOST }} << 'EOF'
            cd /home/${{ secrets.GCP_USERNAME }}/your-project
            git pull origin develop
            chmod +x ./script/docker/run.sh
            ./script/docker/run.sh
          EOF

• `on.push.branches` : 이곳에서 해당 Push 동작으로 Workflow 를 동작시킬 브랜치명을 지정합니다.
• YARN 패키지를 사용중인 프로젝트를 가정으로 하여, 종속성 설치 이후 테스트 코드를 실행합니다. (CI)
• SSH Key Setup 및 접속이 완료되고 나면, 해당 브랜치를 Pulling 합니다.
  따라서, 대상 branch 명이 `develop` 이 아니라면, 해당 브랜치명에 맞게 수정하도록 합니다.
• 마지막으로 준비된 실행 스크립트를 실행합니다. 해당 실행 스크립트 파일명이나 명령어를 맞춰 수정합니다.

 

🔨 원격 서버(GCP 인스턴스)에서 해야 할 작업

1. 프로젝트 clone 및 SSH 설정

• GCP 인스턴스에 프로젝트를 clone 해놓고, develop 브랜치가 기본 브랜치가 되도록 설정합니다.
• SSH 키를 생성하고, 이 공개키를 Github 계정의 SSH Key로 등록합니다.

ssh-keygen -t rsa -b 4096 -C "gcp-server"
cat ~/.ssh/id_rsa.pub  # 이 내용을 복사해서 Github 에 SSH Key로 등록

2. git pull 이 가능하게 설정

• GCP 서버에서 해당 프로젝트 폴더로 이동한 후,

git remote set-url origin git@github.com:yourname/your-repo.git

• 그런 다음 정상적으로 Github에 SSH로 접근 가능한지 확인합니다:

ssh -T git@github.com

 

 

🔐 Github Secrets 설정

자동화 과정에서 민감한 정보를 저장하고 접근하기 위해 Github에서는 Secrets 기능을 제공합니다.

Secrets 위치:

• Github 저장소 > Settings > Secrets and variables > Actions > New repository secret

등록해야 할 값들:

Name	설명
GCP_HOST	GCP 인스턴스의 공인 IP 또는 도메인
GCP_USERNAME	예: ubuntu, ec2-user 등 GCP 로그인 계정
GCP_SSH_KEY	Github Actions에서 GCP 서버에 접속할 때 사용할 비공개 SSH 키 (id_rsa 내용 전체)

 

배포 스크립트 예시 (run.sh)

서버에서는 보통 `.env` 를 주입하고, Docker로 컨테이너를 빌드/재시작하는 스크립트를 준비해둡니다.

#!/bin/bash

source .env
docker build -t my-app .
docker stop my-app || true
docker rm my-app || true
docker run -d --name my-app --env-file .env -p 3000:3000 my-app

 

 

👍 마무리

위의 과정을 통해 Github 저장소에 develop 브랜치로 push를 하면, 자동으로 GCP 개발 서버에 접속하여 배포가 진행됩니다. 테스트를 통과한 경우에만 서버에 반영되므로, 안정성과 자동화 두 마리 토끼를 모두 잡을 수 있습니다.

이 구조는 프로덕션 배포에도 응용할 수 있으며, main 브랜치 기준으로 프로덕션 서버에 배포하는 분기 처리도 쉽게 추가할 수 있습니다. 더 정교하게 하고 싶다면, 슬랙 알림, 롤백 처리, 배포 상태 체크 등도 추가 확장 가능합니다.