1. 깃 협업 Forking Workflow
Forking Workflow(포킹 워크플로)는 각 팀원이 원본 저장소를 Fork(포크)하여 자신의 저장소에서 작업하고, Pull Request(풀 리퀘스트)로 원본에 병합하는 Git 협업 방식이다.
저장소는 3종류이다:
| 이름 | 역할 | 관리자 |
|---|---|---|
| upstream(업스트림) | 최종 통합 저장소. PR이 들어오고 배포 서버에 연결된다. | 팀장 |
| origin(내 fork) | 자유롭게 작업하는 복사본 | 각자 |
| local(로컬) | 실제로 코드를 수정하는 내 PC 폴더 | 각자 |
브랜치는 2개이다: main(배포용, 직접 작업 금지) / dev(개발용, PR 대상)
1.1. 팀장: 원본 저장소 세팅
팀장만 1회 수행한다.
1. GitHub에서 저장소를 만든다.
- New repository → Public →
.gitignore: Node → Create repository
2. Gemini CLI를 열고 프로젝트 폴더로 이동한 뒤 초기화한다.
이 폴더를 git 저장소로 초기화하고 GitHub 저장소에 연결해줘.
주소는 https://github.com/팀장계정/저장소명.git 이야.
커밋 후 main에 push해줘.
3. dev 브랜치를 만들고 push한다.
dev 브랜치를 만들어서 origin에 push해줘.
4. GitHub에서 기본 브랜치를 dev로 변경한다.
- 저장소 → Settings → Branches → Default branch →
dev선택 → Update
1.2. 팀원 각자: 내 환경 세팅
팀원 각자 1회 수행한다.
1. 팀장 저장소 페이지에서 Fork를 클릭한다.
github.com/팀장계정/저장소명→ Fork → Create fork
2. 내 fork를 로컬에 복제한다.
git clone https://github.com/내계정/저장소명.git
cd 저장소명
3. 원본 저장소를 upstream으로 등록한다.
git remote add upstream https://github.com/팀장계정/저장소명.git
4. 제대로 등록됐는지 확인한다.
git remote -v
origin https://github.com/내계정/저장소명.git (fetch)
origin https://github.com/내계정/저장소명.git (push)
upstream https://github.com/팀장계정/저장소명.git (fetch)
upstream https://github.com/팀장계정/저장소명.git (push)
origin과 upstream 2개가 보이면 성공이다.
5. dev 브랜치로 이동한다.
git checkout dev
1.3. 팀장: GitHub Actions 세팅
팀장만 1회 수행한다. PR이 올라오면 자동으로 빌드를 검증한다.
1. Gemini CLI에서 워크플로 폴더와 파일을 만든다.
프로젝트 루트에 .github/workflows/build.yml 파일을 만들어줘.
내용은 아래 코드야.
아래 내용을 함께 전달한다: build.yml 코드
2. 커밋 후 push한다.
커밋해줘. 메시지는 feat: GitHub Actions 빌드 체크 추가. main에 push해줘.
3. GitHub 원본 저장소 → Actions 탭을 열어 워크플로우가 등록됐는지 확인한다.
1.4. 매일 반복: 작업 흐름
1.4.1. 작업 전- upstream 동기화
작업 전 반드시 원본의 최신 내용을 가져온다.
upstream의 최신 dev를 내 로컬로 가져와줘.
git fetch upstream
git merge upstream/dev
1.4.2. 코드 수정 후 — 커밋
담당 파일 수정이 끝나면 바로 커밋한다. 쌓아두지 않는다.
변경된 파일 확인해줘.
git status
커밋해줘. 메시지는 feat: 홈 페이지 구현
git add .
git commit -m "feat: 홈 페이지 구현"
커밋 메시지 접두어 규칙
| 접두어 | 의미 | 예시 |
|---|---|---|
feat: |
새로 만들었다 | feat: 홈 페이지 구현 |
fix: |
고쳤다/바꿨다 | fix: 검색 버그 수정 |
docs: |
문서 작성 | docs: README 작성 |
1.4.3. 커밋 후 — 내 fork에 push
내 fork에 올려줘.
git push origin dev
1.5. PR 올리기
1.6. 팀장: PR 확인 + Merge
1.7. 빌드 에러 수정하기 (팀원)
빌드가 실패하면 아래 순서로 수정한다.
1. PR 페이지 하단의 Details를 클릭한다.
2. 빨간색 줄에서 에러 메시지를 찾아 복사한다.
3. Gemini CLI에 붙여넣는다.
이 에러 고쳐줘:
(에러 메시지 붙여넣기)
4. 수정 후 커밋하고 push한다. PR이 자동으로 업데이트된다.
커밋해줘. 메시지는 fix: 빌드 에러 수정. 내 fork에 push해줘.
자주 발생하는 빌드 에러
| 에러 | 원인 | Gemini CLI 입력 |
|---|---|---|
Module not found: Can't resolve './Home' |
파일명 오타 또는 import 경로 오류 | 이 import 에러 고쳐줘. |
'xxx' is not defined |
import 누락 | xxx가 정의되지 않았다는 에러야. import 추가해줘. |
Unexpected token |
문법 오류 (괄호 빠짐 등) | 문법 에러 고쳐줘. |
Cannot find package 'xxx' |
패키지 미설치 | xxx 패키지 설치해줘. |
VITE_TMDB_API_KEY is not defined |
.env 없음 | GitHub Secrets에 등록한다. |
API 키 빌드 에러 — GitHub Secrets 등록
GitHub Actions는 .env 파일을 읽지 못한다(.gitignore에 등록했으므로). API 키는 GitHub Secrets에 등록한다.
- upstream 저장소 → Settings → Secrets and variables → Actions
- New repository secret → Name:
VITE_TMDB_API_KEY→ Secret: 실제 키 값 입력 build.yml에 아래 블록을 추가한다.
- run: npm run build
env:
VITE_TMDB_API_KEY: ${{ secrets.VITE_TMDB_API_KEY }}
1.8. 충돌이 발생했을 때
1. upstream을 동기화한다.
upstream 최신 dev를 내 로컬로 가져와줘.
2. Gemini에게 충돌 해결을 요청한다.
충돌이 났어. 어떤 파일인지 확인하고 해결 방법 알려줘.
3. 혼자 해결이 어려우면 카카오톡에 에러 화면을 공유하고 Google Meet로 팀원과 함께 결정한다.
4. 해결 후 커밋하고 push한다.
충돌 해결했어. 커밋하고 내 fork에 push해줘.
1.9. 담당 파일 분리 (충돌 예방)
| 담당 | 작업 영역 | 파일 예시 |
|---|---|---|
| A | 디자인 + 검색/상세 | pages/Search.jsx, pages/Detail.jsx |
| B | 홈 + 찜목록 + 공통 | pages/Home.jsx, pages/Wishlist.jsx, components/ |
| C | 챗봇 + 백엔드 | pages/Chatbot.jsx, backend/ 전체 |
공통 파일(App.jsx, index.css, tmdb.js)을 수정할 때는 카카오톡으로 먼저 알린다.
1.10. 절대 하지 말 것
– upstream에 직접 push한다. (팀장의 초기 세팅만 예외)
main브랜치에서 직접 작업한다..env파일을 GitHub에 올린다.- 다른 사람 담당 파일을 수정한다.
- push 전 upstream 동기화를 건너뛴다.
- 커밋을 쌓아두었다가 한꺼번에 올린다.