Git · GitHub · 배포 완전 가이드

01 — Concept

세 가지를 먼저 구분한다

Git · GitHub · 배포는 서로 다른 것이다. 섞이면 아무것도 이해가 안 된다.

🕰️ Git

내 컴퓨터 안의 타임머신

언제 무엇을 바꿨는지 기억하고, 과거로 되돌아갈 수 있다.

인터넷 없어도 작동한다.

☁️ GitHub

클라우드 금고 (인터넷)

Git 기록을 인터넷에 올려두는 서비스.

팀원과 공유, 협업, 백업이 가능해진다.

🚀 배포

전 세계 공개

내 컴퓨터에서만 돌던 것을 인터넷 주소로 누구나 접근할 수 있게 만드는 것.

비유로 이해하기

📁 Git 없이 개발하면 생기는 일

현실

프로젝트_최종.zip
프로젝트_진짜최종.zip
프로젝트_진짜진짜최종.zip
프로젝트_이게맞음.zip
프로젝트_진짜이게맞음_수정2.zip
↑ 이런 경험이 있다면 Git이 해답이다

⏱️ Git이 있으면

Git 타임머신

오전 10시: 첫 화면 만들었다 ← 저장됨
오전 11시: 버튼 3개 추가했다 ← 저장됨
오후  2시: 버튼 다 망가뜨렸다... ← 저장됨
오후  2시: 오전 11시 버전으로 돌아가고 싶다!
          → Git으로 1초 만에 가능

🏠 → 🏦 → 🌍 흐름 한눈에

전체 흐름

내 컴퓨터에서 개발 (localhost:3000)
      ↓
[Git] 코드 변경사항 기록
      ↓  git push
[GitHub] 클라우드에 안전 보관
      ↓  자동 감지
[Vercel/Netlify] 빌드 → 배포
      ↓
https://내앱.vercel.app ← 전 세계 접근 가능

Git vs GitHub — 정확한 차이

구분	Git	GitHub
정체	소프트웨어 도구	웹 서비스 (사이트)
위치	내 컴퓨터 안	인터넷
인터넷 필요	없어도 됨	필요
만든 곳	Linus Torvalds (2005)	Microsoft 소유 (2018~)
비용	무료	기본 무료
비슷한 것	—	GitLab, Bitbucket
없어도 되나?	필수	선택 (하지만 필수적)

02 — Vocabulary

핵심 용어 사전

클릭하면 자세한 설명이 열린다.

Repository 저장소 · 레포 ▼

📁 일반 폴더 + 모든 변경 기록이 담긴 특별한 폴더

프로젝트 폴더 안에 숨겨진 .git 폴더가 생기고, 이 폴더가 언제 누가 무엇을 바꿨는지 전부 기억한다. "레포"라고 줄여 부른다.

로컬 레포 내 컴퓨터에 있는 것
원격 레포 GitHub에 있는 것

Commit 커밋 · 저장 스냅샷 ▼

🎮 게임 세이브 포인트. 이 순간을 기록해둔다는 선언

커밋할 때는 메시지를 반드시 쓴다. 나중에 "어떤 세이브인지" 알아야 하기 때문이다.

좋은 커밋 메시지: "로그인 화면 UI 완성"
나쁜 커밋 메시지: "수정" "aaaa"

Push 푸시 · 올리기 ▼

📤 내 컴퓨터 → GitHub으로 올리기

push 하기 전까지는 내 컴퓨터에만 존재한다. push 후에야 팀원이 볼 수 있고, 배포가 트리거될 수 있다.

순서: add → commit → push

Pull 풀 · 가져오기 ▼

📥 GitHub → 내 컴퓨터로 가져오기

팀원이 새로운 코드를 올렸을 때, 내 컴퓨터를 최신 상태로 맞추려면 pull한다.

팀 협업 시 작업 전 항상 먼저 pull하는 것이 원칙이다.

Clone 클론 · 복사해 오기 ▼

📋 GitHub 저장소를 내 컴퓨터에 통째로 복사

처음 프로젝트를 받아올 때 사용한다. Clone하면 모든 파일과 Git 기록까지 함께 내려온다.

git clone https://github.com/아이디/프로젝트.git

Branch 브랜치 · 평행 우주 ▼

🌿 원본을 건드리지 않고 실험하는 별도 공간

main ← 원본 (실제 서비스)
  ├─ feature/login ← 로그인 기능 개발 중
  ├─ feature/payment ← 결제 개발 중
  └─ bugfix/button ← 버그 수정 중

각 브랜치는 독립적이다. 한 곳에서 망쳐도 다른 브랜치는 무사하다.

Merge 머지 · 합치기 ▼

🔀 브랜치를 원본(main)에 합치기

실험이 성공하면 main에 합친다. 실패하면 브랜치만 삭제하면 된다.

feature/login 완료 → main에 merge → 서비스 반영

Pull Request (PR) 합쳐달라는 요청 ▼

📝 "내가 만든 기능을 main에 합쳐주세요"라는 요청서

팀 협업의 핵심이다. 코드 검토(리뷰) → 승인 → 합치기 순서로 진행된다.

혼자 작업할 때는 PR 없이 직접 merge해도 된다.

Fork 포크 · 남의 것 내 것으로 ▼

🍴 다른 사람의 레포를 내 GitHub 계정으로 복사

오픈소스 코드를 베이스로 내 것을 만들거나, 기여하고 싶을 때 사용한다.

Clone과의 차이: Clone은 그냥 복사, Fork는 GitHub에서 나의 레포로 만드는 것.

.gitignore 무시 목록 ▼

🙈 "이건 GitHub에 올리지 마" 목록

비밀번호, API 키, 자동 생성 파일 등은 절대 올리면 안 된다.

반드시 포함해야 할 것: .env (비밀번호/API 키)
node_modules/ (자동 생성 대용량 폴더)

03 — Setup

설치 & 초기 설정

딱 한 번만 하면 된다. 순서대로 따라간다.

1

Git 설치

Windows: git-scm.com → Download for Windows → 기본값으로 설치
Mac: 터미널에서 brew install git

설치 확인

git --version
# 결과: git version 2.x.x 가 나오면 성공

2

GitHub 가입

github.com → Sign up → 이메일/비밀번호/아이디 입력 → 이메일 인증

아이디 선택 팁

GitHub 아이디가 포트폴리오 주소가 된다. github.com/내아이디
나쁜 예: cool_coder_1234 / 좋은 예: hegler-kim

3

Git 초기 설정 (딱 한 번)

누가 커밋했는지 표시하기 위해 이름과 이메일을 등록한다.

터미널 (PowerShell / Git Bash)

# 이름 설정
git config --global user.name "홍길동"

# 이메일 (GitHub 계정과 동일하게)
git config --global user.email "hegler.kim@gmail.com"

# 기본 브랜치를 main으로 설정
git config --global init.defaultBranch main

# 설정 확인
git config --global --list

4

GitHub 연결 — SSH 키 등록 (비밀번호 없이 통신)

한 번만 설정하면 이후 매번 비밀번호 입력이 필요 없다.

SSH 키 생성

# SSH 키 생성 (이메일은 GitHub 계정 이메일)
ssh-keygen -t ed25519 -C "hegler.kim@gmail.com"
# 엔터 3번 (기본값으로)

# 생성된 공개 키 확인 → 이 내용을 복사해서 GitHub에 등록
cat ~/.ssh/id_ed25519.pub

GitHub 등록 경로: GitHub → 우측 프로필 → Settings → SSH and GPG keys → New SSH key → 붙여넣기 → 저장

04 — Workflow

기본 작업 흐름

새 프로젝트 시작부터 GitHub에 올리기까지 순서대로.

①

폴더 만들기

작업할 폴더를 만들고 들어간다

터미널

mkdir my-project
cd my-project

②

Git 초기화

이 폴더를 Git 레포지토리로 만든다

터미널

git init
# 결과: Initialized empty Git repository

③

파일 만들고 Staging

파일을 만들고 커밋에 포함할 파일을 선택한다

터미널

# 전체 파일 스테이징
git add .

# 특정 파일만
git add README.md

④

Commit — 저장 스냅샷

이 순간을 기록한다. 메시지는 명확하게.

터미널

git commit -m "첫 번째 커밋: README 추가"

⑤

GitHub 레포 연결 & Push

GitHub에서 새 레포를 만든 후 연결하고 올린다

터미널

# GitHub 레포 연결 (SSH 방식)
git remote add origin git@github.com:내아이디/my-project.git

# 처음 올리기
git push -u origin main

# 이후에는 이것만
git push

✓

완료!

github.com/내아이디/my-project 에서 코드가 보인다

매일 하는 작업 루틴

일상 루틴

# 작업 시작 전: 팀원 코드 받아오기
git pull

# 코드 수정 후...

# 뭐가 바뀌었는지 확인
git status

# 스테이징
git add .

# 커밋
git commit -m "로그인 버튼 색깔 파란색으로 변경"

# GitHub에 올리기
git push

💬 커밋 메시지 잘 쓰는 법

종류	예시
feat	feat: 로그인 화면 추가
fix	fix: 결제 버튼 클릭 안 되는 버그 수정
style	style: 폰트 크기 조정
docs	docs: README 설치 방법 업데이트
refactor	refactor: 중복 코드 정리

05 — GitHub Projects

GitHub 프로젝트 만들기

레포지토리 생성부터 팀원 초대까지.

방법 1 — GitHub 웹에서 만들기 (가장 쉬움)

1

github.com 로그인 후 + 버튼

우측 상단 + 버튼 → New repository

2

설정 입력

레포 설정

Repository name: my-project
  (영어, 공백 대신 하이픈(-) 사용)

Description: 프로젝트 한 줄 설명 (선택)

Public  = 전 세계 누구나 볼 수 있음
Private = 나만 (또는 초대한 사람만)

✅ Add a README file  ← 체크 권장
✅ Add .gitignore     ← 프레임워크 선택 (Node, Python 등)

3

Create repository 클릭

완료! github.com/내아이디/my-project 주소로 접근 가능

방법 2 — 기존 폴더를 GitHub에 올리기

주의

이미 작업 중인 폴더가 있을 때 GitHub에서 새 레포 만들 때 README 체크 해제! (충돌 방지)

터미널

# 내 폴더에서
git init
git add .
git commit -m "첫 커밋"

# GitHub 레포와 연결 (SSH)
git remote add origin git@github.com:내아이디/my-project.git

# 올리기
git push -u origin main

README.md — 레포의 얼굴

README.md 예시

# 프로젝트 이름

한 줄 설명: 이 앱이 무엇인지

## 기능
- 재료 입력 → 레시피 추천
- 레시피 저장

## 설치 방법
```bash
npm install
npm run dev
```

## 사용 기술
- React, Next.js
- Supabase

팀원 초대하기

레포지토리 → Settings → 왼쪽 메뉴 Collaborators → Add people → 팀원 GitHub 아이디 입력 → 팀원이 이메일 수락하면 완료

06 — Deploy

배포 — 전 세계에 공개하기

내 컴퓨터에서만 돌던 것을 인터넷 주소로 만드는 것이 배포다.

배포 전후 차이

비교

배포 전: http://localhost:3000
  → 내 컴퓨터만 접근 가능

배포 후: https://내앱.vercel.app
  → 전 세계 누구나 접근 가능

⭐ 방법 1 — Vercel (가장 쉽고 빠름)

vercel.com 가입

GitHub으로 로그인 (가장 편함)

2

New Project 클릭

GitHub 레포지토리 목록에서 프로젝트 선택

3

Deploy 클릭

자동으로 빌드하고 주소를 만들어준다
https://프로젝트명.vercel.app

4

이후 자동 배포

코드 수정 → GitHub push → Vercel 자동 감지 → 자동 재배포. 별도 작업 없음!

환경 변수 (비밀번호/API 키) 설정

코드에 비밀번호를 직접 쓰면 안 된다. Vercel 설정에서 따로 입력한다.

경로: Vercel 대시보드 → 프로젝트 → Settings → Environment Variables
KEY: OPENAI_API_KEY
VALUE: sk-xxxxx...

방법 2 — Netlify

Vercel과 거의 동일한 방식. 정적 사이트(순수 HTML/CSS/JS)에 강하다.

netlify.com → Add new site → Import an existing project → GitHub 연결 → Deploy site

주소: https://랜덤이름.netlify.app

방법 3 — GitHub Pages (완전 무료)

순수 HTML/CSS/JS 사이트 전용. 서버 기능은 없다. 포트폴리오 사이트에 적합.

레포지토리 → Settings → Pages → Source: Deploy from a branch → main, /(root) → Save

주소: https://내아이디.github.io/프로젝트명

비교표

항목	Vercel	Netlify	GitHub Pages
난이도	★☆☆ 쉬움	★☆☆ 쉬움	★★☆ 보통
무료	✅	✅	✅
Next.js 지원	✅ 최적	✅	❌
서버 기능	✅	✅	❌
자동 배포	✅	✅	✅
커스텀 도메인	✅	✅	✅
추천 상황	Next.js 앱	정적 사이트	포트폴리오

커스텀 도메인 연결 (myapp.com)

1

도메인 구매

가비아, Cloudflare, GoDaddy 등에서 구매. 연간 약 1~2만원.

2

DNS 설정

DNS 레코드 추가

타입: CNAME
이름: www
값: cname.vercel-dns.com  (Vercel의 경우)

3

Vercel에서 도메인 등록

프로젝트 → Settings → Domains → 도메인 입력 → 저장

4

24~48시간 후 적용

DNS 전파에 시간이 걸린다. 기다리면 된다.

07 — Commands

실전 명령어 모음

복사해서 바로 쓸 수 있다.

자주 쓰는 명령어

git status뭐가 바뀌었는지 확인

git diff줄 단위로 어떻게 바뀌었는지 확인

git log --oneline커밋 기록 한 줄씩 보기

git add .전체 파일 스테이징

git add 파일명특정 파일만 스테이징

git commit -m "메시지"커밋 (저장 스냅샷)

git pushGitHub에 올리기

git pullGitHub에서 가져오기

git clone [URL]레포 통째로 복사해 오기

브랜치 명령어

git branch브랜치 목록 보기

git branch 이름새 브랜치 만들기

git switch 이름브랜치 이동

git checkout -b 이름브랜치 만들고 바로 이동

git merge 브랜치이름브랜치 합치기

git branch -d 이름브랜치 삭제

실수 수습 명령어

git restore 파일명파일 변경 취소 (커밋 전)

git restore --staged 파일명스테이징 취소

git commit --amend -m "수정"마지막 커밋 메시지 수정 (push 전)

git revert 커밋해시특정 커밋 되돌리기 (기록 유지)

git rm --cached 파일명.gitignore 추가 후 추적 제거

처음 세팅 (복사용)

# 새 프로젝트 시작 전체 흐름
git init
git add .
git commit -m "첫 커밋"
git remote add origin git@github.com:아이디/프로젝트.git
git push -u origin main

08 — Mistakes

자주 하는 실수 & 수습법

누구나 한 번씩 겪는다. 미리 알면 패닉이 없다.

실수 1 — .env 파일을 GitHub에 올림

비밀번호, API 키가 전 세계에 공개된다. 한 번 올라가면 기록이 남는다.

해결: 지금 당장 .gitignore에 추가

.gitignore

.env
.env.local
.env.production
.env*.local

실수 2 — node_modules 올림

수십만 개의 파일 = 수백 MB. 시간 낭비, 용량 낭비. npm install로 자동 생성되므로 올릴 필요 없다.

해결: .gitignore에 추가

.gitignore

node_modules/
.next/
dist/
build/

실수 3 — add하고 커밋 안 하고 push

git add . 후 git push를 바로 하면 아무것도 올라가지 않는다.

반드시: add → commit → push 순서

올바른 순서

git add .
git commit -m "메시지"  ← 이걸 빠뜨리면 안 됨
git push

실수 4 — pull 없이 push했더니 오류

팀원이 먼저 push했는데 내가 pull 안 하고 push 시도 → 거절됨

해결: pull 먼저, push 나중

해결 순서

git pull
# 충돌 있으면 해결 후
git add .
git commit -m "merge 충돌 해결"
git push

충돌(Conflict) 해결하기

같은 파일의 같은 줄을 두 사람이 다르게 수정하면 충돌이 발생한다.

충돌 표시 예시

<<<<<<< HEAD
내가 수정한 내용
=======
팀원이 수정한 내용
>>>>>>> 브랜치이름

위 표시를 직접 편집해서 원하는 내용으로 정리한 후:

충돌 해결 후

git add .
git commit -m "충돌 해결: 로그인 버튼 코드 통합"

전체 흐름 요약

기억할 것

내 컴퓨터에서 개발
  ↓ git add .
스테이징 (올릴 파일 선택)
  ↓ git commit -m "메시지"
로컬 저장 (스냅샷)
  ↓ git push
GitHub 업로드
  ↓ 자동 감지
Vercel 배포
  ↓
https://내앱.vercel.app

09 — GitHub × Vercel

GitHub · Vercel 연동 완전 가이드

GitHub에 push 하면 Vercel이 자동으로 빌드하고 배포한다. 한 번 연결하면 끝이다.

🔁 자동 배포 전체 흐름

흐름도

내 컴퓨터에서 코드 수정
      ↓
git add . && git commit -m "수정사항"
      ↓
git push  ← 이것만 하면 끝
      ↓
GitHub 레포지토리 (코드 저장)
      ↓  Vercel이 자동 감지 (웹훅)
Vercel 빌드 서버 (npm run build 자동 실행)
      ↓  보통 30초~2분
https://내앱.vercel.app ← 자동 업데이트 완료

STEP 1 — Vercel 가입 & GitHub 계정 연결

1

vercel.com 접속 → Sign Up

Continue with GitHub 선택 → GitHub 로그인 화면이 뜸 → 승인

반드시 GitHub으로 로그인

이메일로 가입하면 나중에 GitHub 연결을 따로 해야 한다. 처음부터 GitHub으로 로그인하는 것이 가장 편하다.

2

Vercel에 GitHub 접근 권한 부여

GitHub에서 Vercel 앱 설치 화면이 뜬다.

권한 선택

All repositories  ← 모든 레포에 접근 허용 (편리)
Only select repositories ← 특정 레포만 허용 (보안상 권장)

처음에는 "All repositories"로 해도 무방하다. 나중에 변경 가능.

3

Install & Authorize 클릭

GitHub 비밀번호 확인 후 승인. Vercel 대시보드로 자동 이동된다.

STEP 2 — 첫 프로젝트 연결 & 배포

1

Vercel 대시보드 → Add New → Project

왼쪽 상단 Add New… → Project

2

GitHub 레포지토리 선택

내 GitHub 레포 목록이 뜬다. 배포할 프로젝트 옆 Import 클릭.

레포가 안 보일 때

Configure GitHub App → 해당 레포를 Vercel 접근 허용 목록에 추가한다.

3

프로젝트 설정 확인

Vercel이 프레임워크를 자동 감지한다. 대부분 건드릴 필요 없다.

자동 감지 예시

Framework Preset: Next.js  ← 자동 감지됨
Root Directory:  ./        ← 기본값 유지
Build Command:   npm run build  ← 자동
Output Directory: .next    ← 자동
Install Command: npm install    ← 자동

4

환경 변수 입력 (있을 경우)

Environment Variables 섹션 펼쳐서 .env 파일의 내용을 여기에 입력한다.

.env 파일 내용 → Vercel 환경변수로 이전

# 내 .env 파일 (GitHub에 올리면 안 됨)
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=my-secret-key

# → Vercel 환경변수 칸에 하나씩 입력
NAME: OPENAI_API_KEY   VALUE: sk-xxxxxxxxxxxxx
NAME: DATABASE_URL     VALUE: postgresql://...
NAME: NEXTAUTH_SECRET  VALUE: my-secret-key

5

Deploy 클릭

빌드 로그가 실시간으로 보인다. 보통 30초~2분 후 완료.

배포 완료 후

자동으로 생성된 URL이 나온다: https://프로젝트명.vercel.app
이 주소로 전 세계 누구나 접근 가능하다.

STEP 3 — 이후 자동 배포 (핵심)

🪄 push하면 자동으로 배포된다

연결 후에는 아래 세 줄만 치면 배포까지 완료된다.

이게 전부다

git add .
git commit -m "버튼 색깔 변경"
git push

push 후 1~2분 뒤 vercel.app 주소에서 바로 확인 가능하다.

브랜치별 프리뷰 URL

main 브랜치가 아닌 다른 브랜치를 push하면 별도의 미리보기 URL이 자동 생성된다.

브랜치별 URL 구조

main 브랜치 push
  → https://내프로젝트.vercel.app  (운영 URL, 고정)

feature/login 브랜치 push
  → https://내프로젝트-git-feature-login-아이디.vercel.app
     (임시 프리뷰 URL — 팀원에게 보내서 확인 요청 가능)

bugfix/button 브랜치 push
  → https://내프로젝트-git-bugfix-button-아이디.vercel.app

PR을 열면 GitHub PR 페이지에 프리뷰 URL이 자동으로 댓글로 달린다.

환경 변수 관리 (배포 후)

1

Vercel 대시보드 → 프로젝트 선택

2

Settings → Environment Variables

환경별 분리 설정

Production  ← main 브랜치 배포에 적용
Preview     ← 나머지 브랜치 프리뷰에 적용
Development ← vercel dev (로컬) 실행 시 적용

# 예: 테스트 DB와 운영 DB를 다르게 쓸 때
Production  DATABASE_URL = postgresql://실제DB...
Preview     DATABASE_URL = postgresql://테스트DB...

3

변수 추가/수정 후 재배포

환경 변수 변경 후에는 Redeploy를 눌러야 적용된다. 코드 변경 없이 재배포 가능.

빌드 실패 시 대응법

빌드 로그 보는 법

Vercel 대시보드 → 프로젝트 → Deployments → 실패한 배포 클릭 → Build Logs

자주 나오는 오류 패턴

─── 오류 1: 환경 변수 없음 ───
Error: OPENAI_API_KEY is not defined
→ 해결: Vercel 환경변수에 해당 키 추가 후 재배포

─── 오류 2: 빌드 명령어 실패 ───
Error: Cannot find module 'xxx'
→ 해결: package.json 확인, npm install 후 로컬에서 먼저 빌드 테스트
        git add package.json package-lock.json
        git commit -m "의존성 추가"
        git push

─── 오류 3: TypeScript 오류 ───
Type error: ...
→ 해결: 로컬에서 npm run build 실행해서 오류 먼저 확인
        오류 수정 후 push

─── 오류 4: 루트 디렉토리 설정 오류 ───
No Next.js version detected
→ 해결: Vercel → Settings → General → Root Directory 확인
        monorepo라면 apps/web 등 정확한 경로 입력

커스텀 도메인 연결 (myapp.com)

1

Vercel → 프로젝트 → Settings → Domains

도메인 입력칸에 myapp.com 입력 → Add

2

Vercel이 DNS 설정 방법을 알려준다

Vercel이 제시하는 DNS 레코드

# 루트 도메인 (myapp.com)
타입: A
이름: @  (또는 비워두기)
값: 76.76.21.21

# www 서브도메인 (www.myapp.com)
타입: CNAME
이름: www
값: cname.vercel-dns.com

3

도메인 구매처에서 DNS 설정 입력

가비아 / Cloudflare / GoDaddy 등 → DNS 관리 → 위 레코드 추가

Cloudflare 추천 이유

무료 CDN + DDoS 방어 + DNS 관리가 한번에 된다. 도메인을 Cloudflare로 이전하면 Vercel 연동도 더 쉽다.

4

24~48시간 대기

DNS 전파 시간이 필요하다. Vercel 도메인 탭에서 ✅ Valid Configuration 뜨면 완료.

HTTPS (자물쇠)는 Vercel이 자동으로 설정해준다. 별도 작업 없음.

✅ 한 줄 요약

처음 한 번

vercel.com → GitHub으로 로그인 → Import 레포 → Deploy
# 끝. 이후는 git push만 하면 자동 배포.

매번 배포

git add .
git commit -m "변경사항 설명"
git push
# → 1~2분 후 자동으로 배포 완료