🛠 Spring Boot 서버 GitHub Actions 자동 배포 정리 (Self-hosted runner)

실제 운영 중인 리눅스 서버에 GitHub Actions를 사용한 자동 배포를 구축하면서 발생했던 이슈와 해결 방법을 정리합니다.

---

✅ 목표

• dev 브랜치에 코드 푸시 시, 리눅스 서버에서 Spring Boot 프로젝트 자동 빌드 & 배포
• Docker + docker-compose 환경에서 실행 중인 API 서버를 자동 재배포

---

📁 서버 디렉토리 구조 (예시)

/home/service/
┣ meowro/
┃ ┣ api/
┃ ┃ ┗ dev/
┃ ┃    ┣ docker-compose.yml
┃ ┃    ┣ Dockerfile
┃ ┃    ┣ meowapi-0.0.X.jar ← 최신 버전 자동 복사됨

---

⚙ GitHub Actions 워크플로우 (.github/workflows/deploy-dev.yml)

name: Deploy to Dev Server

on:
  push:
    branches:
      - dev

jobs:
  deploy:
    runs-on: self-hosted

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

      - name: ☕️ Set up JDK
        uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: 🧱 Build Spring Boot JAR
        run: ./gradlew clean build -x test

      - name: 🧹 Delete old JARs & copy latest
        run: |
          rm -f /home/service/meowro/api/dev/*.jar
          latest_jar=$(ls -t build/libs/*.jar | head -n 1)
          cp "$latest_jar" /home/service/meowro/api/dev/

      - name: 🐳 Restart Docker container
        working-directory: /home/service/meowro/api/dev
        run: |
          docker-compose down
          docker-compose up -d --build

---

🧨 발생했던 문제 & 해결 방법

문제	원인	해결
cp: is not a directory	복사 대상 경로를 meowapi-0.0.1.jar로 고정했는데 파일명이 달라짐	*.jar 자동 탐색 + 디렉토리로 복사하도록 변경
Permission denied	Actions가 일반 사용자로 실행되는데, /home/service/...는 root 소유	chown -R 사용자:사용자 대상경로 로 소유권 변경
docker-compose: no config file found	작업 디렉토리 설정 안 되어 있음	working-directory: 명시해줌
Dockerfile 수정했는데 반영 안 됨	재기동(--build)을 안함	docker-compose up -d --build 명시
.jar 파일이 계속 쌓임	매번 새 파일이 복사되며 쌓임	rm -f *.jar로 기존 파일 삭제

---

🚀 Self-hosted runner 설정 팁

# 1. 일반 사용자 생성 및 권한 부여
sudo useradd -m realryan
sudo usermod -aG docker realryan

# 2. runner 디렉토리 이동 및 소유권 이전
sudo chown -R realryan:realryan /home/service/runner

run.sh 자동 실행을 위해 systemd 등록:

[Unit]
Description=GitHub Actions Runner (meowro)
After=network.target

[Service]
ExecStart=/bin/bash /home/service/runner/run.sh
WorkingDirectory=/home/service/runner
User=realryan
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable github-runner
sudo systemctl start github-runner

---

✅ 마무리

처음부터 끝까지 직접 구축하면서 겪은 오류와 해결 과정을 바탕으로
Spring Boot 프로젝트를 GitHub Actions로 자동 배포하는 구조를 완성했습니다.
실제로 운영 환경에 적용해도 충분히 활용 가능한 패턴입니다! 💪