Docker + Nginx 기반 Blue-Green 배포 구축 (3) — GitHub Actions CI/CD와 자동 배포 스크립트 구축

들어가며

이전 글에서는 Docker 이미지를 GitHub Container Registry(GHCR)에 업로드하고
Blue-Green 컨테이너 환경을 구성하여 수동 배포 방식으로 Blue-Green 전환을 검증했다.

이 과정에서 다음과 같은 작업을 완료했다.

• Dockerfile 작성 및 이미지 빌드
• GitHub Container Registry(GHCR) 사용
• 서버에서 이미지 Pull 테스트
• Blue / Green 컨테이너 환경 구성
• NGINX Reverse Proxy 트래픽 전환 테스트

즉 Blue-Green 배포가 실제로 동작하는 환경은 이미 구축된 상태였다.

하지만 실제 운영 환경에서는 다음과 같은 문제가 남아 있다.

코드 변경
↓
Docker 이미지 빌드
↓
이미지 Push
↓
서버 접속
↓
컨테이너 실행
↓
NGINX 전환

 

이 과정을 모두 수동으로 실행해야 한다는 점이다.

따라서 이번 글에서는 이 과정을 자동화하여 다음과 같은 완전한 자동 배포 파이프라인을 구축한다.

GitHub Push
↓
GitHub Actions
↓
Docker Image Build
↓
GHCR Push
↓
Server Deploy Script
↓
Blue-Green 배포
↓
NGINX 자동 전환

---

자동 배포 구조 설계

자동 배포의 핵심 구성 요소는 다음과 같다.

1️⃣ GitHub Actions CI/CD
2️⃣ Docker Image Version 관리
3️⃣ 서버 배포 스크립트 (deploy.sh)
4️⃣ Health Check 자동화
5️⃣ NGINX 트래픽 전환 자동화

전체 구조는 다음과 같다.

Developer
│
│ git push
▼
GitHub Repository
│
▼
GitHub Actions
│
│ Docker Build
│
▼
GitHub Container Registry (GHCR)
│
│ docker pull
▼
Server
│
│ deploy.sh
▼
Blue / Green Container
│
▼
NGINX
│
▼
Client

 

즉 코드가 Push되면 자동으로 서버까지 배포되는 구조를 만드는 것이 목표다.

---

Docker 이미지 버전 전략

초기에는 Docker 이미지를 다음과 같이 latest 태그로만 관리했다.

ghcr.io/kbo-note/kbo-note-feed-service:latest

 

하지만 이 방식에는 문제가 있다.

새로운 배포가 latest를 덮어씀
↓
기존 컨테이너 재시작 시 다른 코드 실행 가능
↓
버전 추적 어려움

 

이를 해결하기 위해 Commit 기반 이미지 태그 전략을 적용했다.

GitHub Actions에서 Docker 이미지를 빌드할 때 다음과 같이 두 개의 태그를 동시에 생성한다.

docker build \
-t ghcr.io/kbo-note/kbo-note-feed-service:${{ github.sha }} \
-t ghcr.io/kbo-note/kbo-note-feed-service:latest .

 

이렇게 하면 Registry에는 다음과 같은 형태로 이미지가 저장된다.

kbo-note-feed-service
├ latest
├ 3f91c2a
├ 8ad21f3
└ b71d9c1

 

이 전략의 장점은 다음과 같다.

• 배포 버전 추적 가능
• 특정 버전 롤백 가능
• 이미지 변경으로 인한 코드 꼬임 방지

---

GitHub Actions CI/CD 구축

이제 GitHub Actions Workflow를 작성한다.

Workflow 파일 위치

.github/workflows/deploy.yml

 

핵심 Workflow는 다음과 같다.

name: Feed Service CI/CD

on:
push:
branches:
- main

permissions:
contents: read
packages: write

jobs:
deploy:

runs-on: ubuntu-latest

steps:

- name: Checkout
uses: actions/checkout@v4

- name: Login to GHCR
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

- name: Build Docker Image
run: |
docker build \
-t ghcr.io/kbo-note/kbo-note-feed-service:${{ github.sha }} \
-t ghcr.io/kbo-note/kbo-note-feed-service:latest .

- name: Push Docker Image
run: |
docker push ghcr.io/kbo-note/kbo-note-feed-service:${{ github.sha }}
docker push ghcr.io/kbo-note/kbo-note-feed-service:latest

- name: Deploy to Server
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USERNAME }}
password: ${{ secrets.SERVER_PASSWORD }}
port: 22
script: |
cd ~/kbo-feed-service/deploy
./deploy.sh ${{ github.sha }}

 

이 Workflow는 다음과 같은 작업을 수행한다.

코드 Checkout
↓
Docker 이미지 빌드
↓
GHCR Push
↓
SSH 서버 접속
↓
deploy.sh 실행

---

Blue-Green 자동 배포 스크립트 작성

다음으로 서버에서 실행되는 자동 배포 스크립트를 작성한다.

파일 위치

~/kbo-feed-service/deploy/deploy.sh

 

스크립트의 주요 역할은 다음과 같다.

현재 실행 중인 컨테이너 확인
↓
반대 환경 컨테이너 실행
↓
Health Check 수행
↓
NGINX 트래픽 전환
↓
기존 컨테이너 종료

 

예를 들어 현재 상태가 다음과 같다면

feed-blue → 8081

 

배포 시 다음과 같이 진행된다.

새 버전 → feed-green (8082)
↓
Health Check
↓
NGINX 전환
↓
feed-blue 종료

---

Health Check 자동화

새 컨테이너가 정상적으로 실행되었는지 확인하기 위해
Health Check 로직을 추가했다.

Feed Server에는 다음과 같은 health endpoint가 존재한다.

/api/v1/feeds/health

 

응답 예시

{
"service": "kbo-feed-service",
"status": "UP"
}

 

deploy.sh에서는 이 값을 확인하여 서비스 상태를 검증한다.

curl http://localhost:$PORT/api/v1/feeds/health

 

만약 Health Check가 실패하면

1. NGINX 전환 중단
2. 새 컨테이너 제거
3. 배포 실패 처리

 

하도록 구성했다.

---

배포 로그 기록

추가로 배포 히스토리를 확인할 수 있도록 배포 로그 기록 기능도 추가했다.

echo "$(date '+%Y-%m-%d %H:%M:%S') deploy $IMAGE_TAG" >> deploy.log

 

이렇게 하면 서버에서 다음과 같이 배포 기록을 확인할 수 있다.

2026-03-15 01:12 deploy 3f91c2a
2026-03-15 01:40 deploy 8ad21f3

---

자동 배포 동작 과정

이제 실제 배포 흐름은 다음과 같다.

git push
↓
GitHub Actions 실행
↓
Docker Image Build
↓
GHCR Push
↓
SSH 서버 접속
↓
deploy.sh 실행
↓
Blue-Green 배포
↓
NGINX 트래픽 전환

 

즉 개발자는 단순히 다음 명령만 실행하면 된다.

git push

 

그러면 자동으로 서버까지 배포된다.

---

실제 배포 검증

자동 배포가 정상적으로 동작하는지 확인하기 위해
테스트 커밋을 Push하여 배포를 실행했다.

GitHub Actions 로그에서는 다음과 같은 단계가 확인된다.

Checkout
Login to GHCR
Build Docker Image
Push Docker Image
Deploy to Server

 

서버에서도 컨테이너가 정상적으로 전환되는 것을 확인했다.

docker ps

 

컨테이너는 다음과 같이 번갈아 실행된다.

feed-blue
feed-green

 

이로써 GitHub Push → 자동 Blue-Green 배포가 정상적으로 동작하는 것을 확인했다.

---

현재까지 진행 상황

지금까지 진행한 작업을 정리하면 다음과 같다.

✔ Docker 기반 서비스 환경 구축
✔ GitHub Container Registry 사용
✔ Blue-Green 배포 환경 구성
✔ NGINX Reverse Proxy 설정
✔ 수동 Blue-Green 배포 검증
✔ GitHub Actions CI/CD 구축
✔ Blue-Green 자동 배포 스크립트 작성
✔ Health Check 자동화
✔ 자동 배포 검증 완료

---

마무리

이번 글에서는 GitHub Actions를 이용해 Blue-Green 자동 배포 환경을 구축하는 과정을 정리했다.

특히 다음 세 가지가 핵심이었다.

• GitHub Actions 기반 CI/CD 구축
• Commit 기반 Docker Image 버전 관리
• Blue-Green 자동 배포 스크립트 구현

이 구조를 통해 코드 Push만으로 서버 배포가 자동으로 이루어지는 환경을 구축할 수 있었다.

앞으로 서비스 규모가 커지더라도
이 배포 구조를 기반으로 안정적인 배포를 유지할 수 있을 것으로 기대한다

---