Git 브랜치, 왜? 그리고 어떻게? (Cloudflare 배포 워크플로우)

1. “왜 브랜치를 고민하게 되었는가?”

처음에는 git push를 main 브랜치에 직접 했다. 코드를 저장하는 단순한 백업 용도였다.

하지만 Cloudflare Pages에 main 브랜치를 연결하자, 상황이 완전히 달라졌다.

” main 브랜치에 push = 즉시 실제 사이트 배포 ”

이것은 엄청난 편리함인 동시에 엄청난 위험이었다. “폰트가 적용 안 되네?”, “헤더가 깨졌네?” 같은 사소한 수정조차 main에 푸시하는 순간, 전 세계 방문자에게 깨진 사이트가 보일 수 있게 된 것이다.

‘작업을 안전하게 완료할 때까지 배포를 막고 싶다’는 생각이 들었고, Gemini는 그 해답으로 **‘브랜치(Branch)‘**를 제안했다.

2. 핵심 철학: `main`과 `feature`의 분리

우리가 정한 워크플로우의 핵심은 딱 두 가지 브랜치 종류만 기억하는 것이다.

main 브랜치:
- “최종 완성본”, “배포용 원본”, “실제 사이트”
- 항상 완벽하게 작동하는 상태여야 한다.
- 절대 여기서 직접 작업하거나 커밋하지 않는다. (매우 중요)
feature 브랜치 (예: feature/header-footer):
- “작업용 초안”, “실험실”, “안전한 샌드박스”
- 여기서 마음껏 코드를 수정하고, 100번을 push해도 main에 영향을 주지 않는다.
- 깨져도 나만 본다.

Cloudflare의 역할: Cloudflare는 main 브랜치만 “실제 사이트”로 배포하고, feature 브랜치에 대한 push는 “미리보기(Preview) URL”로만 만들어준다.

3. 나의 ‘안전한’ 배포 워크플로우 (명령어)

이 과정을 까먹지 않기 위해, 새 기능을 추가할 때의 전체 흐름을 기록한다.

1단계: 새 작업 시작 (샌드박스 만들기)

main은 항상 깨끗하게 두고, 새로운 ‘기능’ 브랜치를 만든다. (예: about 페이지 만들기)

# 1. 항상 main 브랜치에서 시작한다. (최신 원본 가져오기)
git checkout main
git pull origin main

# 2. 'feature/about-page'라는 이름의 새 브랜치를 만들고, 그 브랜치로 이동
git checkout -b feature/about-page

2단계: 자유롭게 작업 및 테스트

feature/about-page 브랜치에서 about.astro 파일을 만들고, Header.astro를 수정하는 등 모든 작업을 한다.

npm run dev로 로컬에서 테스트하며 자유롭게 코드를 짠다.

3단계: 작업 내용 ‘중간 저장’ (샌드박스에 푸시)

작업한 내용을 GitHub에 ‘초안’으로 저장한다.

# 1. 변경된 파일들을 추가
git add .

# 2. "feat(기능): about 페이지 추가" 같은 메시지로 커밋
git commit -m "feat: add about page and update header"

# 3. 'main'이 아닌! 'feature/about-page' 브랜치로 푸시
git push origin feature/about-page

이점: 이 push는 절대 실제 사이트를 망가뜨리지 않는다. Cloudflare가 이 브랜치만을 위한 “임시 미리보기 URL”을 만들어줘서, 실제 배포 전에 확인까지 할 수 있다.

4단계: ‘배포’ 결정 (main으로 병합)

‘미리보기 URL’과 로컬 테스트를 통해 about 페이지가 완벽하다고 판단되면, “이 초안을 최종본으로 승격”시킨다.

# 1. 다시 'main' 브랜치로 돌아온다.
git checkout main

# 2. 'feature/about-page' 브랜치에서 작업한 모든 내용을 'main'으로 가져와 합친다.
git merge feature/about-page

5단계: 실제 배포 (Cloudflare 트리거)

이제 ‘main’ 브랜치에 about 페이지의 코드가 합쳐졌다. 이 최종본을 GitHub main에 올리면, Cloudflare가 배포를 시작한다.

# 'main' 브랜치를 GitHub로 푸시한다.
git push origin main

1~2분 뒤, 실제 사이트에 about 페이지가 성공적으로 적용된다.

4. 결론

push (저장)와 deploy (배포)를 분리했다.

git push origin feature/my-work = 스트레스 없는 안전한 ‘초안 저장’
git push origin main = 내가 결정한 ‘실제 사이트 배포’ 버튼

이것이 내가 깨진 사이트를 두려워하지 않고 “AI 코딩 일기장”을 가꿀 수 있는 방법이다.