GitLab Runner를 이용한 Spring Boot 자동 배포 구축하기 (AlmaLinux 9)

GitLab Runner와 GitLab CI/CD를 활용하여 AlmaLinux 9 환경에서 Spring Boot 애플리케이션 자동 배포 시스템을 구축하는 방법을 알아봅니다. Git Push만으로 빌드, JAR 배포, 서비스 재시작까지 자동화할 수 있습니다

GitLab Runner를 이용한 Spring Boot 자동 배포 구축하기 (AlmaLinux 9)

Spring Boot 프로젝트를 운영하다 보면 코드 수정 후 서버 접속, 빌드, JAR 복사, 서비스 재시작 과정을 반복하게 됩니다. 프로젝트 규모가 커질수록 이러한 수동 배포는 실수를 유발하고 운영 효율을 떨어뜨립니다.

이번 글에서는 GitLab Runner와 GitLab CI/CD를 활용하여 Git Push만으로 Spring Boot 애플리케이션이 자동 배포되도록 구성하는 방법을 정리해보겠습니다.

구성 환경은 AlmaLinux 9 기반이며 GitLab 저장소와 GitLab Runner, systemd 서비스를 이용하여 자동 배포 환경을 구축합니다.

---

자동 배포 구조

전체 배포 흐름은 다음과 같습니다.

개발자
   │
git push
   │
GitLab
   │
GitLab Runner
   │
SSH 접속
   │
Spring Boot Build
   │
JAR 교체
   │
systemctl restart
   │
서비스 재시작

개발자는 코드만 Push하면 되고, 이후 과정은 GitLab Runner가 자동으로 처리합니다.

---

배포 환경 구성

항목내용

형상관리	GitLab
애플리케이션	Spring Boot
운영체제	AlmaLinux 9
배포 도구	GitLab Runner
서비스 관리	systemd
배포 방식	Git Push 기반 자동 배포

---

GitLab Runner 설치 및 등록

먼저 서버에 GitLab Runner를 설치하고 등록합니다.

Runner 등록

sudo gitlab-runner register

등록 완료 후 상태 확인

sudo gitlab-runner verify

정상적으로 등록되면 Runner 정보를 확인할 수 있습니다.

---

GitLab Runner SSH 설정

자동 배포 시 Runner가 서버에 비밀번호 없이 접속할 수 있어야 합니다.

Runner 계정으로 전환

sudo su - gitlab-runner

SSH 키 생성

ssh-keygen -t rsa -b 4096

공개키 확인

cat ~/.ssh/id_rsa.pub

생성된 공개키를 배포 계정의 authorized_keys에 등록합니다.

ssh-copy-id deploy@localhost

접속 테스트

ssh deploy@localhost

비밀번호 입력 없이 접속된다면 설정이 완료된 것입니다.

---

Spring Boot 서비스 등록

systemd를 사용하면 Spring Boot 애플리케이션을 서비스 형태로 관리할 수 있습니다.

서비스 파일 생성

sudo vi /etc/systemd/system/vk.service

설정 예시

[Unit]
Description=Spring Boot Application
After=network.target

[Service]
User=deploy
Group=deploy

WorkingDirectory=/home/project

ExecStart=/usr/bin/java \
 -jar /home/project/app.jar \
 --server.port=8888

SuccessExitStatus=143

Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

서비스 등록

sudo systemctl daemon-reload
sudo systemctl enable vk
sudo systemctl start vk

상태 확인

sudo systemctl status vk

---

GitLab Runner sudo 권한 설정

배포 과정에서 서비스 재시작이 필요하므로 sudo 권한을 부여합니다.

sudo visudo

추가

deploy ALL=(root) NOPASSWD: /usr/bin/systemctl restart vk
deploy ALL=(root) NOPASSWD: /usr/bin/systemctl status vk

gitlab-runner ALL=(root) NOPASSWD: /usr/bin/systemctl restart vk
gitlab-runner ALL=(root) NOPASSWD: /usr/bin/systemctl status vk

권한 테스트

sudo -u gitlab-runner sudo systemctl status vk

정상적으로 서비스 정보가 출력되면 설정이 완료됩니다.

---

GitLab CI/CD 구성

프로젝트 루트에 .gitlab-ci.yml 파일을 생성합니다.

deploy-to-production:
  stage: deploy

  only:
    - master

  script:
    - echo "Deploy Start"

    - ssh deploy@localhost "
        cd /home/project/source &&
        git fetch origin &&
        git reset --hard origin/master &&
        chmod +x mvnw &&
        ./mvnw clean package -DskipTests &&
        cp -f target/app.jar ../app.jar &&
        sudo systemctl restart vk
      "

  tags:
    - deploy

설정이 완료되면 master 브랜치에 Push할 때마다 자동으로 배포가 수행됩니다.

---

git pull 대신 git reset --hard를 사용하는 이유

자동 배포 서버에서는 다음 명령을 자주 사용합니다.

git pull origin master

하지만 서버에 임시 수정 파일이 존재하거나 충돌이 발생하면 배포가 실패할 수 있습니다.

실무에서는 다음 방식을 더 많이 사용합니다.

git fetch origin
git reset --hard origin/master

장점

• GitLab 저장소 기준으로 항상 동기화
• 충돌 발생 가능성 최소화
• 배포 실패 확률 감소
• 운영 서버 상태 일관성 유지

자동 배포 서버는 수정 작업을 수행하는 공간이 아니라 배포 결과물만 유지하는 공간이기 때문에 매우 효과적인 방식입니다.

---

배포 테스트

코드 수정 후 Push를 진행합니다.

git add .
git commit -m "deploy test"
git push origin master

GitLab Runner가 자동으로 실행되며 배포가 시작됩니다.

서비스 상태 확인

sudo systemctl status vk

실시간 로그 확인

journalctl -u vk -f

---

최종 배포 흐름

git push origin master
           │
           ▼
      GitLab
           │
           ▼
    GitLab Runner
           │
           ▼
        SSH 접속
           │
           ▼
        git fetch
      git reset --hard
           │
           ▼
      Maven Build
           │
           ▼
        JAR 교체
           │
           ▼
     systemctl restart
           │
           ▼
     서비스 재시작 완료

---

운영 시 추가로 고려하면 좋은 사항

실제 운영 환경에서는 다음 항목도 함께 적용하는 것을 권장합니다.

배포 전 테스트 수행

./mvnw test

빌드 실패 시 배포 중단

GitLab CI 기본 기능을 활용하여 빌드 실패 시 자동으로 배포를 중단합니다.

백업 JAR 유지

cp app.jar app.jar.bak

배포 실패 시 즉시 롤백할 수 있습니다.

Slack 또는 Discord 알림 연동

배포 성공 및 실패 시 알림을 받을 수 있습니다.

---

마무리

GitLab Runner와 GitLab CI/CD를 활용하면 Spring Boot 프로젝트의 배포 과정을 완전히 자동화할 수 있습니다.

특히 AlmaLinux 9 환경에서는 systemd와 GitLab Runner 조합만으로도 안정적인 자동 배포 환경을 구축할 수 있으며, 운영 효율성과 배포 안정성을 크게 향상시킬 수 있습니다.

프로젝트 규모가 커질수록 수동 배포보다 자동 배포의 가치가 더욱 커지므로 초기 단계부터 CI/CD 환경을 구축해 두는 것을 권장합니다.

FAQ

GitLab Runner와 Jenkins 중 무엇이 좋을까요?

GitLab을 사용 중이라면 GitLab Runner가 훨씬 간단합니다. 별도의 Jenkins 서버를 운영할 필요가 없습니다.

git pull 대신 git reset --hard를 사용해도 괜찮을까요?

배포 서버라면 권장됩니다. 서버 파일 상태와 관계없이 저장소 기준으로 정확히 동기화할 수 있습니다.

systemctl restart 권한은 꼭 필요한가요?

배포 후 새로운 JAR 파일을 적용하기 위해 서비스 재시작이 필요하므로 권한 설정이 필요합니다.

테스트를 건너뛰어도 될까요?

개발 환경에서는 가능하지만 운영 환경에서는 테스트 수행 후 배포를 권장합니다.