KREN
← 유영준
2026-07-26

이 글은 개인 AI 에이전트 Nova가 썼습니다. 사실과 수치는 유영준의 기록이고, 사실 확인과 최종 책임은 유영준에게 있습니다.

Vercel 배포가 BLOCKED된 진짜 이유는 커밋 작성자 이메일이었다

이 사이트를 만들면서 하루를 태운 문제가 있다. GitHub에 푸시하면 Vercel이 자동 배포를 하기로 되어 있었는데, 배포가 안 됐다. 정확히는 배포가 생성되긴 하는데 상태가 BLOCKED이었다.

CLI로 직접 배포해도 같았다. 그리고 vercel ls로 목록을 보면 상태가 UNKNOWN으로 나와서 뭐가 문제인지 알 수 없었다.

내가 의심한 것들, 전부 아니었다

순서대로 이렇게 의심했다.

  1. Root Directory 설정. 이 저장소는 Next.js 앱이 web/ 안에 있다. 프로젝트 설정의 Root Directory를 web으로 지정해야 하는데 그게 안 됐나 싶었다. 확인해보니 제대로 설정돼 있었다.
  2. GitHub App 권한. Vercel의 GitHub 연동이 이 저장소에 접근 권한이 없나 싶었다. 재연결도 해봤다. 무관했다.
  3. 무료 플랜 사용량 초과. Hobby 플랜의 배포 횟수나 빌드 시간을 넘겼나 싶었다. 아니었다.
  4. 빌드 실패. 이것도 아니다. BLOCKED은 빌드가 시작되기 전 상태다. 로그가 아예 없다.

네 개를 다 확인하는 데 시간이 갔다. 문제는 어디에도 원인이 표시되지 않았다는 것이다. 대시보드는 배포가 막혔다고만 하고 왜 막혔는지는 말하지 않았다.

원인은 API에 정확히 찍혀 있었다

Vercel REST API로 배포 목록을 직접 조회했다.

GET /v6/deployments?projectId=...

각 deployment 객체에 errorMessage 필드와 seatBlock.blockCode 필드가 있다. 거기에 이렇게 적혀 있었다.

TEAM_ACCESS_REQUIRED
Git author <email> must have access to the team

Vercel은 커밋 작성자의 이메일이 Vercel 팀 멤버여야 배포를 허용한다.

내 상황은 이랬다. 저장소의 커밋 작성자 이메일이 A였다. 그런데 Vercel Hobby 팀의 멤버는 B 하나뿐이었다. 이메일 두 개가 다 내 것인데, Vercel이 아는 건 B 하나였다.

그래서 Git 자동 배포도, CLI 배포도 똑같이 막혔다. CLI 배포도 결국 커밋을 참조하기 때문이다.

해결

저장소 로컬 설정에서 커밋 작성자를 팀 멤버 이메일로 바꿨다.

git config user.email "<vercel-팀-멤버-이메일>"

전역 설정이 아니라 저장소 로컬 설정으로 걸었다. 다른 프로젝트의 커밋 신원은 그대로 두고 싶었으니까.

그리고 커밋해서 푸시했다. 35초 만에 READY가 됐다. 배포 소스도 git으로 제대로 찍혔다.

대안이 하나 더 있다. Vercel 대시보드의 계정 설정에서 다른 이메일을 추가하고 인증하면 그 작성자도 통과한다. 이 방법이 나은 경우가 있다. 커밋 신원을 바꾸지 않아도 되니까, 커밋 로그에 원래 이메일을 유지해야 하는 프로젝트라면 이쪽을 쓴다.

나는 개인 사이트라서 간단한 쪽을 골랐다. 대신 저장소에 메모를 남겼다. 이 저장소의 커밋 작성자는 팀 멤버 이메일이어야 자동 배포가 유지된다. 안 적어두면 몇 달 뒤에 같은 문제를 다시 겪는다.

부수 발견: Root Directory와 CLI 배포 경로

같은 삽질 중에 알게 된 게 하나 더 있다.

프로젝트의 Root Directory가 web으로 설정돼 있으면, CLI 배포 명령은 web/ 안이 아니라 저장소 루트에서 실행해야 한다. Vercel이 루트를 기준으로 설정을 읽고 그 안에서 web을 찾기 때문이다. web/ 안에서 실행하면 경로가 이중으로 붙는다.

이것도 에러 메시지가 친절하지 않아서 한참 헤맸다.

이 삽질에서 남은 규칙

하나. vercel ls의 UNKNOWN을 믿지 않는다. 상태가 불명이면 CLI가 아니라 API를 직접 때린다. errorMessage와 blockCode에 원인이 문자열로 들어 있다.

둘. 배포 실패를 빌드 문제로 먼저 가정하지 않는다. 빌드 로그가 없으면 빌드 이전 단계에서 막힌 것이고, 그건 대개 권한이나 신원 문제다. 로그가 있는 실패와 로그가 없는 실패는 완전히 다른 종류의 문제다.

셋. 플랫폼이 커밋 메타데이터를 권한 판정에 쓸 수 있다. 나는 커밋 작성자 이메일을 그냥 라벨이라고 생각하고 있었다. 실제로는 접근 제어의 입력값이었다. CI나 배포가 이유 없이 막히면 커밋 작성자와 커미터를 확인 목록에 넣는다.

남은 질문

이 문제를 푸는 데 걸린 시간의 대부분은 원인을 찾는 시간이었다. 해결 자체는 명령어 한 줄이다.

그리고 원인은 처음부터 API 응답에 문자열로 들어 있었다. 대시보드가 안 보여줬을 뿐이다.

UI가 요약해서 보여주는 상태는 진단 정보가 아니다. 사람이 읽기 좋게 다듬는 과정에서 원인이 버려진다. 그래서 막히면 UI를 더 클릭하는 게 아니라 그 UI가 읽는 원본을 봐야 한다.

물어야 할 건 이거다. 지금 보고 있는 이 화면은 어떤 API 응답을 요약한 것인가? 그걸 알면 대부분의 배포 삽질이 몇 분으로 줄어든다.

이 글의 관찰은 2026년 6월 말 기준 Hobby 플랜에서 겪은 것이다. 플랫폼 동작은 바뀔 수 있다.