현대적인 서버 운영에서는 코드를 변경할 때마다 직접 서버에 접속해서 배포하지 않습니다.

GitHub Actions 같은 CI/CD 도구를 사용하면 코드 변경부터 Docker Image 생성, 서버 배포까지 자동화할 수 있습니다.

기존 방식:

개발자

↓

서버 접속

↓

Git Pull

↓

Docker Build

↓

Container 재시작

문제:

반복 작업 증가
배포 실수 발생
작업 기록 부족
여러 서버 관리 어려움

자동화 방식:

Git Push

↓

GitHub Actions 실행

↓

Docker Build

↓

Image Push

↓

Server Deploy

↓

서비스 확인

Docker Compose와 GitHub Actions를 연결하면 안정적인 Production 배포 환경을 만들 수 있습니다.

이번 글에서는 GitHub Actions 기본 구조부터 Docker Image Build, Registry Push, SSH 배포, Docker Compose 자동 실행까지 실제 서버 운영 구조 기준으로 알아보겠습니다.

GitHub Actions란 무엇인가?

GitHub Actions는 GitHub에서 제공하는 자동화 플랫폼입니다.

사용 가능한 작업:

Build
Test
Deploy
Script 실행
Server 관리

기본 구조:

Repository

↓

Workflow

↓

Runner

↓

Command 실행

Workflow 파일:

.github/

└── workflows/

    └── deploy.yml

GitHub Actions는 YAML 파일로 동작을 정의합니다.

Docker Compose GitHub Actions 구조

Production 자동 배포 구조:

Developer

↓

Git Push

↓

GitHub Actions

↓

Docker Build

↓

Docker Registry

↓

Production Server

↓

Docker Compose

각 역할:

GitHub:

코드 저장

Actions:

자동 작업 실행

Docker:

Image 생성

Compose:

Container 배포

GitHub Actions Workflow 기본 구조

파일 생성:

.github/workflows/deploy.yml

기본 형태:

name: Deploy

on:

  push:

    branches:

      - main


jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - name: Deploy

        run: echo "Deploy"

동작:

main Push

↓

Workflow 실행

↓

명령 실행

Docker Image Build 자동화

GitHub Actions에서 Docker Build를 실행할 수 있습니다.

예:

- name: Docker Build

  run: docker build -t my-app .

과정:

Source Code

↓

Dockerfile

↓

Docker Image

Docker Compose Image Push 자동화

Build한 Image를 Registry에 저장합니다.

구조:

GitHub Actions

↓

Docker Build

↓

Docker Hub

↓

Production Server

- name: Login Docker Hub

  uses: docker/login-action@v3

Push:

- name: Push Image

  run: docker push my-app:latest

GitHub Actions Secret 설정

배포 정보는 GitHub Secret으로 관리합니다.

관리 대상:

Docker Password
Server SSH Key
Server IP
Database Password

위치:

Repository

↓

Settings

↓

Secrets and variables

↓

Actions

구조:

GitHub Secret

↓

Workflow

↓

Deploy

Docker Compose SSH 자동 배포

Production 서버에 접속하여 Compose를 실행합니다.

구조:

GitHub Actions

↓

SSH 연결

↓

Server

↓

docker compose up -d

예:

- name: Deploy Server

  uses: appleboy/ssh-action@v1

  with:

    host: ${{ secrets.SERVER_HOST }}

    username: ubuntu

    key: ${{ secrets.SSH_KEY }}

    script:

      docker compose pull

      docker compose up -d

동작:

새 Image 다운로드

↓

Container 업데이트

↓

서비스 재시작

Docker Compose Production Deploy Workflow 예제

전체 흐름:

name: Production Deploy

on:

  push:

    branches:

      - main


jobs:

  deploy:

    runs-on: ubuntu-latest


    steps:

      - uses: actions/checkout@v4


      - name: Build Image

        run: docker build -t app .


      - name: Deploy

        run: docker compose up -d

실제 운영에서는 Registry와 SSH 배포를 추가합니다.

Docker Compose 배포 검증 추가

자동 배포 후 상태 확인이 필요합니다.

확인:

docker compose ps

Healthcheck:

healthy

↓

배포 성공

실패:

unhealthy

↓

Rollback

Docker Compose Rollback 자동화

새로운 배포가 실패하면 이전 Version으로 돌아갑니다.

구조:

Version 2.0

↓

오류 발생

↓

Version 1.9 복구

방법:

Image Tag 사용:

app:2.0

app:1.9

배포:

image: app:1.9

Docker Compose Branch 기반 배포

실제 운영에서는 Branch별 환경을 나눕니다.

구조:

develop

↓

Development Server


main

↓

Production Server

Workflow:

branches:

  - main

의미:

main Push 시 Production 배포

Docker Compose CI/CD 보안 관리

중요:

SSH Key:

GitHub Secret 저장

Password:

Secret 사용

Server 접근:

IP 제한

Image:

Version 관리

구조:

Secret

↓

GitHub Actions

↓

Server

Docker Compose GitHub Actions 장애 대응

Workflow 실패

확인:

Actions

↓

Failed Job

↓

Log 확인

확인:

Docker Build 오류
Secret 오류
SSH 오류

SSH 연결 실패

확인:

Host
Username
Private Key
Firewall

Deploy 후 서비스 오류

확인:

docker compose ps

docker compose logs

Docker Compose GitHub Actions Best Practice

자주 묻는 질문

GitHub Actions로 Docker Compose 배포가 가능한가요?

가능합니다.

실제 Production 환경에서도 많이 사용하는 방식입니다.

서버에 Git을 설치해야 하나요?

Registry 기반 배포라면 필요하지 않습니다.

Docker Image는 어디에 저장하나요?

Docker Hub, GitHub Container Registry, Private Registry 등을 사용할 수 있습니다.

자동 배포하면 위험하지 않나요?

Test, Healthcheck, Rollback 구조를 함께 구성하면 안정적으로 운영할 수 있습니다.

마무리

Docker Compose GitHub Actions 연동은 서버 운영 자동화를 위한 핵심 기술입니다.

최종 CI/CD 구조:

Git Push

↓

GitHub Actions

↓

Docker Build

↓

Image Registry

↓

Production Server

↓

Docker Compose Deploy

↓

Health Check

이 구조를 구축하면 개발자가 코드를 수정한 순간부터 Production 배포까지 자동화할 수 있습니다.

다음 글에서는 안정적인 배포 품질을 높이기 위한 Docker Compose 테스트 자동화 방법을 알아보겠습니다.

Docker Compose GitHub Actions 연동 완벽 가이드! Git Push부터 자동 배포 Pipeline 구축하기