깃허브와 Vercel 연결하기, 컴맹이 막혔던 곳 그대로 공개

작성자: 컴맹 집사

대표 이미지: Vercel 프로젝트 설정에서 확인한 GitHub 연결 항목 (출처: 직접 캡처한 화면(2026년 9월 18일))

설명만 들었을 때는 “GitHub 저장소를 Vercel에서 불러와서 Deploy 버튼을 누르면 끝”이었다. 실제로는 한 시간 가까이 걸렸다. 버튼을 누르는 시간보다 화면 앞에서 멈춰 있던 시간이 훨씬 길었다.

이 글은 매끈한 설명서가 아니라, 내가 멈칫했던 지점까지 담은 기록이다. 같은 곳에서 멈춘 분이 있다면 여기서 넘어갈 수 있으면 좋겠다.

시작 전 준비 상태

• GitHub 계정이 있다.
• 강아지 앱 저장소(kba-butler-app)를 GitHub에 푸시해 둔 상태다.
• 저장소 맨 바깥에 index.html 파일이 있다.

마지막 항목이 나중에 중요해진다. 기억해 두자.

1단계. Vercel 가입, GitHub로 로그인

vercel.com에 들어가 Sign Up을 누르고, 가입 방법 중 Continue with GitHub를 골랐다.

GitHub 화면에서 “Vercel이 당신의 GitHub 계정에 접근하도록 허락하겠습니까?”라는 안내가 나왔다. 여기서 한 번 멈칫했다. 내 계정을 남에게 넘겨주는 건가 싶었다.

AI에게 물어보니, 이건 Vercel이 내 저장소 파일을 읽어 갈 수 있도록 허락하는 절차였다. 이 허락이 있어야 Vercel이 GitHub에서 파일을 가져가 배포할 수 있다. (출처: Vercel 문서, Git 연동) 비밀번호를 넘겨주는 것과는 다르다. Authorize를 눌러 진행했다.

가입 중에 사용 목적을 묻는 화면이 나오면, 개인 프로젝트는 Hobby를 고르면 된다.

2단계. 새 프로젝트 만들기

로그인하면 Vercel 대시보드(관리 화면)가 나온다. Add New… → Project를 누른다. 그러면 Import Git Repository라는 제목 아래에 내 GitHub 저장소 목록이 나와야 한다.

첫 번째 막힘: 저장소가 목록에 없다

목록이 비어 있었다. 분명 GitHub에 올렸는데 kba-butler-app이 보이지 않았다.

원인은 권한이었다. Vercel이 GitHub에 설치될 때 “모든 저장소”가 아니라 “선택한 저장소”에만 접근하도록 설정되었거나, 아직 설치가 덜 된 상태였다.

해결 방법은 이랬다.

1. 저장소 목록 아래쪽의 Adjust GitHub App Permissions(또는 GitHub 설정 링크)를 누른다.
2. GitHub 화면에서 Repository access 항목을 찾는다.
3. All repositories를 고르거나, Only select repositories에서 kba-butler-app을 추가한다.
4. Save를 누르고 Vercel로 돌아온다.

돌아오니 kba-butler-app이 목록에 나타났다. 옆의 Import 버튼을 눌렀다.

초보자 팁: 저장소가 안 보이면 대부분 권한 문제다. 저장소가 비공개(Private)여도 권한만 주면 Vercel에서 불러올 수 있다.

3단계. 프로젝트 설정 화면

Import를 누르면 설정 화면이 나온다. 모르는 항목이 여럿 있었다. 강아지 앱처럼 HTML 파일 위주의 단순한 웹앱 기준으로 정리하면 이렇다.

Framework Preset에서 두 번째로 멈칫했다. Next.js, React 같은 낯선 이름이 가득했다. AI에게 물어보니 이건 React 같은 개발 도구(프레임워크)를 썼을 때 고르는 항목이다. index.html 하나로 만든 앱은 Other를 고르면 된다. Vercel이 자동으로 Other를 골라 주는 경우도 있다.

Project Name은 주소가 된다는 걸 나중에 알았다. kba-butler-app으로 두면 주소가 kba-butler-app.vercel.app이 되는데, 이미 누가 쓰는 이름이면 뒤에 글자가 더 붙는다. 앱 이름을 정했다면 여기서 바꿔도 된다.

4단계. Deploy

설정을 마치고 Deploy를 눌렀다. 화면에 진행 기록이 주르륵 올라가고, 몇십 초 뒤 축하 화면이 떴다. 폭죽 효과와 함께 앱의 작은 미리보기가 보였다.

이 순간의 이야기는 다음 글에 따로 적었다. 여기서는 연결 과정에서 한 번 더 막혔던 부분만 적는다.

두 번째 막힘: 주소를 열었는데 404가 뜬다

사실 첫 시도에서 나는 축하 화면 다음에 404: NOT_FOUND를 봤다. 배포는 성공했다는데 페이지가 없다니.

원인은 파일 위치였다. 저장소를 만들 때 kba-butler-app 폴더 안에 app이라는 폴더를 만들고 그 안에 index.html을 넣어 뒀던 것이다. Vercel은 저장소 맨 바깥에서 index.html을 찾는데, 거기엔 아무것도 없었다.

해결 방법은 두 가지였다.

• index.html을 저장소 맨 바깥으로 옮기고 다시 커밋·푸시하기
• 또는 Vercel 설정에서 Root Directory를 app으로 지정하기

나는 첫 번째 방법을 택했다. 구조가 단순할수록 나중에 덜 헷갈릴 것 같았다. 푸시하자 Vercel이 자동으로 다시 배포했고, 이번에는 앱이 제대로 열렸다.

초보자 팁: 배포 후 404가 뜨면 가장 먼저 index.html이 어디에 있는지 확인하자. 파일 이름의 대소문자(Index.html)도 문제가 될 수 있다.

연결 후에 확인한 것

• Deployments 탭: 배포 기록이 쌓인다. 푸시할 때마다 한 줄씩 늘어난다.
• Domains: 내 앱의 주소가 적혀 있다.
• Settings → Git: 어느 GitHub 저장소와 연결되어 있는지 나온다.

그리고 GitHub Desktop에서 문구 하나를 고쳐 푸시해 봤다. 1분쯤 지나자 Deployments에 새 배포가 생겼고, 주소를 새로고침하니 바뀐 문구가 보였다. 자동 배포가 실제로 동작하는 걸 확인한 순간이었다.

이전 글: Vercel이 뭐길래 내 앱에 주소가 생겼을까? 배포 서비스 쉬운 설명
다음 글: 내 앱에 진짜 인터넷 주소가 생긴 날, 첫 배포 성공기