신규 프로젝트를 시작할 때 GitHub 저장소를 어떻게 구성하고 관리해야 할지 고민되시나요? 이 글에서는 Organization 활용법, 저장소 생성 방법, VSCode 연동까지 실무에서 바로 쓸 수 있는 내용을 정리했습니다.
GitHub 구조 이해하기
Organization (또는 개인 계정)
└── Repository (프로젝트)
└── Branch (작업 공간)
GitHub은 2단계 구조입니다. 폴더처럼 3단계 이상 중첩할 수 없어요. 프로젝트가 많아지면 Organization으로 그룹화하는 게 유일한 방법입니다.
Organization으로 프로젝트 그룹화하기
프로젝트가 늘어나면 개인 계정 하나로 관리하기 어려워집니다. Organization을 만들어 용도별로 분리하세요.
구성 예시
| Organization | 용도 |
|---|---|
| 개인 계정 | 개인 프로젝트, 실험 |
팀이름-team | 팀/회사 프로젝트 |
팀이름-ai | AI/ML 관련 프로젝트 |
Organization 생성 방법
- GitHub 우측 상단
+클릭 New organization선택- Free 플랜 선택
- 이름 입력 후 생성
이렇게 하면 저장소 생성 시 Owner를 선택할 수 있어 프로젝트 분류가 명확해집니다.
Repository 생성 방법 3가지
방법 1: VSCode에서 바로 생성 (권장)
가장 간단한 방법입니다. GitHub 계정이 VSCode에 연동되어 있다면 바로 사용 가능합니다.
# 1. 폴더 생성 및 VSCode 열기
mkdir my-project
cd my-project
code .
# 2. 파일 하나 생성 (README.md 등)
# 3. Publish
Ctrl+Shift+P → "Publish to GitHub" 입력 → Private/Public 선택
Git 초기화, 저장소 생성, 푸시가 한 번에 됩니다.
방법 2: GitHub CLI
터미널에서 모든 작업을 처리하고 싶다면 GitHub CLI를 설치하세요.
# 설치 (최초 1회)
brew install gh # macOS
winget install GitHub.cli # Windows
# 로그인 (최초 1회)
gh auth login
# 저장소 생성 + 푸시
gh repo create my-project --private --source=. --push
방법 3: 웹에서 생성
전통적인 방법입니다.
- GitHub.com → New repository
- Owner에서 Organization 선택
- Repository name 입력
- Create repository
- 로컬에서
git remote add후 푸시
Branch 이해하기
브랜치는 같은 프로젝트 안에서 작업 복사본을 만드는 개념입니다.
파일 작업할 때 보고서_수정중.docx, 보고서_최종.docx 이렇게 해본 적 있죠? 브랜치가 이걸 깔끔하게 해결해줍니다.
1인 개발: main만 사용
main ← 모든 작업
혼자 개발한다면 브랜치 분리 없이 main 하나로 충분합니다.
팀 개발: 브랜치 분리
main (프로덕션)
├── develop (개발 통합)
│ ├── feature/* (기능 개발)
│ └── bugfix/* (버그 수정)
└── hotfix/* (긴급 수정)
팀 작업에서는 브랜치 분리가 필수입니다. 각자 브랜치에서 작업 후 PR로 병합하면 충돌을 최소화할 수 있어요.
필수 파일 구성
최소 구성
├── README.md # 프로젝트 설명
├── .gitignore # 버전관리 제외 파일
└── .env.example # 환경변수 템플릿
.gitignore 예시
Node.js
node_modules/
.env
.DS_Store
dist/
Python
__pycache__/
.env
venv/
*.pyc
VSCode에서 Git 사용하기
기본 명령어
# 변경사항 스테이징
git add .
# 커밋
git commit -m "feat: 로그인 기능 추가"
# 푸시
git push origin main
# 풀 (원격 변경사항 가져오기)
git pull origin main
GUI로 사용하기
Ctrl+Shift+G: Source Control 패널 열기+버튼: Stage 변경사항- 메시지 입력 후
✓: 커밋 ...→ Push: 푸시
명령어가 익숙하지 않다면 GUI부터 시작해도 됩니다.
프로젝트 그룹화 팁
Organization 외에도 프로젝트를 정리하는 방법이 있습니다.
이름 규칙 (Prefix)
rag-service-backend
rag-service-frontend
rag-service-infra
관련 프로젝트끼리 prefix를 맞추면 정렬했을 때 모아서 볼 수 있습니다.
Topics (태그)
저장소 Settings에서 Topics를 추가하면 태그로 필터링할 수 있습니다.
예: nextjs, typescript, side-project
커밋 메시지 컨벤션
나중에 히스토리를 볼 때 알아보기 쉽도록 일관된 형식을 사용하세요.
타입: 간단한 설명
# 타입 예시
init: 프로젝트 초기화
feat: 새 기능 추가
fix: 버그 수정
docs: 문서 수정
refactor: 코드 리팩토링
정리
| 항목 | 1인 개발 | 팀 개발 |
|---|---|---|
| Branch | main만 | main + develop + feature |
| Organization | 선택 | 권장 |
| PR | 불필요 | 필수 |
| Branch 보호 | 불필요 | main 보호 설정 |
1인 개발이라면 최대한 단순하게 시작하고, 필요할 때 확장하는 게 좋습니다. Organization과 브랜치 전략은 프로젝트가 커지거나 협업이 시작될 때 도입해도 늦지 않습니다.