목표#
- GitHub 계정으로 Vercel에 가입합니다.
- Vercel이 GitHub 저장소에 접근할 수 있도록 Vercel GitHub App을 설치하고, 접근할 저장소 범위를 정합니다.
- 나중에 권한을 바꾸거나 연결을 해제하는 방법을 알아 둡니다.
사전 조건#
- 1장을 마쳐서 GitHub에 배포할 저장소(예:
my-app)가 올라가 있습니다. - 브라우저에서 배포할 저장소를 가진 GitHub 계정으로 로그인되어 있습니다.
1. Vercel과 GitHub는 어떻게 연결되나요?#
GitHub와 Vercel 사이에는 두 가지 연결이 생깁니다. 이 장의 대부분은 이 두 가지를 설정하는 과정입니다.
| 연결 | 무엇을 하나요? | GitHub에서 확인하는 곳 |
|---|---|---|
| 로그인 연결 (OAuth 앱) | GitHub 계정으로 Vercel에 로그인 | Settings → Applications → Authorized OAuth Apps |
| Vercel GitHub App | 저장소 코드를 읽고, push·PR을 감지하고, PR에 배포 결과를 남김 | Settings → Applications → Installed GitHub Apps |
로그인 연결만 하고 GitHub App을 설치하지 않으면 Vercel에서 저장소 목록이 보이지 않습니다. 저장소를 배포하려면 GitHub App 설치가 반드시 필요합니다.
2. Vercel 가입하기#
- https://vercel.com/signup 에 접속합니다.
사용 목적을 선택합니다.
- Hobby: 개인·비상업적 프로젝트용 무료 요금제. 이 매뉴얼은 Hobby 기준으로 설명합니다.
- Pro: 회사·상업적 프로젝트용 유료 요금제. 체험 기간이 제공될 수 있습니다.
- 이름(계정에 표시될 이름)을 입력합니다.
- Continue with GitHub를 누릅니다.
- GitHub 권한 승인 화면이 나오면 계정 이름이 맞는지 확인하고 Authorize Vercel을 누릅니다.
- 추가 본인 확인(휴대전화 인증 등)을 요청하면 안내에 따라 진행합니다.
- 가입이 끝나면 Vercel 대시보드로 이동합니다.
상업적 용도인데 Hobby를 선택하면 이용 약관 위반이 될 수 있습니다. 회사 업무나 수익이 나는 프로젝트라면 Vercel 요금제 안내와 Fair Use 정책을 확인하세요.
이미 이메일로 Vercel에 가입했다면 새로 가입하지 말고, 대시보드에서 계정 Settings → Authentication(로그인 연결 메뉴)에 들어가 GitHub를 연결하세요.
3. Vercel GitHub App 설치하기#
가입 직후 새 프로젝트를 만들려고 하면 GitHub 저장소를 가져오기 위해 GitHub App 설치를 안내합니다.
Vercel 대시보드에서 Add New… → Project를 누릅니다.
- 가입 직후라면 바로 Import Git Repository 화면이 보일 수도 있습니다.
- Import Git Repository 영역에서 Install (또는 Continue with GitHub) 버튼을 누릅니다.
GitHub 화면으로 이동하면 앱을 설치할 계정 또는 조직(Organization) 을 선택합니다.
- 개인 저장소라면 본인 계정을 선택합니다.
접근할 저장소 범위를 선택합니다.
- All repositories: 현재와 앞으로 만들 모든 저장소에 접근
- Only select repositories: 선택한 저장소에만 접근 → 목록에서
my-app을 선택
- 요청하는 권한 목록을 확인하고 Install을 누릅니다.
- Vercel로 돌아오면 Import Git Repository 목록에 저장소가 표시됩니다.
보안상 Only select repositories를 권장합니다. Vercel이 필요한 저장소에만 접근하게 되고, 저장소가 늘어나면 언제든 추가할 수 있습니다. (아래 4단계 참고)
이 장에서는 저장소 목록이 보이는 것까지만 확인합니다. Import 버튼을 눌러 실제로 배포하는 과정은 3장에서 진행합니다.
조직(Organization) 저장소를 연결할 때#
회사나 동아리 등 GitHub 조직 소유 저장소는 설치 과정이 다를 수 있습니다.
- 조직의 Owner 권한이 있으면 바로 설치할 수 있습니다.
- Owner가 아니면 설치 대신 요청(Request) 이 보내지고, 조직 Owner가 승인해야 저장소가 보입니다.
Hobby 요금제에서는 조직 소유 Private 저장소를 배포하는 데 제한이 있을 수 있습니다. 조직 저장소를 배포할 계획이라면 먼저 Vercel GitHub 연동 문서에서 요금제별 지원 범위를 확인하세요.
4. 저장소 접근 권한 바꾸기 (나중에 저장소 추가하기)#
새 저장소를 만들었는데 Vercel 목록에 보이지 않는다면, GitHub App의 저장소 범위에 추가해야 합니다.
방법 A. Vercel에서 이동하기#
- Vercel Add New… → Project 화면으로 갑니다.
- 저장소 목록 아래의 Adjust GitHub App Permissions 링크를 누릅니다.
- GitHub 화면에서 Repository access 범위를 수정하고 Save를 누릅니다.
방법 B. GitHub에서 직접 바꾸기#
- GitHub 오른쪽 위 프로필 사진 → Settings로 갑니다.
- 왼쪽 메뉴에서 Applications를 누르고 Installed GitHub Apps 탭을 선택합니다.
- Vercel 옆의 Configure를 누릅니다.
- Repository access에서 저장소를 추가하거나 빼고 Save를 누릅니다.
조직 저장소라면 개인 Settings가 아니라 조직 페이지 → Settings → GitHub Apps에서 관리합니다.
5. 연결 해제하기 (필요할 때만)#
Vercel을 더 이상 쓰지 않거나 연결을 처음부터 다시 하고 싶을 때 사용합니다.
| 하고 싶은 일 | 위치 |
|---|---|
| 저장소 접근 끊기 | GitHub Settings → Applications → Installed GitHub Apps → Vercel → Configure 하단의 Uninstall |
| GitHub 로그인 연결 끊기 | GitHub Settings → Applications → Authorized OAuth Apps → Vercel → Revoke |
GitHub App을 제거하면 연결된 모든 Vercel 프로젝트의 자동 배포가 멈춥니다. 이미 배포된 사이트는 그대로 유지되지만, 이후 push가 반영되지 않습니다.
확인 방법#
문제 해결#
저장소 목록에 내 저장소가 보이지 않아요#
- GitHub App의 저장소 범위에 해당 저장소가 포함되어 있는지 확인합니다. (4단계 참고)
- 목록 위쪽의 계정 선택 드롭다운에서 저장소를 가진 계정 또는 조직이 선택되어 있는지 확인합니다.
- 조직 저장소라면 조직 Owner가 설치 요청을 승인했는지 확인합니다.
- 방금 권한을 바꿨다면 Vercel 페이지를 새로고침합니다.
다른 GitHub 계정으로 연결되었어요#
브라우저에 다른 GitHub 계정이 로그인된 상태에서 가입하면 그 계정으로 연결됩니다.
- Vercel에서 로그아웃합니다.
- https://github.com 에서 로그아웃한 뒤 배포할 저장소가 있는 계정으로 다시 로그인합니다.
- Vercel에 Continue with GitHub로 다시 로그인합니다.
하나의 GitHub 계정은 보통 하나의 Vercel 계정에만 로그인 연결할 수 있습니다. 이미 다른 Vercel 계정에 연결된 GitHub 계정이라는 메시지가 나오면, 기존 Vercel 계정의 로그인 연결을 먼저 해제하세요.
GitHub에서 Request 버튼만 보이고 설치가 안 돼요#
조직 저장소에 대해 Owner 권한이 없는 경우입니다. 요청을 보낸 뒤 조직 Owner에게 승인을 부탁하세요. 승인 전까지는 해당 조직의 저장소가 Vercel 목록에 나타나지 않습니다.
가입 중 휴대전화 인증이 계속 실패해요#
번호 형식(국가 코드 +82 선택, 맨 앞 0 제외 여부)을 확인하고, 계속 실패하면 Vercel 지원 센터에 문의하세요.
다음 단계#
➡️ 3장. 프로젝트 Import와 첫 배포: 연결한 저장소를 Vercel 프로젝트로 가져와 첫 배포를 진행합니다.