git push 했는데 배포가 안 됐다 — Vercel 배포를 끝까지 확인하는 법

한 줄짜리 카피 수정을 커밋하고 git push origin main을 날렸습니다. Vercel을 쓰고 있으니 당연히 자동 배포가 돌았겠거니 하고 프로덕션 사이트를 열었는데 — 바뀐 게 없었습니다.

캐시 문제인가? 시크릿 창에서 열어봐도 그대로. 이때부터 30분짜리 삽질이 시작됐고, 결론은 허무했습니다. 이 프로젝트는 애초에 Vercel Git 연동이 안 되어 있었습니다. 푸시해봤자 Vercel은 아무것도 모르는 상태였던 거죠.

오늘은 이 삽질 과정에서 정리한 "배포를 끝까지 확인하는 법"을 공유합니다. Vercel 기준이지만, 어떤 배포 파이프라인에도 통하는 원칙입니다.

배경: 무엇을 배포하려 했나

배포하려던 건 아주 작은 커밋이었습니다. 랜딩 검색바의 지역 라벨을 바꾸는 작업이요.

-    searchCountry: '호주 · 뉴질랜드',
+    searchCountry: '전 세계',

서비스 포지셔닝을 특정 지역에서 글로벌로 넓히는 중이라, 히어로 검색바에 박혀 있던 '호주 · 뉴질랜드' 라벨이 계속 걸렸습니다. 라벨을 아예 없앨 수도 있었지만, 그러면 검색바 레이아웃이 허전해집니다. '전 세계'로 바꾸면 레이아웃은 그대로 유지하면서 포지셔닝 메시지는 오히려 강해집니다. 영어 로케일도 Australia · NZ → Worldwide로 맞췄습니다.

한 가지 덤: UI 카피만 바꾸고 끝이 아니었습니다. 이 서비스에는 AI 고객지원 챗봇이 있는데, 챗봇이 참조하는 지식 문서에도 지역·직군 편향 문구가 남아 있었습니다.

-... 호주·뉴질랜드 등 해외 IT 채용에 특히 유용합니다.
+... 국가·직군에 관계없이 해외 취업 전반에 활용할 수 있습니다.

UI에서 '전 세계'라고 해놓고 챗봇이 "호주·뉴질랜드 IT 채용에 특히 유용해요"라고 답하면 이상하겠죠. AI 챗봇의 지식 문서도 서비스 카피의 일부입니다. 포지셔닝을 바꿀 땐 화면에 보이는 텍스트뿐 아니라 AI가 읽는 텍스트까지 grep 해봐야 합니다.

여기까지는 순조로웠습니다. 문제는 배포부터였습니다.

Step 1: "배포됐겠지"를 의심하기 — `vercel ls`

푸시 후 사이트가 안 바뀌었을 때, 가장 먼저 확인할 것은 최신 배포가 언제 만들어졌는가입니다.

vercel ls

출력을 보고 바로 알았습니다.

Age     Deployment                              Status    Environment
7h      https://jobradar-xxxx.vercel.app        ● Ready   Production
9h      https://jobradar-yyyy.vercel.app        ● Ready   Production
...

방금 푸시했는데 최신 배포가 7시간 전. 즉, 내 푸시는 배포를 전혀 트리거하지 않았습니다.

배포 이력을 훑어보니 전부 CLI에서 올라간 배포였습니다. 이 프로젝트는 처음 셋업할 때 vercel CLI로 배포를 시작했고, GitHub 저장소를 Vercel 프로젝트에 연결하는 단계를 건너뛰었던 겁니다. Git 연동이 없으면 push는 그냥 GitHub에 코드가 올라가는 것으로 끝입니다. Vercel은 웹훅을 받을 일이 없으니 아무것도 하지 않죠.

해결은 간단합니다. 직접 프로덕션 배포를 실행하면 됩니다.

vercel --prod

교훈 1: "푸시했다 = 배포됐다"는 파이프라인이 그렇게 구성되어 있을 때만 참입니다. 자동 배포는 기본값이 아니라 설정의 결과입니다.

Step 2: 배포가 "진짜" 됐는지 확인 — `vercel inspect`

vercel --prod가 성공 메시지를 뱉었다고 끝이 아닙니다. 두 가지를 더 확인해야 합니다.

배포 상태가 Ready인가 (빌드가 실제로 성공했는가)
커스텀 도메인 alias가 이 배포를 가리키는가

vercel inspect https://jobradar-zzzz.vercel.app

출력에서 볼 것은 두 줄입니다.

status      ● Ready
aliases     matchda.com, www.matchda.com

Vercel에서 배포 URL과 서비스 도메인은 별개입니다. 배포는 성공했는데 alias가 옛 배포에 붙어 있으면, 사용자는 여전히 옛 버전을 봅니다. vercel --prod는 보통 alias까지 옮겨주지만, "보통 그렇다"와 "확인했다"는 다릅니다.

Step 3: 실제 서빙 내용까지 확인 — `curl`

마지막 단계는 배포 시스템의 말을 믿지 않고, 실제 도메인이 서빙하는 HTML을 직접 확인하는 겁니다. 이번 변경은 텍스트 한 줄이라 grep 한 방이면 됩니다.

curl -sL https://matchda.com/ | grep "전 세계"

매치가 나오면 진짜 끝난 겁니다. 브라우저 새로고침보다 이게 나은 이유:

브라우저 캐시, 서비스 워커의 영향을 받지 않음
CDN이 실제로 내보내는 원본 응답을 확인
터미널에 남아서 "확인했다"는 기록이 됨

변경이 텍스트가 아니라면 상황에 맞게 응용하면 됩니다. API 변경이면 해당 엔드포인트를 curl, 스타일 변경이면 빌드 해시가 바뀌었는지 확인하는 식으로요.

배포 검증 3단계 요약

단계	명령어	확인할 것
1. 배포가 만들어졌나	`vercel ls`	최신 배포의 Age가 방금인지
2. 배포가 살아있고 연결됐나	`vercel inspect <url>`	`Ready` 상태 + 도메인 alias
3. 실제로 서빙되나	`curl -sL <domain> \| grep <변경내용>`	바뀐 내용이 응답에 있는지

셋 다 10초짜리 명령입니다. "됐겠지" 하고 넘어갔다가 나중에 발견하는 비용에 비하면 공짜나 다름없습니다.

트러블슈팅: 자주 헷갈리는 포인트

Q. push 했는데 vercel ls에 새 배포가 없다 → Git 연동이 안 된 프로젝트일 가능성이 큽니다. Vercel 대시보드의 프로젝트 Settings → Git에서 저장소가 연결되어 있는지 확인하세요. CLI로만 배포해온 프로젝트라면 이 상태일 수 있습니다. vercel --prod로 직접 배포하거나, Git 연동을 걸어서 자동 배포로 전환하세요.

Q. 배포는 Ready인데 사이트가 안 바뀌었다 → vercel inspect로 도메인 alias가 최신 배포에 붙어 있는지 확인하세요. alias가 맞다면 브라우저 캐시나 ISR/캐시 재검증 문제일 수 있으니 curl로 원본 응답을 확인하세요.

Q. 매번 이걸 다 기억할 자신이 없다 → 저도 그렇습니다. 그래서 마지막 교훈으로 이어집니다.

프로젝트별 함정은 기록해야 반복하지 않는다

이번 삽질의 원인은 기술이 아니라 기억이었습니다. "이 프로젝트는 Git 연동이 없어서 vercel --prod를 직접 실행해야 한다"는 사실을 몇 달 전의 나는 알고 있었을 겁니다. 오늘의 나는 몰랐죠.

그래서 배포를 마치고 가장 먼저 한 일은 코드 수정이 아니라 기록이었습니다. 프로젝트 메모리 문서(저는 CLAUDE.md와 메모리 폴더를 씁니다. README의 배포 섹션도 좋습니다)에 이렇게 남겼습니다.

## 배포 주의
- 이 프로젝트는 Vercel Git 연동 없음 — push만으로 배포되지 않음
- 배포: `vercel --prod` 직접 실행
- 배포 후 확인: `vercel ls` → `vercel inspect` → `curl | grep`

프로젝트마다 이런 "그 프로젝트만의 함정"이 하나씩 있습니다. 이 프로젝트는 배포 방식이었고, 다른 프로젝트에서는 특이한 환경변수 로딩 순서나 수동으로 돌려야 하는 마이그레이션일 수 있습니다. 공통점은 문서에 안 적으면 반드시 다시 밟는다는 것.

정리

오늘의 흐름을 한눈에:

텍스트 한 줄 수정 (지역 라벨 '호주 · 뉴질랜드' → '전 세계' + 챗봇 지식 문서 정리)
git push — 그리고 사이트가 안 바뀜
vercel ls로 최신 배포가 7시간 전임을 발견 → Git 연동이 없는 프로젝트였음
vercel --prod로 직접 배포
vercel inspect로 Ready 상태와 도메인 alias 확인
curl -sL https://matchda.com/ | grep "전 세계"로 실서빙 검증
프로젝트 문서에 배포 절차 기록

세 가지 교훈으로 요약하면:

푸시는 배포가 아니다. 자동 배포는 설정의 결과이지 기본값이 아니다.
배포는 실서빙 확인까지가 배포다. ls → inspect → curl 3단계면 충분하다.
프로젝트별 함정은 발견 즉시 문서에 남긴다. 미래의 나는 오늘의 나보다 기억력이 나쁘다.

여러분의 프로젝트는 push하면 정말 배포되나요? 확실하지 않다면, 지금 vercel ls 한 번 쳐보는 걸 추천합니다.