바이브 코딩은 끝났는데 배포를 못 한다면? Git·GitHub·Vercel 완전 입문 가이드
Codex나 Claude Code가 웹사이트를 만들어 주었는데, 그다음 무엇을 해야 할지 모르겠다면 이 글만 천천히 따라오면 됩니다. Git을 처음 듣는 사람도 이해할 수 있도록, 내 컴퓨터에 있는 프로젝트가 실제 인터넷 주소가 되는 과정을 처음부터 설명합니다.
요즘은 코딩을 몰라도 자연어로 프로그램을 만들 수 있습니다. “이미지를 변환하는 웹사이트를 만들어줘”, “회원가입이 있는 예약 페이지를 만들어줘”라고 요청하면 AI가 파일을 만들고 화면까지 완성해 줍니다.
그런데 마지막에 예상하지 못한 벽을 만납니다.
내 컴퓨터에서만 열리는 웹사이트는 아직 세상에 공개된 서비스가 아닙니다. 다른 사람이 주소를 입력해 접속할 수 있도록 인터넷에 올리는 과정이 필요한데, 이것을 배포(Deployment)라고 합니다.
배포를 검색하면 Git, GitHub, Repository, Commit, Push, Build, Vercel, 환경변수 같은 단어가 한꺼번에 등장합니다. 비개발자에게는 코딩보다 이 용어들이 더 어렵게 느껴질 수 있습니다. 하지만 처음부터 모든 기술을 공부할 필요는 없습니다. 각 도구가 무슨 역할을 하는지만 생활 속 물건에 비유해 이해하면 됩니다.
1. 배포는 무엇인가?
배포는 어렵게 말하면 프로그램을 운영 환경에 공개하는 일입니다. 쉽게 말하면 내 컴퓨터 안에만 있던 웹사이트를 인터넷에 올려 누구나 주소로 접속할 수 있게 만드는 것입니다.
프로젝트 파일
GitHub
Vercel
예를 들어 Codex가 만든 프로젝트가 내 컴퓨터의 C:\projects\my-tool 폴더에 들어 있다고 해보겠습니다. 지금은 그 폴더가 있는 컴퓨터에서만 실행할 수 있습니다. 이를 Vercel 같은 서비스에 배포하면 다음과 같은 주소가 생깁니다.
https://my-tool.vercel.app
이제 그 주소를 친구에게 보내거나 블로그에 연결할 수 있습니다. 방문자의 컴퓨터에는 프로젝트 파일이 없어도 됩니다. Vercel이 대신 웹사이트를 실행하고 방문자에게 보여주기 때문입니다.
2. Git은 무엇인가?
Git은 파일의 변경 기록을 관리하는 프로그램입니다. GitHub와 이름이 비슷하지만 둘은 같은 것이 아닙니다.
예를 들어 문서를 수정할 때 다음처럼 파일을 여러 개 복사해 본 경험이 있을 것입니다.
최종.docx 최종_수정.docx 진짜최종.docx 진짜최종2.docx 진짜진짜최종.docx
프로그램도 개발하면서 파일이 계속 바뀝니다. 어제는 잘 작동했는데 오늘 수정한 뒤 고장 날 수 있습니다. Git은 그때마다 프로젝트 전체를 복사하는 대신, 어느 파일의 무엇이 바뀌었는지 기록합니다. 필요하면 이전 상태로 돌아갈 수도 있습니다.
Git 공식 설명에서 기본 작업 흐름은 파일을 수정하고, 다음 기록에 포함할 변경을 고른 뒤, 그 상태를 기록하는 과정으로 소개됩니다. 개발자는 이 기록 덕분에 변경 과정을 추적할 수 있습니다.
설명용 이미지: Git은 프로젝트가 변해 온 과정을 기록합니다.
Git을 꼭 직접 배워야 할까?
바이브 코딩을 하는 비개발자라면 처음부터 Git 명령어를 전부 외울 필요는 없습니다. Codex나 Claude Code가 Git 작업을 대신 수행할 수 있기 때문입니다. 다만 다음 네 단어의 의미는 알아두는 것이 좋습니다.
| 용어 | 쉽게 말하면 | 생활 속 비유 |
|---|---|---|
| Repository | 프로젝트와 변경 기록이 들어 있는 공간 | 프로젝트 전용 서류함 |
| Commit | 현재 변경 내용을 하나의 기록으로 저장 | 작업 일지 한 줄 작성 |
| Push | 내 컴퓨터의 기록을 GitHub로 전송 | 서류를 온라인 창고에 업로드 |
| Pull | GitHub의 최신 내용을 내 컴퓨터로 가져옴 | 온라인 창고의 최신 서류 내려받기 |
3. GitHub는 무엇인가?
GitHub는 Git으로 관리하는 프로젝트를 인터넷에 보관하는 서비스입니다. Git은 내 컴퓨터에서 변경 기록을 관리하는 도구이고, GitHub는 그 프로젝트와 기록을 온라인에 저장하고 공유하는 장소입니다.
Git이 사진을 정리하고 변경 기록을 남기는 방식이라면, GitHub는 그 사진 앨범을 온라인에 보관하는 클라우드 서비스와 비슷합니다.
GitHub에서는 프로젝트별로 Repository(저장소)를 만듭니다. GitHub 공식 문서도 저장소를 코드, 파일, 파일의 변경 이력을 보관하는 가장 기본적인 공간으로 설명합니다. 저장소는 누구나 볼 수 있는 Public 또는 허용된 사람만 볼 수 있는 Private로 만들 수 있습니다.
설명용 이미지: GitHub 저장소에서는 프로젝트 파일을 웹 화면으로 확인할 수 있습니다.
왜 Vercel에 바로 올리지 않고 GitHub를 거칠까?
GitHub를 연결하면 프로젝트를 수정할 때마다 배포 파일을 다시 선택해 업로드할 필요가 없습니다. 내 컴퓨터에서 변경한 내용을 GitHub에 Push하면 Vercel이 그 변화를 감지해 자동으로 새 버전을 배포할 수 있습니다.
즉, GitHub는 단순한 백업 장소가 아니라 개발 작업과 배포 서비스를 연결하는 중간 다리가 됩니다.
4. Repository, Commit, Push를 실제 흐름으로 이해하기
용어를 따로 외우는 것보다 한 번의 수정 과정을 떠올리면 쉽습니다.
예: 한국어만 지원하던 사이트에 영어 화면을 추가합니다.
“영어 UI 추가”라는 이름으로 이번 변경을 하나의 기록으로 남깁니다.
내 컴퓨터에 있던 새 기록을 온라인 저장소로 보냅니다.
새 Commit을 발견하고 웹사이트를 다시 빌드해 공개합니다.
AI에게 “변경 내용을 커밋하고 GitHub에 Push해줘”라고 요청할 때 바로 이 과정이 진행됩니다.
5. 내 프로젝트에는 어떤 배포 방법이 맞을까?
HTML·CSS·JavaScript
Netlify 폴더 업로드가 가장 간단합니다. 프로젝트 폴더를 화면에 끌어다 놓으면 됩니다.
Next.js·React 웹앱
GitHub + Vercel 조합을 추천합니다. 한 번 연결하면 수정할 때마다 자동 배포할 수 있습니다.
소개 페이지·프로젝트 문서
GitHub Pages도 사용할 수 있습니다. 다만 서버 기능이 필요한 앱에는 적합하지 않습니다.
정적 사이트·Cloudflare 사용자
Cloudflare Pages를 고려할 수 있습니다. 처음 배포라면 Vercel이나 Netlify가 더 쉽게 느껴질 수 있습니다.
package.json 파일이 있고 Codex가 Next.js라고 설명했다면 GitHub와 Vercel 방식을 선택하면 됩니다. index.html을 더블클릭해 사이트가 열리는 단순 프로젝트라면 Netlify 폴더 업로드가 쉽습니다.6. GitHub 없이 HTML 사이트를 Netlify로 배포하기
가장 단순한 방법부터 살펴보겠습니다. 프로젝트가 HTML, CSS, JavaScript 파일로만 구성되어 있다면 Git을 몰라도 배포할 수 있습니다.
먼저 폴더를 확인합니다
my-website/ ├── index.html ├── style.css ├── script.js └── images/
첫 화면 파일은 보통 index.html입니다. Netlify 공식 안내에 따르면 프로젝트 폴더나 ZIP 파일을 Drop 영역에 끌어다 놓아 공유 가능한 netlify.app 주소를 만들 수 있습니다.
Drag and drop your site output folder
폴더 선택설명용 이미지: Netlify Drop 방식은 폴더를 끌어다 놓는 것만으로 배포할 수 있습니다.
GitHub 계정이나 이메일로 계정을 만들 수 있습니다.
Projects에서 수동 배포 또는 Netlify Drop 화면으로 이동합니다.
index.html이 들어 있는 폴더를 선택합니다.사이트이름.netlify.app 형태의 주소가 생성됩니다.Netlify 폴더 업로드의 한계
내용을 수정하면 변경된 폴더를 다시 업로드해야 합니다. 또한 Next.js의 서버 기능, 로그인 처리, 데이터베이스 연결처럼 빌드와 서버 실행이 필요한 프로젝트는 단순 폴더 업로드보다 GitHub 연결 배포가 더 안정적입니다.
7. Next.js 프로젝트를 GitHub와 Vercel로 배포하기
Codex로 Next.js 웹사이트를 만들었다면 이 방식이 가장 현실적입니다.
전체 과정부터 보기
1단계: GitHub 계정을 만들고 새 저장소를 준비합니다
GitHub 오른쪽 위의 New repository 메뉴를 선택합니다. 저장소 이름은 영어 소문자와 하이픈을 사용하면 관리하기 쉽습니다.
Create a new repository
설명용 이미지: 저장소 이름과 공개 범위를 정해 새 Repository를 만듭니다.
Public은 누구나 코드를 볼 수 있고, Private은 허용된 사용자만 볼 수 있습니다. 개인 프로젝트나 아직 공개하고 싶지 않은 서비스라면 Private으로 시작해도 됩니다.
2단계: Codex에게 GitHub 업로드를 요청합니다
현재 프로젝트를 GitHub에 올릴 수 있도록 준비해줘. 1. 빌드 오류가 없는지 확인 2. .gitignore 파일 확인 3. API 키와 개인정보가 포함되지 않았는지 검사 4. README.md 작성 5. 변경 내용을 Commit 6. 내가 만든 GitHub 저장소에 Push 진행 중 권한이나 로그인이 필요하면 내가 눌러야 할 버튼을 정확히 설명해줘.
Codex가 GitHub 연결 권한을 요청하면 승인 화면이 나타날 수 있습니다. 이때 저장소 접근 범위를 확인한 뒤 허용합니다. 연결이 완료되면 GitHub 저장소 화면에 프로젝트 파일이 나타납니다.
3단계: Vercel에서 GitHub 저장소를 불러옵니다
Vercel에 GitHub 계정으로 로그인하고 Add New → Project를 선택합니다. GitHub 저장소 목록에서 방금 만든 프로젝트를 찾아 Import를 누릅니다.
Import Git Repository
GitHub 연결됨Next.js · Updated 2 minutes ago
ImportHTML · Updated 2 months ago
Import설명용 이미지: Vercel에서 배포할 GitHub 저장소를 선택합니다.
4단계: 배포 설정을 확인합니다
Vercel 공식 문서에 따르면 Git 저장소를 선택한 뒤 프로젝트 이름, 프레임워크, 루트 디렉터리, 빌드 설정, 환경변수를 구성하고 Deploy를 실행할 수 있습니다. Next.js 프로젝트는 프레임워크가 자동 감지되는 경우가 많습니다.
Configure Project
설명용 이미지: 대부분은 자동 감지된 설정을 확인한 뒤 Deploy를 누르면 됩니다.
5단계: 배포 성공 주소를 확인합니다
https://image-converter.vercel.app
설명용 이미지: 성공하면 공유할 수 있는 vercel.app 주소가 생성됩니다.
Vercel은 연결된 Git 저장소에 새 Commit이 올라오면 자동으로 새 배포를 만들 수 있습니다. 따라서 앞으로는 사이트를 수정한 뒤 Codex에게 다음처럼 요청하면 됩니다.
이번 변경 내용을 확인하고 문제가 없으면 Commit한 뒤 GitHub에 Push해줘. Push 이후 Vercel 자동 배포가 시작되는지도 확인해줘.
8. 환경변수는 무엇이고, API 키는 왜 따로 넣어야 할까?
초보자가 배포하면서 가장 자주 막히는 부분이 환경변수(Environment Variables)입니다.
환경변수는 프로그램이 필요로 하지만 코드 안에 직접 넣으면 곤란한 값을 외부에서 전달하는 방식입니다. 대표적으로 다음 값이 있습니다.
OPENAI_API_KEY DATABASE_URL NEXT_PUBLIC_SITE_URL SUPABASE_SERVICE_ROLE_KEY
비밀번호나 API 키를 코드에 직접 적고 GitHub에 올리면 저장소를 본 사람이 그 값을 가져갈 수 있습니다. Private 저장소라도 실수나 권한 설정 문제에 대비해 비밀값은 코드와 분리하는 것이 기본 원칙입니다.
Vercel 공식 문서는 환경변수를 소스 코드 밖에서 설정하는 키와 값으로 설명하며, 프로젝트 설정에서 환경별로 관리할 수 있다고 안내합니다.
Environment Variables
설명용 이미지: API 키는 코드가 아니라 Vercel 환경변수 메뉴에 등록합니다.
NEXT_PUBLIC_이 붙은 값은 비밀일까?
Next.js에서 NEXT_PUBLIC_ 접두사가 붙은 환경변수는 브라우저로 전달될 수 있으므로 비밀키를 넣으면 안 됩니다. 공개되어도 되는 사이트 주소나 공개용 설정값에만 사용해야 합니다.
9. 배포가 실패했을 때 가장 먼저 볼 것
배포 실패는 드문 일이 아닙니다. 중요한 것은 빨간 오류 화면을 보고 포기하지 않는 것입니다. Vercel의 배포 로그를 복사해 AI에게 전달하면 상당수 문제를 해결할 수 있습니다.
오류 1. Build failed
Vercel이 프로젝트를 실제 웹사이트로 만드는 과정에서 문제가 생겼다는 뜻입니다. 내 컴퓨터에서는 실행되더라도 운영용 빌드에서는 더 엄격한 검사가 실행될 수 있습니다.
Vercel 배포 중 아래 Build 오류가 발생했어. [여기에 Vercel 오류 로그 붙여넣기] 1. 오류의 핵심 원인을 한글로 설명해줘. 2. 수정해야 할 파일을 찾아 고쳐줘. 3. npm run build를 실행해 다시 확인해줘. 4. 성공하면 Commit하고 GitHub에 Push해줘.
오류 2. 환경변수가 없음
로컬의 .env.local 파일에는 값이 있지만 Vercel에는 등록하지 않은 경우입니다. 오류 로그에 “undefined”, “missing API key”, “environment variable not found” 같은 표현이 나타날 수 있습니다.
오류 3. Root Directory가 잘못됨
GitHub 저장소 안에 실제 Next.js 프로젝트가 하위 폴더에 들어 있으면 Vercel이 package.json을 찾지 못할 수 있습니다.
my-project/
├── documents/
└── web-app/
├── package.json
├── app/
└── public/
이 경우 Vercel의 Root Directory를 web-app으로 설정해야 합니다.
오류 4. 대소문자가 다름
Windows에서는 Logo.png와 logo.png가 비슷하게 처리될 수 있지만 배포 서버에서는 서로 다른 파일로 취급될 수 있습니다. 로컬에서는 보이던 이미지가 배포 후 사라지는 대표적인 원인입니다.
오류 5. 배포는 됐지만 일부 기능이 작동하지 않음
로그인, 데이터베이스, 결제, 외부 API를 사용하는 서비스라면 각 서비스에 운영 주소를 등록해야 할 수 있습니다. 예를 들어 로그인 서비스의 Redirect URL이 아직 localhost로 되어 있다면 실제 Vercel 주소에서는 로그인이 실패할 수 있습니다.
10. 비개발자가 Codex에 그대로 붙여 넣을 배포 준비 프롬프트
다음 요청문은 Git이나 배포를 잘 모르는 사람이 프로젝트를 정리할 때 사용할 수 있도록 만든 것입니다.
현재 프로젝트를 비개발자가 GitHub와 Vercel로 안전하게 배포할 수 있는 상태로 준비해줘. 반드시 다음 순서로 진행해줘. 1. 현재 프로젝트의 프레임워크와 구조를 확인 2. npm run build를 실행하고 오류가 있으면 수정 3. API 키, 비밀번호, 개인정보가 코드에 직접 들어 있는지 검사 4. 비밀값은 환경변수로 분리 5. .env, .env.local이 GitHub에 올라가지 않도록 .gitignore 확인 6. 필요한 환경변수 이름만 .env.example에 작성 7. README.md에 실행 방법과 배포 방법 작성 8. Git 변경 내용을 이해하기 쉬운 메시지로 Commit 9. 내가 지정한 GitHub 저장소에 Push 10. Vercel에서 선택해야 할 설정을 표로 정리 나는 Git과 GitHub를 잘 모르는 비개발자야. 권한 승인이나 버튼 클릭이 필요하면 화면에서 무엇을 눌러야 하는지 한국어로 정확히 설명해줘. 비밀키의 실제 값은 출력하거나 GitHub에 올리지 마.
11. 배포가 끝난 뒤 확인해야 할 체크리스트
- PC와 휴대전화에서 사이트가 모두 열리는가?
- 메뉴, 버튼, 이미지, 다운로드 기능이 정상 작동하는가?
- 한국어와 영어 화면이 모두 정상 표시되는가?
- 로그인과 로그아웃이 정상 작동하는가?
- API 키가 GitHub 파일에 노출되지 않았는가?
- 새로고침했을 때 404 오류가 발생하지 않는가?
- 브라우저 주소창에 HTTPS 자물쇠가 표시되는가?
- 모바일 화면에서 글자와 버튼이 잘리지 않는가?
- 오류 발생 시 사용자에게 이해 가능한 안내가 표시되는가?
- GitHub에 새 변경을 Push했을 때 자동 배포되는가?
12. 자주 묻는 질문
GitHub에 올리면 누구나 내 코드를 볼 수 있나요?
Public 저장소는 누구나 볼 수 있지만 Private 저장소는 허용된 사용자만 볼 수 있습니다. 다만 어느 쪽이든 API 키나 비밀번호는 저장소에 올리지 않는 것이 원칙입니다.
Git을 설치하지 않고도 배포할 수 있나요?
단순 HTML 사이트는 Netlify 폴더 업로드로 가능합니다. GitHub 웹 업로드도 가능하지만, 지속적으로 수정하고 자동 배포하려면 Git을 사용하는 편이 편리합니다. Codex가 설치와 명령 실행을 도와줄 수 있습니다.
Vercel 무료 주소를 계속 사용해도 되나요?
초기 테스트와 개인 프로젝트에서는 vercel.app 주소로 시작할 수 있습니다. 서비스가 안정되면 개인 도메인을 연결하면 됩니다. 실제 운영 전에는 현재 요금제의 사용 조건과 제한을 확인하는 것이 좋습니다.
수정할 때마다 Vercel에서 Deploy를 다시 눌러야 하나요?
GitHub 저장소를 Vercel에 연결했다면 보통 새 Commit이 Push될 때 자동 배포가 시작됩니다.
GitHub 저장소를 Private으로 해도 Vercel 배포는 가능한가요?
가능합니다. Vercel에 해당 저장소를 읽을 수 있는 권한을 허용해야 합니다.
마무리: 코딩이 끝난 뒤 필요한 것은 세 단계뿐이다
처음에는 Git, GitHub, Vercel이 서로 비슷해 보입니다. 하지만 역할을 나누면 어렵지 않습니다.
GitHub는 프로젝트를 온라인에 보관하며,
Vercel은 그 프로젝트를 웹사이트로 공개합니다.
비개발자가 Git 명령어를 모두 외울 필요는 없습니다. 중요한 것은 전체 흐름을 이해하고, AI에게 무엇을 확인시켜야 하는지 아는 것입니다.
단순 HTML 사이트라면 Netlify에 폴더를 올리는 방식으로 시작할 수 있습니다. Next.js로 만든 웹앱이라면 GitHub에 프로젝트를 저장하고 Vercel에 연결하는 방식을 추천합니다. 한 번 연결하고 나면 이후에는 “수정 → Commit → Push → 자동 배포” 흐름으로 운영할 수 있습니다.
바이브 코딩의 완성은 코드가 만들어졌을 때가 아니라, 실제 사용자가 주소를 열고 기능을 사용할 수 있을 때입니다.
댓글
댓글 쓰기