vercel github 연동 오류, 권한 재설정만 해도 풀리는 경우가 많습니다

vercel github 연동 오류는 대부분 GitHub App 권한, 연결된 저장소 범위, 기본 브랜치 설정이 어긋나서 생깁니다. 먼저 Vercel의 Git Integration 권한을 다시 확인하고, 프로젝트가 바라보는 Repository와 Production Branch가 실제 배포하려는 브랜치와 같은지 맞추는 것이 빠릅니다.

GitHub 권한과 Vercel Git 설정을 먼저 대조해 보세요.

Cursor, Claude Code, Codex로 만든 Next.js나 Vite 프로젝트를 GitHub에 올린 뒤 Vercel에서 “왜 자동 배포가 안 되지?” 하고 막히는 상황이 흔합니다. 코드 문제가 아니라 연결 설정 문제인 경우가 많으니, 아래 순서대로 보면 불필요한 빌드 수정에 시간을 쓰지 않을 수 있습니다.

먼저 5분 점검
GitHub App 권한 → Vercel 프로젝트 Git 설정 → 브랜치/루트 디렉터리 순서로 확인해 보세요.

가능성 높은 원인부터 확인하기

1. GitHub App이 해당 저장소를 볼 권한이 없습니다

Vercel은 일반적으로 GitHub OAuth가 아니라 Vercel GitHub App 설치 권한을 통해 저장소에 접근합니다. GitHub에서 “All repositories”가 아니라 “Only select repositories”로 설치했다면, 새로 만든 저장소가 빠져 있을 수 있습니다.

확인은 GitHub의 Settings → Applications → Installed GitHub Apps → Vercel → Configure에서 합니다. 배포하려는 Repository가 선택되어 있는지 보고, 빠져 있다면 추가합니다.

2. Vercel 프로젝트가 다른 Repo나 Branch를 보고 있습니다

저장소 이름을 바꾸었거나, 템플릿을 복제한 뒤 새 프로젝트로 옮긴 경우 자주 생깁니다. Vercel Dashboard에서 해당 프로젝트의 Settings → Git을 열어 연결된 Repository와 Production Branch를 확인합니다.

예를 들어 일반적인 상황으로, main 브랜치에 코드를 push했는데 Vercel의 Production Branch가 master로 남아 있으면 자동 배포가 기대대로 시작되지 않을 수 있습니다. 이때는 브랜치를 맞추거나, 실제 사용하는 브랜치로 push해야 합니다.

3. 모노레포 루트 디렉터리와 빌드 설정이 맞지 않습니다

AI 코딩 에이전트가 apps/web, frontend, client 같은 하위 폴더에 앱을 생성하는 경우가 있습니다. 이때 Vercel의 Root Directory가 저장소 루트로 남아 있으면 프레임워크 감지나 빌드 명령이 어긋날 수 있습니다.

Vercel의 프로젝트 설정에서 Root Directory, Build Command, Output Directory를 확인하세요. Next.js라면 보통 프레임워크 프리셋이 자동 감지되지만, 구조가 특이하면 직접 지정해야 합니다.

표준 해결 절차: 권한부터 배포 트리거까지

  1. GitHub App 권한 재확인: GitHub에서 Vercel 앱이 대상 저장소에 접근 가능한지 확인합니다.
  2. Vercel Git 연결 확인: Vercel Project Settings의 Git 항목에서 Repository와 Production Branch를 맞춥니다.
  3. 루트 디렉터리 확인: 앱이 하위 폴더에 있다면 Root Directory를 실제 앱 폴더로 지정합니다.
  4. 환경 변수 확인: GitHub 연동은 되었지만 빌드가 실패한다면 Vercel의 Environment Variables가 빠졌는지 봅니다.
  5. 새 배포 트리거: 설정을 고친 뒤 새 커밋을 push하거나 Vercel Dashboard에서 Redeploy를 실행합니다.

CLI로 프로젝트 연결을 다시 확인해야 하는 상황이라면 공식 Vercel CLI를 사용할 수 있습니다. 표준 명령은 다음처럼 시작합니다.

npx vercel login
npx vercel link
npx vercel --prod

단, CLI 배포가 성공해도 GitHub 자동 배포 설정이 고쳐진 것은 아닐 수 있습니다. 자동 배포 문제라면 Dashboard와 GitHub App 권한을 같이 확인해야 합니다.

어떤 방식으로 해결할지 빠르게 고르기

상황 먼저 볼 곳 추천 조치
저장소가 Vercel Import 목록에 안 보임 GitHub Installed GitHub Apps Vercel 앱의 Repository access에 저장소 추가
push했는데 자동 배포가 안 시작됨 Vercel Project Settings → Git 연결 Repo와 Production Branch 확인 후 새 커밋 push
배포는 시작되지만 빌드 실패 Root Directory, Build Command, Env 앱 폴더와 환경 변수 누락 여부 점검
급하게 배포만 필요함 Vercel CLI npx vercel --prod로 배포 후 Git 연동은 별도 수정

이런 분에게는 이 순서를 추천합니다

AI 코딩 도구로 만든 첫 프로젝트라면

코드부터 고치지 말고 GitHub 권한 → 브랜치 → Root Directory 순서로 보세요. Cursor나 Claude Code가 만든 프로젝트는 폴더 구조가 예상과 다를 수 있어, Vercel이 앱 위치를 잘못 잡는 경우가 있습니다.

팀/조직 저장소를 쓰는 경우라면

개인 계정 저장소보다 조직 저장소가 한 단계 더 복잡합니다. GitHub Organization의 권한 정책, SSO, Vercel Team 권한이 맞물릴 수 있습니다. 이 경우 개인 GitHub 계정이 아니라 조직에 설치된 Vercel GitHub App 설정을 확인해야 합니다.

해결됐는지 확인하는 법

설정을 고친 뒤에는 Vercel Deployments 화면에서 새 배포가 생성되는지 확인합니다. GitHub 커밋과 연결된 배포가 보이고, GitHub의 Checks에 Vercel 관련 상태가 표시되면 연동은 대체로 정상 흐름에 들어온 것입니다.

그래도 안 된다면 다음을 추가로 봅니다. 저장소가 private인지, fork에서 온 Pull Request인지, 보호 브랜치 규칙이 있는지, GitHub 조직에서 외부 앱 사용을 제한하는지 확인하세요. 세부 UI와 권한 이름은 바뀔 수 있으니 공식 문서 기준으로 보는 것이 안전합니다.

FAQ

GitHub 저장소 이름을 바꾸면 Vercel 연결이 깨지나요?

항상 깨진다고 단정할 수는 없지만, 저장소 이동·이름 변경 후에는 Project Settings의 Git 연결 상태를 확인하는 것이 좋습니다. 자동 배포가 멈췄다면 재연결이 필요할 수 있습니다.

Vercel에서 GitHub 계정을 다시 로그인하면 해결되나요?

로그인만으로 해결되지 않는 경우가 많습니다. 핵심은 계정 로그인보다 GitHub App이 대상 저장소에 접근할 수 있는지입니다.

환경 변수 때문에도 vercel github 연동 오류처럼 보일 수 있나요?

연동 자체가 아니라 빌드 실패인데, 사용자 입장에서는 같은 문제처럼 보일 수 있습니다. 배포가 생성된다면 연동보다 빌드 로그와 Environment Variables를 먼저 보세요.

지금 바로 할 체크리스트

  • GitHub에서 Vercel 앱이 대상 저장소에 설치되어 있는지 확인합니다.
  • Vercel 프로젝트의 Repository와 Production Branch를 실제 배포 브랜치와 맞춥니다.
  • 모노레포라면 Root Directory가 앱 폴더를 가리키는지 봅니다.
  • 설정 변경 후 새 커밋 push 또는 Redeploy로 배포를 다시 트리거합니다.

이 순서로 보면 권한 문제와 빌드 문제를 분리할 수 있습니다. 다음 단계는 Vercel의 Deployments 화면에서 실패 지점이 “연동 전”인지 “빌드 중”인지 구분하는 것입니다.

오늘도, 코딩할 용기.

관련 링크

글쓴이 용기

15년차 백엔드 개발자, 바이브코딩으로 개발 방식 전환 중. Claude Code·Codex 실사용 후기와 빌더 일지를 씁니다.

지식창고