배포 매뉴얼
전체 목차06 · Preview 배포와 PR 흐름
Chapter 06

Preview 배포와 PR 흐름

최종 확인일 2026-11-04 읽는 시간 약 8분 운영 · 협업과 도메인

목표#

  • 브랜치와 Pull Request(PR)를 만들 때 Vercel이 자동으로 Preview 배포를 만드는 흐름을 익힙니다.
  • PR에 달린 미리보기 URL로 변경 사항을 확인하고, main에 병합해 Production에 반영합니다.
  • 문제가 생겼을 때 이전 배포로 되돌리는(롤백) 방법과 재배포 방법을 알아 둡니다.

사전 조건#

  • 3장에서 main 브랜치가 Production으로 배포되어 있습니다.
  • 기본 Git 명령(add, commit, push)을 사용할 수 있습니다.

1. 브랜치별 배포 규칙#

push한 곳배포 종류접속 주소영향
main (Production 브랜치)Productionmy-app.vercel.app실제 사용자에게 바로 반영
그 외 모든 브랜치Preview브랜치 URL, 배포별 고유 URL운영 사이트에 영향 없음
PR이 열린 브랜치Preview + PR 코멘트PR 코멘트의 링크운영 사이트에 영향 없음
참고

Production 브랜치는 기본적으로 저장소의 기본 브랜치(main)입니다. 바꾸려면 프로젝트 Settings → Environments → Production의 브랜치 설정을 수정합니다.


2. Preview 배포 흐름 따라 하기#

브랜치 생성
수정 후 push
Preview 배포자동 생성
PR 생성
미리보기 확인PR 코멘트 링크
문제 없나요?
예 → main에 MergeProduction 배포가 자동으로 시작됩니다

2-1. 새 브랜치 만들고 push하기#

  1. main을 최신 상태로 맞춥니다.

    bash
    git switch main
    git pull
  2. 작업용 브랜치를 만듭니다.

    bash
    git switch -c feature/new-header
  3. 코드를 수정하고 커밋합니다.

    bash
    git add .
    git commit -m "헤더 디자인 변경"
  4. 브랜치를 GitHub에 push합니다. 새 브랜치는 처음 한 번 -u origin <브랜치>가 필요합니다.

    bash
    git push -u origin feature/new-header
  5. Vercel Deployments 탭에 feature/new-header 브랜치의 Preview 배포가 생기는지 확인합니다.

2-2. Pull Request 만들기#

  1. GitHub 저장소에 접속하면 상단에 Compare & pull request 버튼이 나타납니다. 누릅니다.

    • 버튼이 없다면 Pull requests → New pull request에서 base: main ← compare: feature/new-header를 선택합니다.
  2. 제목과 설명을 입력하고 Create pull request를 누릅니다.
  3. 잠시 후 PR에 Vercel 봇의 코멘트가 달립니다. 배포 상태와 Preview 링크가 들어 있습니다.
  4. PR 하단의 체크 목록(Checks)에도 Vercel 배포 결과가 표시됩니다.

2-3. 미리보기 확인하기#

  1. Vercel 코멘트의 Visit Preview 링크를 누릅니다.
  2. 변경 사항이 의도대로 동작하는지 확인합니다.
  3. 수정할 부분이 있으면 같은 브랜치에 다시 커밋·push합니다. PR의 Preview가 자동으로 갱신됩니다.
중요

Preview URL은 기본적으로 Vercel 접속 보호(Deployment Protection) 가 걸려 있어 Vercel에 로그인한 팀 구성원만 볼 수 있습니다. 외부 사람에게 미리보기를 보여 주려면 프로젝트 Settings → Deployment Protection에서 설정을 조정하거나 공유 링크 기능을 사용하세요.

팁

Preview 화면에는 Vercel Toolbar가 표시될 수 있습니다. 툴바의 Comments 기능으로 화면의 특정 위치에 피드백을 남길 수 있습니다.

2-4. main에 병합해 Production에 반영하기#

  1. PR 화면에서 Merge pull request → Confirm merge를 누릅니다.
  2. main에 새 커밋이 생기면서 Production 배포가 자동으로 시작됩니다.
  3. Vercel Deployments 탭에서 Production 배포가 Ready가 되면 my-app.vercel.app에 반영된 것입니다.
  4. 로컬도 최신 상태로 맞추고, 다 쓴 브랜치는 정리합니다.

    bash
    git switch main
    git pull
    git branch -d feature/new-header
팁

GitHub 저장소 Settings → Branches에서 main에 브랜치 보호 규칙을 만들고, Vercel 배포 체크를 필수(Require status checks to pass)로 지정하면 빌드가 실패한 PR은 병합할 수 없게 막을 수 있습니다.


3. Production 재배포와 롤백#

3-1. Redeploy (재배포)#

코드는 그대로 두고 다시 배포합니다. 환경 변수나 빌드 설정을 바꾼 뒤에 사용합니다.

  1. Deployments 탭에서 대상 배포 오른쪽의 ⋯를 누릅니다.
  2. Redeploy를 선택합니다.
  3. 빌드 캐시 때문에 문제가 의심되면 Use existing Build Cache 옵션을 끄고 재배포합니다.

3-2. Instant Rollback (즉시 롤백)#

새 Production 배포에 문제가 있으면 이전 Production 배포로 바로 되돌릴 수 있습니다. 다시 빌드하지 않으므로 몇 초 만에 끝납니다.

  1. Deployments 탭에서 정상이던 이전 Production 배포를 찾습니다.
  2. ⋯ → Instant Rollback을 누르고 확인합니다.
  3. my-app.vercel.app이 즉시 이전 배포를 가리키게 됩니다.
주의

롤백 후에는 Vercel이 자동 배포를 일시 중단할 수 있습니다. 문제를 고친 뒤에는 새 배포를 Promote(아래)하거나 프로젝트 화면의 안내에 따라 자동 배포를 다시 켜야 이후 push가 Production에 반영됩니다.

참고

Hobby 요금제는 바로 직전 Production 배포로만 롤백할 수 있는 등 제한이 있을 수 있습니다.

3-3. Promote (Preview를 Production으로 승격)#

이미 확인을 마친 Preview 배포를 그대로 Production으로 올릴 수도 있습니다.

  1. Deployments 탭에서 대상 Preview 배포의 ⋯ → Promote를 누릅니다.
  2. 확인하면 Production 도메인이 해당 배포를 가리킵니다.
중요

Promote는 GitHub의 main 브랜치를 바꾸지 않습니다. 나중에 main에 다른 커밋이 push되면 그 커밋이 다시 Production이 됩니다. 장기적으로는 PR을 병합하는 방식을 기본으로 쓰세요. 또한 Preview용 환경 변수로 빌드된 배포라면 Production 값으로 다시 빌드될 수 있습니다.


확인 방법#

문제 해결#

증상원인과 해결
PR에 Vercel 코멘트가 달리지 않음GitHub App 권한에 저장소가 포함되었는지 확인 (2장), 프로젝트 Settings → Git 연결 상태 확인
Preview 링크를 열면 Vercel 로그인 화면이 나옴정상 동작(Deployment Protection). 외부 공유가 필요하면 보호 설정 조정
Preview에서 API가 동작하지 않음Preview 환경에 환경 변수가 없음 → 5장
병합했는데 Production이 안 바뀜롤백 후 자동 배포가 멈춘 상태인지 확인, Production 브랜치 설정 확인

다음 단계#

➡️ 7장. 커스텀 도메인: my-app.vercel.app 대신 내가 가진 도메인으로 서비스합니다.

참고 자료#