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(저장소)는 프로젝트의 파일과 변경 이력 전체가 저장되는 원격 공간입니다.
- github.com에 로그인 후 오른쪽 위 + 아이콘 → New repository 클릭 (또는 github.com/new)
- Repository name 입력 — 예:
my-vercel-app(영문 소문자·숫자·하이픈 권장) - Description (선택) — 프로젝트 설명
- Public / Private 선택 — Vercel은 둘 다 배포 가능합니다.
- Initialize this repository with
- 이미 로컬에 프로젝트가 있다면 → 모두 체크 해제 (빈 저장소로 생성해야 충돌이 없습니다)
- 새로 시작한다면 → Add a README file 체크 후 clone 해서 사용
- 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 Manager | Windows용 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 연결
- vercel.com 로그인 → Continue with GitHub 선택을 권장합니다.
- 대시보드 오른쪽 위 Add New… → Project 클릭 (또는 vercel.com/new)
- Import Git Repository 영역에서 GitHub 계정을 연결합니다.
- 처음이면 Install 버튼 → GitHub 화면에서 Vercel GitHub App 설치
- All repositories 또는 Only select repositories(배포할 저장소만 선택) 중 선택 후 Install
- 목록에 나타난 저장소 옆 Import 클릭
- Configure Project 화면에서 설정 확인
항목 설명 Project Name 배포 주소에 사용됨 → 프로젝트명.vercel.appFramework Preset Next.js, Vite 등 자동 감지. 순수 HTML이면 Other Root Directory 저장소 안 하위 폴더에 앱이 있으면 지정 (예: frontend)Build & Output Settings 보통 기본값 사용. 예: Build npm run build, OutputdistEnvironment Variables API 키 등 비밀값 입력 ( .env대신)
저장소가 목록에 안 보이면 GitHub → Settings → Applications → Vercel → Configure에서 해당 저장소 접근 권한을 추가하세요.
6. Deploy
- 설정 화면 하단 Deploy 클릭 → 빌드 로그가 실시간으로 표시됩니다.
- 완료되면 축하 화면과 함께 미리보기 이미지가 나타납니다. Continue to Dashboard로 이동
- Domains에 표시된
https://프로젝트명.vercel.app주소로 접속해 확인
이후 자동 배포 (Git 연동의 핵심)
| Git 동작 | Vercel 결과 |
|---|---|
main 브랜치에 push / PR merge | Production 배포 → 운영 도메인에 즉시 반영 |
| 다른 브랜치에 push | Preview 배포 → 브랜치별 고유 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 repository | Git 저장소 폴더가 아님 → 프로젝트 폴더로 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가 성공하는지 먼저 확인 |
| 배포 후 404 | Output Directory 또는 Root Directory 설정 오류. 정적 사이트는 루트에 index.html이 있어야 함 |
| 환경 변수가 적용 안 됨 | 변수 추가·수정 후 Redeploy 필요. 클라이언트에서 쓰는 변수는 프레임워크 접두사 필요 (예: NEXT_PUBLIC_, VITE_) |
| push 했는데 배포가 안 됨 | Settings → Git에서 저장소 연결·Production 브랜치 확인, GitHub App 권한 확인 |
| 저장소가 Import 목록에 없음 | GitHub → Settings → Applications → Vercel → Configure에서 저장소 접근 권한 추가 |