배포 매뉴얼
전체 목차01 · GitHub 저장소 준비
Chapter 01

GitHub 저장소 준비

최종 확인일 2026-11-04 읽는 시간 약 9분 시작하기 · 첫 배포까지

목표#

  • GitHub에 새 저장소(Repository)를 만듭니다.
  • 로컬 PC의 프로젝트를 Git으로 관리하고 GitHub 저장소에 push합니다.
  • 이후 코드를 고칠 때마다 push하는 기본 작업 흐름을 익힙니다.

사전 조건#

  • 0장의 준비물 체크리스트를 모두 완료했습니다.

    • GitHub 계정 로그인 가능
    • git --version 정상 출력
    • git config --global user.name / user.email 설정 완료
  • 배포할 프로젝트 폴더가 있습니다. 이 장에서는 예시로 my-app 폴더를 사용합니다.

1. GitHub에 새 저장소 만들기#

  1. https://github.com 에 로그인합니다.
  2. 오른쪽 위 + 버튼을 누르고 New repository를 선택합니다.
  3. Repository name에 저장소 이름을 입력합니다. 예: my-app

    • 영문 소문자, 숫자, 하이픈(-)을 사용하는 것을 권장합니다.
    • 이 이름은 나중에 Vercel 기본 주소(my-app.vercel.app 등)를 정할 때도 기본값으로 쓰입니다.
  4. Description에 짧은 설명을 입력합니다. (선택)
  5. 공개 범위를 선택합니다.

    • Public: 누구나 코드를 볼 수 있습니다.
    • Private: 본인과 초대한 사람만 볼 수 있습니다.
  6. README, .gitignore, license 추가 옵션은 모두 선택하지 않은 상태로 둡니다.
  7. Create repository 버튼을 누릅니다.
중요

로컬에 이미 프로젝트가 있다면 6번의 README / .gitignore / license 옵션을 체크하지 마세요. 체크하면 GitHub 저장소에 커밋이 먼저 생겨서, 처음 push할 때 rejected 오류가 납니다. (해결법은 문제 해결 참고)

참고

Public과 Private 저장소 모두 Vercel에 연결할 수 있습니다. 저장소를 Private으로 만들어도 배포된 웹사이트는 누구나 접속할 수 있습니다. 코드 공개 여부와 사이트 공개 여부는 별개입니다.

저장소가 만들어지면 빈 저장소 안내 화면이 나옵니다. 화면에 보이는 저장소 주소(HTTPS) 를 복사해 둡니다.

output
https://github.com/<USER>/my-app.git

2. .gitignore 파일 만들기#

.gitignore는 GitHub에 올리지 않을 파일을 적어 두는 파일입니다. 용량이 큰 라이브러리 폴더나 비밀 값이 담긴 파일이 저장소에 올라가지 않게 막아 줍니다.

  1. 프로젝트 폴더(my-app) 최상단에 .gitignore 파일이 있는지 확인합니다.

    • create-next-app 같은 도구로 만든 프로젝트라면 이미 들어 있습니다.
  2. 없다면 새로 만들고 아래 내용을 넣습니다.
.gitignore
# 의존성
node_modules/

# 빌드 결과물
.next/
dist/
build/
out/

# 환경 변수 (비밀 값)
.env
.env*.local

# Vercel CLI 연결 정보
.vercel/

# OS / 편집기
.DS_Store
Thumbs.db
주의

API 키, 데이터베이스 비밀번호 등이 담긴 .env 파일은 절대 커밋하지 마세요. Public 저장소라면 전 세계에 공개되고, Private 저장소라도 유출 위험이 있습니다. 이런 값은 5장에서 Vercel 환경 변수로 따로 설정합니다.

팁

순수 HTML 프로젝트라면 node_modules/나 빌드 폴더 항목이 없어도 문제는 없지만, 그대로 두어도 괜찮습니다.


3. 로컬 프로젝트를 Git 저장소로 만들고 push하기#

터미널을 열고 프로젝트 폴더로 이동합니다.

PowerShell
# Windows (PowerShell) 예시
cd D:\Projects\my-app
bash
# macOS / Linux 예시
cd ~/projects/my-app

이제 아래 명령어를 한 줄씩 실행합니다.

  1. Git 저장소로 초기화합니다.

    bash
    git init
    참고

    create-next-app 등으로 만든 프로젝트는 이미 Git 저장소일 수 있습니다. 이때는 Reinitialized existing Git repository 메시지가 나오는데, 문제없으니 다음 단계로 진행합니다.

  2. 모든 파일을 커밋 대상으로 추가합니다.

    bash
    git add .
  3. 추가된 파일 목록을 확인합니다. node_modules나 .env가 목록에 없어야 합니다.

    bash
    git status
  4. 첫 커밋을 만듭니다.

    bash
    git commit -m "Initial commit"
  5. 기본 브랜치 이름을 main으로 맞춥니다.

    bash
    git branch -M main
  6. GitHub 저장소를 원격 저장소(origin)로 등록합니다. 주소는 1단계에서 복사한 주소로 바꿉니다.

    bash
    git remote add origin https://github.com/<USER>/my-app.git
  7. GitHub로 push합니다.

    bash
    git push -u origin main
    • -u 옵션은 "앞으로 이 브랜치는 origin의 main과 연결한다"는 뜻입니다. 처음 한 번만 붙이면 이후에는 git push만 입력해도 됩니다.
팁

새로 만드는 저장소의 기본 브랜치를 항상 main으로 하려면 아래 명령을 한 번 실행해 두세요. 이후 git init 할 때 5번 단계가 필요 없습니다.

bash
git config --global init.defaultBranch main

4. GitHub 로그인(인증)#

처음 push할 때 GitHub 로그인을 요청받습니다.

중요

GitHub는 Git 명령어에서 계정 비밀번호로 로그인하는 것을 지원하지 않습니다. 아래 방법 중 하나를 사용하세요.

방법 A. 브라우저로 로그인 (권장, Windows 기본)#

Windows용 Git에는 Git Credential Manager가 포함되어 있습니다. push하면 로그인 창이 뜹니다.

  1. 창에서 Sign in with your browser를 선택합니다.
  2. 브라우저가 열리면 GitHub에 로그인하고 권한을 승인합니다.
  3. 터미널로 돌아오면 push가 이어서 진행됩니다.

로그인 정보는 저장되므로 다음부터는 묻지 않습니다.

방법 B. GitHub CLI로 로그인#

GitHub CLI를 설치했다면 아래 명령으로 로그인할 수 있습니다.

bash
gh auth login

안내에 따라 GitHub.com → HTTPS → Login with a web browser를 선택합니다.

방법 C. Personal Access Token (토큰)#

macOS/Linux에서 로그인 창이 뜨지 않고 Username, Password를 묻는 경우에 사용합니다.

  1. GitHub Settings → Developer settings → Personal access tokens에서 토큰을 발급합니다.
  2. 터미널에서 Username에는 GitHub 아이디를, Password에는 비밀번호 대신 발급받은 토큰을 붙여 넣습니다.
주의

토큰은 비밀번호와 같습니다. 문서·채팅·코드에 붙여 넣지 말고, 필요한 최소 권한과 만료일을 정해서 발급하세요.


5. 이후 작업 흐름: 수정 → 커밋 → push#

처음 연결이 끝나면 코드를 고칠 때마다 아래 세 줄만 반복하면 됩니다.

bash
git add .
git commit -m "변경 내용을 짧게 설명"
git push

3장에서 Vercel과 연결하고 나면, 이 git push가 곧 배포 명령이 됩니다. main에 push할 때마다 Vercel이 자동으로 다시 배포합니다.

팁

커밋 메시지는 나중에 Vercel의 배포 목록에도 표시됩니다. 수정, test처럼 쓰기보다 메인 페이지 제목 변경처럼 무엇을 바꿨는지 알 수 있게 쓰면 문제가 생겼을 때 어느 배포로 되돌릴지 찾기 쉽습니다.


확인 방법#


문제 해결#

error: remote origin already exists.#

origin이 이미 등록되어 있습니다. 주소만 바꿉니다.

bash
git remote set-url origin https://github.com/<USER>/my-app.git

error: src refspec main does not match any#

아직 커밋이 없거나 브랜치 이름이 main이 아닙니다.

  1. git status로 커밋할 파일이 있는지 확인하고 git add . → git commit -m "Initial commit"을 실행합니다.
  2. git branch -M main으로 브랜치 이름을 맞춘 뒤 다시 push합니다.

! [rejected] main -> main (fetch first)#

GitHub 저장소에 로컬에 없는 커밋이 있습니다. 저장소를 만들 때 README 등을 함께 추가한 경우에 주로 발생합니다. 원격 내용을 먼저 받아 합친 뒤 push합니다.

bash
git pull --rebase origin main
git push -u origin main
주의

인터넷 검색에서 흔히 보이는 git push --force는 GitHub에 있는 커밋을 덮어써서 지웁니다. 무엇이 지워지는지 확실히 알 때가 아니라면 사용하지 마세요.

Authentication failed / Support for password authentication was removed#

계정 비밀번호로 로그인하려 했습니다. 4. GitHub 로그인(인증)의 방법 A~C 중 하나를 사용하세요.

fatal: not a git repository#

프로젝트 폴더가 아닌 곳에서 명령을 실행했습니다. cd로 프로젝트 폴더로 이동했는지 확인하세요. (PowerShell은 Get-Location, macOS/Linux는 pwd로 현재 위치 확인)

node_modules가 GitHub에 올라가 버렸어요#

.gitignore를 나중에 추가해도 이미 커밋된 파일은 자동으로 빠지지 않습니다. Git 추적 목록에서만 제거합니다. (로컬 파일은 지워지지 않습니다.)

bash
git rm -r --cached node_modules
git commit -m "node_modules 추적 제외"
git push
주의

.env처럼 비밀 값이 담긴 파일이 올라갔다면 위 방법으로 지워도 커밋 이력에는 남아 있습니다. 해당 키·비밀번호를 즉시 폐기하고 새로 발급하세요.


다음 단계#

➡️ 2장. Vercel 가입과 GitHub 연동: GitHub 계정으로 Vercel에 가입하고 저장소 접근 권한을 설정합니다.

참고 자료#