매뉴얼

GitHub + Vercel Setting

로컬 프로젝트를 GitHub 저장소에 올리고, Vercel과 연결해 push 한 번으로 자동 배포되게 만드는 전체 과정입니다.

로컬 코드→ git commit→ git push→ GitHub Repository→ Vercel 자동 빌드→ https://*.vercel.app

0. 준비물

  • GitHub 계정 — github.com/signup
  • Vercel 계정 — vercel.com/signup (GitHub 계정으로 가입하면 연결이 가장 간단합니다)
  • Git — 로컬 PC에 설치 (아래 2-① 참고)
  • 올릴 프로젝트 — 정적 HTML, Next.js, React(Vite), Vue 등

Part 1 · GitHub 설정

1. Repository 생성

Repository(저장소)는 프로젝트의 파일과 변경 이력 전체가 저장되는 원격 공간입니다.

  1. github.com에 로그인 후 오른쪽 위 + 아이콘 → New repository 클릭 (또는 github.com/new)
  2. Repository name 입력 — 예: my-vercel-app (영문 소문자·숫자·하이픈 권장)
  3. Description (선택) — 프로젝트 설명
  4. Public / Private 선택 — Vercel은 둘 다 배포 가능합니다.
  5. Initialize this repository with
    • 이미 로컬에 프로젝트가 있다면 → 모두 체크 해제 (빈 저장소로 생성해야 충돌이 없습니다)
    • 새로 시작한다면 → Add a README file 체크 후 clone 해서 사용
  6. Create repository 클릭 → 생성된 페이지의 주소(https://github.com/<사용자명>/my-vercel-app.git)를 복사해 둡니다.
TIP  .gitignore 템플릿에서 Node를 고르면 node_modules/, .env 등이 자동으로 제외됩니다. 로컬에 직접 만들어도 됩니다.

2. 클라이언트 연결 방법

내 PC(클라이언트)의 Git이 GitHub 저장소와 통신할 수 있도록 설치 → 사용자 정보 설정 → 인증 → 원격 저장소 연결 순서로 진행합니다.

① Git 설치

Windows는 git-scm.com에서 설치 파일을 받거나, 터미널에서 winget을 사용합니다. 설치 후 확인:

# Windows (winget)
winget install --id Git.Git -e

# macOS (Homebrew)
brew install git

# 설치 확인
git --version

② 사용자 정보 설정 (최초 1회)

커밋에 기록될 작성자 정보입니다. GitHub 계정의 이메일과 같게 설정하면 커밋이 내 프로필에 연결됩니다.

git config --global user.name "홍길동"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

# 설정 확인
git config --list

③ GitHub 인증

GitHub는 비밀번호로 push할 수 없습니다. 아래 방법 중 하나를 사용하세요.

방법특징권장 대상
A. Git Credential ManagerWindows용 Git에 기본 포함. 첫 push 때 브라우저 로그인 창이 뜨고 이후 자동 저장가장 간단 · 입문자
B. GitHub CLI (gh)gh auth login 한 번으로 인증 + 저장소 생성까지 터미널에서 가능터미널 선호
C. SSH 키키 쌍을 만들어 GitHub에 공개키 등록. 토큰 만료 걱정 없음여러 PC · 장기 사용

B. GitHub CLI

winget install --id GitHub.cli -e
gh auth login
# → GitHub.com → HTTPS → Login with a web browser 선택 후 안내에 따라 진행

C. SSH 키

# 1) 키 생성 (엔터 3번)
ssh-keygen -t ed25519 -C "you@example.com"

# 2) 공개키 내용 복사
cat ~/.ssh/id_ed25519.pub

# 3) GitHub → Settings → SSH and GPG keys → New SSH key 에 붙여넣기

# 4) 연결 테스트
ssh -T git@github.com

④ 로컬 프로젝트 ↔ GitHub 저장소 연결

경우 1 — 이미 로컬에 프로젝트가 있을 때 (빈 Repository를 만든 경우)

cd D:\Projects\my-vercel-app

git init                         # 현재 폴더를 Git 저장소로 초기화
git add .                        # 모든 파일 스테이징
git commit -m "first commit"     # 첫 커밋
git branch -M main               # 브랜치 이름을 main으로
git remote add origin https://github.com/<사용자명>/my-vercel-app.git
git push -u origin main          # 원격에 올리고 추적 설정

경우 2 — GitHub에 있는 저장소를 내려받아 시작할 때

git clone https://github.com/<사용자명>/my-vercel-app.git
cd my-vercel-app
origin은 원격 저장소의 별칭입니다. 연결 상태는 git remote -v로 확인하고, 주소를 바꾸려면 git remote set-url origin <새 주소>를 사용합니다.

3. 커밋 · 푸시 개념 및 실행 명령

Working Directory내가 편집 중인 파일
Staging Area커밋할 변경 목록
Local Repository내 PC의 커밋 이력
Remote (GitHub)공유·배포용 저장소
git add →
git commit →
git push →
← git pull
개념설명
Stage (add)변경된 파일 중 이번 커밋에 포함할 것을 고르는 단계
Commit스테이징된 변경을 메시지와 함께 내 PC의 이력에 스냅샷으로 저장. 아직 GitHub에는 올라가지 않음
Push로컬 커밋들을 GitHub(원격)으로 업로드. Vercel은 이 시점을 감지해 배포를 시작
Pull원격의 최신 커밋을 받아와 로컬에 합침 (다른 PC·협업자 변경 반영)
Branch독립적인 작업 줄기. main = 운영, 그 외 = 기능 개발/미리보기

일상적인 작업 흐름

git pull                          # 1. 작업 전 최신 상태로

#    ... 파일 수정 ...

git status                        # 2. 변경된 파일 확인
git diff                          #    변경 내용 상세 확인 (선택)
git add .                         # 3. 전체 스테이징 (특정 파일: git add index.html)
git commit -m "메인 페이지 헤더 수정"  # 4. 커밋
git push                          # 5. GitHub로 업로드 → Vercel 자동 배포

git log --oneline                 # 커밋 이력 확인

브랜치로 작업하기 (미리보기 배포 활용)

git switch -c feature/login       # 새 브랜치 생성 + 이동
git add .
git commit -m "로그인 화면 추가"
git push -u origin feature/login  # → Vercel Preview 배포 생성

# GitHub에서 Pull Request 생성 → 검토 → Merge 하면 main에 반영 → Production 배포
좋은 커밋 메시지  무엇을·왜 바꿨는지 한 줄로. 예: fix: 모바일에서 메뉴 겹침 수정, feat: 문의 폼 추가
주의  API 키·비밀번호가 든 .env 파일은 절대 커밋하지 마세요. .gitignore에 추가하고, 값은 Vercel의 Environment Variables에 등록합니다.

4. 명령어 요약

명령용도
git init현재 폴더를 Git 저장소로 초기화
git clone <URL>원격 저장소 내려받기
git remote add origin <URL>원격 저장소 연결
git remote -v연결된 원격 저장소 확인
git status변경 상태 확인
git add .전체 변경 스테이징
git commit -m "메시지"로컬 커밋
git push -u origin main최초 push (추적 브랜치 설정)
git push이후 push
git pull원격 변경 받아오기
git log --oneline커밋 이력 간략히 보기
git switch -c <브랜치>새 브랜치 생성 + 이동
git restore <파일>커밋 전 수정 내용 되돌리기

Part 2 · Vercel 연결 · 배포

5. Vercel Project 생성 및 Git 연결

  1. vercel.com 로그인 → Continue with GitHub 선택을 권장합니다.
  2. 대시보드 오른쪽 위 Add New… → Project 클릭 (또는 vercel.com/new)
  3. Import Git Repository 영역에서 GitHub 계정을 연결합니다.
    • 처음이면 Install 버튼 → GitHub 화면에서 Vercel GitHub App 설치
    • All repositories 또는 Only select repositories(배포할 저장소만 선택) 중 선택 후 Install
  4. 목록에 나타난 저장소 옆 Import 클릭
  5. Configure Project 화면에서 설정 확인
    항목설명
    Project Name배포 주소에 사용됨 → 프로젝트명.vercel.app
    Framework PresetNext.js, Vite 등 자동 감지. 순수 HTML이면 Other
    Root Directory저장소 안 하위 폴더에 앱이 있으면 지정 (예: frontend)
    Build & Output Settings보통 기본값 사용. 예: Build npm run build, Output dist
    Environment VariablesAPI 키 등 비밀값 입력 (.env 대신)
저장소가 목록에 안 보이면 GitHub → Settings → Applications → Vercel → Configure에서 해당 저장소 접근 권한을 추가하세요.

6. Deploy

  1. 설정 화면 하단 Deploy 클릭 → 빌드 로그가 실시간으로 표시됩니다.
  2. 완료되면 축하 화면과 함께 미리보기 이미지가 나타납니다. Continue to Dashboard로 이동
  3. Domains에 표시된 https://프로젝트명.vercel.app 주소로 접속해 확인

이후 자동 배포 (Git 연동의 핵심)

Git 동작Vercel 결과
main 브랜치에 push / PR mergeProduction 배포 → 운영 도메인에 즉시 반영
다른 브랜치에 pushPreview 배포 → 브랜치별 고유 URL 생성
Pull Request 생성PR에 Vercel 봇이 미리보기 링크를 댓글로 남김
PR(Pull Request)이란?  다른 브랜치에서 작업한 내용을 main에 합쳐 달라고 GitHub에 올리는 요청입니다. 변경 내용을 검토한 뒤 Merge하면 main에 반영됩니다. PR을 만들면 Vercel이 Preview 주소를 PR 댓글로 남겨 주므로, 운영 사이트를 건드리지 않고 바뀐 화면을 먼저 확인할 수 있습니다. 혼자 작업할 때는 PR 없이 main에 바로 push해도 됩니다.

즉, 최초 1회 연결 후에는 git push만 하면 배포가 끝납니다. 별도로 Vercel에 접속할 필요가 없습니다. push 방법은 3. 커밋 · 푸시를 참고하세요.

대시보드에서 자주 쓰는 기능

  • Deployments — 배포 이력, 빌드 로그 확인. 각 항목의 ⋯ → Redeploy로 재배포
  • Instant Rollback — 이전 정상 배포를 선택해 Promote to Production으로 즉시 되돌리기
  • Settings → Domains — 보유한 커스텀 도메인 연결 (DNS 레코드 안내 표시)
  • Settings → Environment Variables — 변수 수정 후에는 재배포해야 적용됩니다
  • Settings → Git — 연결된 저장소 변경·해제, Production 브랜치 지정

(선택) Vercel CLI로 배포

npm i -g vercel
vercel login
vercel          # Preview 배포 (최초 실행 시 프로젝트 연결 질문)
vercel --prod   # Production 배포

7. 문제 해결

GitHub (push · 인증)

증상원인 · 해결
fatal: not a git repositoryGit 저장소 폴더가 아님 → 프로젝트 폴더로 cd 하거나 git init
remote origin already exists이미 연결됨 → git remote set-url origin <URL>
Authentication failed / 403비밀번호로 인증 시도 → 2-③의 Credential Manager, gh auth login, SSH 중 하나로 인증
rejected ... (fetch first)원격에 내 PC에 없는 커밋 존재 (README로 생성한 경우 등) → git pull --rebase origin main 후 다시 push
src refspec main does not match any커밋이 아직 없음 → git add . · git commit 먼저

Vercel (빌드 · 배포)

증상원인 · 해결
Vercel 빌드 실패Deployments → 실패 항목 → Build Logs 확인. 로컬에서 npm run build가 성공하는지 먼저 확인
배포 후 404Output Directory 또는 Root Directory 설정 오류. 정적 사이트는 루트에 index.html이 있어야 함
환경 변수가 적용 안 됨변수 추가·수정 후 Redeploy 필요. 클라이언트에서 쓰는 변수는 프레임워크 접두사 필요 (예: NEXT_PUBLIC_, VITE_)
push 했는데 배포가 안 됨Settings → Git에서 저장소 연결·Production 브랜치 확인, GitHub App 권한 확인
저장소가 Import 목록에 없음GitHub → Settings → Applications → Vercel → Configure에서 저장소 접근 권한 추가