[IT-방법] 컴포즈 파일 버전 자동화와 CI/CD 연동 – 반복적인 배포 작업을 줄이는 실무 기술

수동 배포의 늪에서 벗어나야 하는 이유

금요일 퇴근 직전, 평소처럼 도커 컴포즈로 서비스를 배포하려는데 무언가 이상해요. 분명히 코드는 수정했는데, 서버에는 예전 버전의 컨테이너가 그대로 돌아가고 있어요. 원인을 찾아보니 docker-compose.yml 파일의 버전 필드나 이미지 태그를 수정하는 것을 깜빡했네요. 이런 실수는 단순한 건망증이 아니라, 반복적인 수동 작업이 만들어낸 구조적인 문제입니다.

서비스 규모가 커지고 컨테이너 개수가 늘어날수록 사람이 직접 파일을 열어 숫자를 고치는 방식은 한계에 부딪혀요. 한 번의 실수가 전체 서비스 장애로 이어지기도 하고, 배포할 때마다 사람이 개입해야 하니 자동화된 파이프라인의 의미가 퇴색되죠. 컴포즈 파일 버전 자동화는 단순히 편해지기 위한 도구가 아니라, 배포의 안정성을 확보하기 위한 생존 전략이에요.

이제는 깃(Git)에 코드를 올리기만 하면, 시스템이 알아서 버전 번호를 계산하고 컴포즈 파일의 내용을 업데이트한 뒤 배포까지 마쳐야 해요. 사람이 개입하는 지점을 최소화할수록 배포 속도는 빨라지고 사고 확률은 급격히 낮아져요. 이 글에서는 반복적인 배포 작업에 지친 개발자를 위해, 컴포즈 파일 버전을 똑똑하게 관리하고 이를 CI/CD 환경에 녹여내는 구체적인 방법을 다뤄요.

오늘 함께 살펴볼 내용은 다음과 같아요.

• 수동 배포 시 발생하는 주요 문제점과 자동화의 필요성
• 버전 자동화를 위해 준비해야 할 도구와 환경
• 스크립트와 CI 도구를 이용한 단계별 자동화 구현 방법
• 배포 과정에서 흔히 겪는 오류와 해결책
• 안정적인 운영을 위한 롤백 전략

자동화 환경 구축을 위한 사전 준비

무작정 스크립트를 짜기 전에, 우리 팀의 운영 환경이 자동화를 받아들일 준비가 되었는지 확인해야 해요. 자동화는 마법이 아니라, 잘 짜인 규칙과 도구의 조합이기 때문이에요. 무턱대고 도입했다가는 오히려 자동화된 오류가 더 빠르게 퍼지는 재앙을 맞이할 수도 있어요.

도구 선택과 환경 구성

가장 먼저 결정해야 할 것은 버전 관리 도구와 YAML 편집 도구예요. 단순히 텍스트를 치환하는 방식은 위험해요. YAML 파일은 구조가 중요한데, 단순한 텍스트 치환은 들여쓰기를 망가뜨려 파일을 깨뜨릴 수 있거든요. 그래서 구조를 이해하는 전문 도구가 필요해요.

자동화 방식 비교하기

프로젝트의 복잡도에 따라 적절한 자동화 수준을 선택해야 해요. 모든 것을 한 번에 바꾸려 하기보다, 현재 상황에 맞는 단계를 밟아가는 것이 현명해요.

핵심 체크리스트

자동화를 시작하기 전, 아래 조건들이 충족되었는지 반드시 점검해 보세요. 이 조건들이 갖춰지지 않으면 자동화는 오히려 관리 비용을 늘리는 짐이 될 뿐이에요.

• Git 태그 전략: Semantic Versioning(예: v1.2.3) 규칙이 확립되어 있는가?
• 환경 변수 관리: 버전 정보가 .env 파일이나 환경 변수로 주입될 준비가 되었는가?
• 도구 설치: CI 서버(Runner)에 yq나 jq 같은 명령행 도구가 설치 가능한 환경인가?
• 권한 체계: CI 도구가 컴포즈 파일을 수정하고 서버에 원격 명령을 내릴 권한이 있는가?

모든 준비가 끝났다면, 이제 실제로 파일을 어떻게 조작하고 배포 파이프라인에 태울지 구체적인 단계를 밟아볼까요?

컴포즈 파일 버전 자동화 실전 단계

이제 본격적으로 컴포즈 파일 버전 자동화를 구현해 봐요. 단순히 텍스트를 바꾸는 수준을 넘어, 실제 운영 환경에서 견고하게 작동하는 시스템을 만드는 과정이에요. 총 5단계의 과정을 통해 체계적으로 구축해 볼게요.

STEP 1. 버전 정보의 소스 정하기

자동화를 하려면 가장 먼저 “버전 정보가 어디서 오는가?”를 결정해야 해요. 버전 정보의 원천(Source of Truth)이 명확하지 않으면 자동화 프로세스가 꼬이게 돼요. 보통 다음 세 가지 중 하나를 선택해요.

• Git Tag: 가장 권장하는 방식이에요. 개발자가 `git tag v1.0.5`를 생성하면, 이 태그 값이 컴포즈 파일의 버전이 돼요.
• CI Build Number: Jenkins나 GitHub Actions에서 생성하는 고유 번호를 사용해요. 버전 관리가 엄격하지 않은 내부 테스트용 환경에 적합해요.
• Timestamp: 배포 시점의 시간을 사용해요. 버전의 의미보다는 “언제 배포되었는가”가 더 중요할 때 유용해요.

실무에서는 Git Tag를 사용하는 것이 가장 좋아요. 코드가 어떤 버전인지와 배포된 컨테이너의 버전이 일치하기 때문에 추적 관리가 매우 쉽기 때문이에요.

STEP 2. yq를 활용한 YAML 구조적 수정

이제 결정한 버전 정보를 컴포즈 파일에 써넣어야 해요. 여기서 많은 개발자가 실수하는 것이 `sed` 명령어를 사용하는 거예요. `sed`는 텍스트를 바꾸는 데는 훌륭하지만, YAML의 계층 구조를 이해하지 못해요. 예를 들어, 여러 서비스에서 공통으로 쓰는 `version` 필드가 있을 때 `sed`는 엉뚱한 곳을 바꿀 위험이 커요.

가장 안전한 방법은 yq를 사용하는 거예요. `yq`는 YAML 전용 명령행 도구로, 파일의 구조를 유지하면서 특정 필드값만 정확하게 바꿀 수 있어요.

STEP 3. CI/CD 파이프라인 설계하기

준비된 스크립트를 실제 배포 흐름에 녹여내야 해요. GitHub Actions를 기준으로 하는 표준적인 워크플로우 시나리오를 살펴볼게요. 이 과정은 사람이 직접 명령어를 치는 대신, 시스템이 흐름을 주도하게 만들어요.

1. 트리거(Trigger): 개발자가 `main` 브랜치에 코드를 병합하거나 새로운 `tag`를 푸시할 때 파이프라인이 시작돼요.
2. 체크아웃 및 도구 설치: 소스 코드를 가져오고, `yq`와 같은 필요한 도구들을 준비해요.
3. 버전 추출: 현재의 Git 태그 값을 변수에 저장해요. (예: `TAG_NAME=$(git describe –tags)`)
4. 파일 업데이트: 추출한 태그 값을 `yq`를 이용해 `docker-compose.yml`의 `version` 필드와 각 서비스의 `image` 태그에 주입해요.
5. 이미지 빌드 및 푸시: 업데이트된 태그를 기반으로 도커 이미지를 빌드하고 레지스트리에 업로드해요.
6. 원격 배포: SSH 등을 통해 서버에 접속하여 `docker compose up -d`를 실행해요.

STEP 4. 환경 변수(.env) 활용 전략

컴포즈 파일을 직접 수정하는 것이 부담스럽다면, 환경 변수 방식을 병행하는 것도 아주 좋은 전략이에요. 컴포즈 파일에는 변수명만 적어두고, 실제 값은 `.env` 파일에서 관리하는 거죠.

예를 들어, `docker-compose.yml` 파일 내용을 다음과 같이 구성할 수 있어요.

services:
  web:
    image: my-app:${APP_VERSION}
    labels:
      version: "${APP_VERSION}"

이렇게 해두면, 자동화 스크립트는 컴포즈 파일을 건드릴 필요 없이 `.env` 파일의 `APP_VERSION` 값만 한 줄 바꾸면 돼요. 파일 구조를 건드리지 않으니 훨씬 안전하고 관리가 쉬워져요. 실무에서는 이 방식을 가장 선호해요.

STEP 5. 배포 전 검증(Validation) 단계 추가

자동화가 끝났다고 바로 배포 버튼을 누르면 안 돼요. 자동화 스크립트가 실수로 파일을 망가뜨렸을 수도 있으니까요. 배포 직전에 반드시 검증 단계를 넣어야 해요.

가장 좋은 명령은 `docker compose config예요. 이 명령어를 실행하면 현재 작성된 컴포즈 파일이 문법적으로 올바른지, 변수 치환은 제대로 되었는지 확인하고 최종적으로 해석된 내용을 화면에 보여줘요. 이 과정에서 에러가 발생한다면 파이프라인을 즉시 중단시키고 배포를 막아야 해요. 검증 없는 자동화는 사고를 자동화하는 것과 같아요.