우리 팀의 Gitflow 기반 개발 프로세스

이 글에서는 우리가 실제로 운영하고 있는 Gitflow와 그 위에서 기능 개발부터 배포까지 어떤 흐름으로 작업이 이루어지는지 정리하려고 한다.

CI/CD 구조 자체에 대한 설명은 이 글의 범위를 벗어나므로, 해당 내용은 별도의 글에서 다룰 예정이다.

기본 브랜치 구조

우리는 기본적으로 다음 세 개의 브랜치를 중심으로 운영한다.

dev → 개발 서버
stage → 스테이징 서버
main → production 서버 (실제 운영 서버)

각 브랜치는 다음과 같이 서버 환경과 1:1로 연결되어 있다.

dev 브랜치
- 개발 및 기능 검증용 서버
stage 브랜치
- 배포 전 최종 검증용 서버
main 브랜치
- 실제 운영 서버 (Production)

세 환경 모두 CI/CD 플로우와 연결되어 있어 브랜치에 변경이 반영되면 자동 빌드/배포가 수행된다.

다만, 안전을 위해 production(main) 환경은 자동 빌드까지만 수행되고 실제 배포는 개발자가 직접 진행해야 한다.

브랜치 네이밍 컨벤션

작업 성격에 따라 브랜치 이름을 명확히 구분한다.

기능 개발 : feature-…
핫픽스 : hotfix-…
QA 과정 중 수정 사항 : qa-feature-…, qa-hotfix-…

이름만 보아도 어떤 목적의 브랜치인지 바로 알 수 있도록 하는 것이 목표다.

브랜치 보호 규칙

우리는 기본 브랜치의 안정성을 매우 중요하게 생각한다.

그래서 다음과 같은 제한을 두고 있다.

dev, stage, main 브랜치
직접 push 불가능
모든 변경 사항은 Pull Request를 통해서만 반영

또한 PR 대상도 제한한다.

feature-* 브랜치
dev 브랜치로만 PR 가능
hotfix-* 브랜치
dev, stage 브랜치로만 PR 가능

이 구조 덕분에 의도치 않은 변경이 바로 상위 환경으로 올라가는 것을 막을 수 있다.

기능 개발 흐름

1. feature 브랜치에서 개발 시작

새로운 기능 개발은 항상 feature-* 브랜치에서 시작한다.

기능을 한 번에 다 만들고 합치는 것이 아니라, 적당한 크기의 작업 단위(chunk)로 나누어 개발한다.

생각보다 중간에 기획이 바뀌는 경우가 많고, 실제 개발해보면 디자인이나 인터렉션(Interaction)이 어색한 경우가 많아 바뀔 확률이 높다.
그래서 중간 중간에 계속 테스트하면서 변경 사항을 빠르게 반영해야 한다.

2. dev 브랜치로 merge 및 개발 서버에서 테스트

기능이 어느 정도 완성되면 feature-* 브랜치를 dev 브랜치로 merge한다.

Merge하면 CI/CD 플로우가 자동으로 실행되고 dev 서버에 기능이 배포된다.
그 후 실제 서버 환경에서 기능 동작 및 다른 기능과의 충돌 여부를 확인할 수 있다.

3. dev QA

Dev 서버에 배포되고 나면 통합 QA 과정을 거친다.

기능들이 서로 정상적으로 연동되는지, 예상치 못한 사이드 이펙트는 없는지, UI / UX 상의 문제는 없는지 확인한다.
눈에 불을 키고 허점을 찾는 작업이라 굉장히 스트레스를 많이 받는 과정이다…

이 과정에서 발견되는 수정 사항은 qa-feature-* 형태의 브랜치로 반영한다.
해당 브랜치는 dev 또는 stage로 다시 merge되며 QA 결과를 반영하는 용도로 사용된다.

4. stage 브랜치로 승격

dev 환경에서 QA가 완료되면 stage 브랜치로 merge한다.
stage 서버 역시 CI/CD를 통해 자동 반영된다.

이 단계에서는 실제 배포 환경과 최대한 동일한 조건에서 검증하는 것이 목적이다.

백엔드에서는

DB migration을 실제 배포처럼 수행
migration 과정에서 문제가 없는지 확인

프론트엔드에서는

실제 DB와 연동되는지
dev 환경에서 드러나지 않았던 이슈는 없는지 확인

5. 최종 QA 및 배포 결정

stage 서버에 모든 변경 사항이 반영되면 최종 QA를 진행한다.

이 단계에서 배포 가능 여부를 최종 결정하고 문제가 없다고 판단되면 프로젝트를 배포 가능 상태로 바꾼다.

6. Production 배포

main 브랜치에 merge가 완료되면 팀 전체가 함께 production 배포를 진행한다.

상황에 따라 사전 공지가 필요한 경우 미리 공지 후 서버를 내리고 안전하게 migration과 deployment를 진행한다.
무중단 배포가 가능한 경우에는 별도 공지 없이 바로 배포 진행한다.

배포 과정은 세세하게 항상 공유하고 확인한다.
예를 들어,

프론트 빌드 완료
백엔드 이미지 빌드 완료
백엔드 Helm 차트 이미지 태그 변경 완료
데이터베이스 마이그레이션 시작
데이터베이스 마이그레이션 중 (25%, 50%, 75% 때 공지하도록 함)
데이터베이스 마이그레이션 끝
helm upgrade 실행
백엔드 배포 완료
프론트 배포 완료
와 같은 과정을 세세하게 실시간으로 공유해서 배포 시 최대한 문제가 안 생기도록 하였다.

7. 배포 이후 Hotfix 처리 (없으면 좋음)

배포 이후 발생하는 수정 사항은 stage를 기준으로 hotfix 브랜치를 생성한다.

처리 흐름은 다음과 같다.

hotfix 브랜치 생성 (from stage)
수정 사항 반영
stage 브랜치로 merge
stage 서버에서 QA
재배포 (핫픽스)

이렇게 하면 production에 직접 수정이 들어가는 것을 방지할 수 있고, 항상 검증된 상태로 재배포가 가능하다.

이 Gitflow 구조의 핵심은 우리의 상황에 맞추어 적절한 정책을 구성하고 변경 사항이 어디로, 어떤 검증을 거쳐 올라가는지 모두가 명확하게 이해할 수 있는 흐름을 만드는 것이라고 생각한다.

Gitflow는 본래 개발의 편의성과 안정성을 높이기 위해 고안된 방식이기 때문에, 구조가 지나치게 복잡해지면 오히려 개발 과정을 어렵게 만들고 불필요한 비용을 발생시킬 수 있다.

그래서 우리는 개발 효율성을 높일 수 있는 규칙은 남기고, 팀의 규모와 서비스 특성에 맞게 구성하려고 했다.

중요한 것은 브랜치 이름이나 단계의 개수가 아니라,  잘 구성된 Gitflow를 따르다 보면, 이 개발 프로세스가 딱딱하게 지켜야 하는 약속이 아니라, 현재 개발이 어떤 상태인지, 다음에 무엇을 해야 하는지가 바로 보이는 편리한 과정이다.