Vercel 자동배포가 Deploy 단계에서 멈추는 문제

GitHub Actions로 main 브랜치에 push하면 Vercel에 자동배포되도록 세팅했다. 워크플로우는 vercel pull → vercel build → vercel deploy 순서였는데, Actions 탭에서 보니까 Deploy 단계에서 계속 "In progress" 상태로 멈춰 있었다.

증상

- name: Pull Vercel environment
  run: npx vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

이 단계가 끝나지 않고 계속 돌고 있었다. 로컬에서는 잘 되는데 Actions에서만 걸리니까 처음엔 원인을 못 찾았다.

원인

vercel pull 명령어가 어느 프로젝트에 연결할지 모르는 상태에서 인터랙티브 프롬프트를 띄우려고 기다리고 있던 것이다. 로컬에서는 npx vercel link로 이미 연결이 돼있어서 .vercel/project.json이 있지만, Actions 환경에서는 그게 없다.

VERCEL_ORG_ID와 VERCEL_PROJECT_ID를 환경변수로 주면 Vercel CLI가 자동으로 프로젝트를 찾아가는데, 그걸 빠뜨렸다.

해결

workflow 파일 상단에 env 블록 추가:

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

그리고 GitHub Secrets에서 두 값을 추가해줬다. 값은 로컬에서 npx vercel link 실행 후 생성되는 .vercel/project.json에서 확인 가능하다.

정리

CI/CD 세팅할 때 CLI 도구들이 어떤 환경변수를 보는지 먼저 확인하는 습관이 필요하다는 걸 배웠다.