GitHub 연동 배포

저장소를 한 번 연결하면 push마다 자동 빌드·배포  |  공식 문서: Vercel for GitHub

참조 문서 URLvercel.com/docs/git · /git/vercel-for-github
문서 수집일2026년 6월 13일
전제Vercel 계정과 GitHub 계정이 있고, 배포할 코드가 GitHub 저장소에 있음 (없으면 ③ CLI/MCP 직접 배포 참고)

1. 동작 원리

Vercel for GitHub는 GitHub 저장소를 Vercel 프로젝트에 연결해 자동 배포하는 통합입니다. 한 번 연결하면 기본적으로 모든 push를 배포합니다(브랜치 push와 pull request 포함).

저장소 한 번 연결(Import)
   │
   ├── main 브랜치에 push / merge ─────▶ Production 배포 (실서비스 도메인 갱신)
   │
   └── 그 외 브랜치 push / PR 열기 ─────▶ Preview 배포 (고유 미리보기 URL + PR 자동 코멘트)

핵심은 "내가 빌드 명령을 직접 실행하지 않는다"는 점입니다. 코드를 GitHub에 올리는 행위(git push) 자체가 배포 트리거이고, 빌드는 Vercel의 서버에서 자동으로 일어납니다.

GitHub 연동: push가 일으키는 일 git push 또는 PR이 발생하면 어느 브랜치인지에 따라 흐름이 갈립니다. main 브랜치는 Production 배포로 이어져 커스텀 도메인이 갱신되고, 그 외 브랜치나 PR은 Preview 배포로 이어져 고유 미리보기 URL과 PR 자동 코멘트가 생성됩니다. 빌드는 Vercel 서버에서 자동으로 실행됩니다. GitHub 연동: push가 일으키는 일 git push (또는 PR) 어느 브랜치인가? main 그 외 브랜치 / PR Production 배포 → 커스텀 도메인 갱신 (실서비스 반영) Preview 배포 → 고유 미리보기 URL + PR 자동 코멘트 빌드는 Vercel 서버에서 자동 실행됩니다 — 직접 명령하지 않습니다
그림. git push 이후 브랜치에 따른 자동 분기
같은 브랜치에서 이전 커밋의 빌드가 진행 중일 때 새 push가 들어오면, 진행 중 빌드는 끝내고 그 사이 커밋은 건너뛴 뒤 가장 최신 커밋만 배포합니다(autoJobCancellation). 불필요한 빌드 낭비를 막는 기본 동작입니다.

2. 저장소 Import 절차

공식 흐름은 Add New… → Project → Import Git Repository입니다.

  1. Vercel 대시보드 우상단 Add New ▾ → Project(또는 New Project) 클릭
  2. 연결된 Git 계정에서 Vercel GitHub App에 접근 권한을 준(설치 범위에 포함된) 저장소가 표시됨 — 배포할 저장소 선택(Import). 원하는 저장소가 보이지 않으면 GitHub App 설치 화면의 Configure에서 그 저장소를 접근 범위에 추가하세요(아래 3절의 연결 자격 규칙도 함께 적용됩니다)
  3. 구성 페이지에서 다음을 확인·설정: 프로젝트 이름, Framework Preset(자동 감지), Root Directory, Build & Output 설정, Environment Variables
  4. Deploy 클릭 → 첫 빌드가 시작되고, 완료되면 라이브 URL 발급

아래는 Import 화면의 구조를 단순화한 예시입니다(실제 색·배치는 다를 수 있습니다).

vercel.com/new
Import Git Repository
▤ my-username/my-first-appImport
▤ my-username/portfolioImport
▤ my-username/study-notesImport
vercel.com/new/configure
Configure Project
Framework Preset
Next.js  ▾  (자동 감지됨)
Root Directory
./
Environment Variables
NEXT_PUBLIC_API_URL = ...
Deploy
대부분의 경우 Framework Preset이 자동 감지되어 빌드 명령·출력 폴더가 알아서 채워집니다. AI가 만든 Next.js 앱이면 보통 그대로 Deploy만 누르면 됩니다.

3. GitHub 권한

Vercel for GitHub 통합은 저장소를 빌드·배포·상태표시하기 위해 일정 권한을 요구합니다. 공식 문서가 명시하는 주요 Repository 권한:

권한용도(요약)
Contents코드 읽기(빌드 대상)
DeploymentsGitHub 내 배포 상태 표시
Pull Requests · Checks · Commit StatusesPR 코멘트·체크 표시
Web Hookspush 이벤트 수신(배포 트리거)
Metadata · Administration 등저장소 메타데이터·설치 관리

누가 연결할 수 있나

GitHub App 설치 시 "모든 저장소" 또는 "선택한 저장소만" 접근 범위를 고르는 화면이 나옵니다. 보안상 필요한 저장소만 선택하는 것을 권장합니다. (이 선택 UI의 세부 단계는 공식 문서 본문에 명시적으로 서술되어 있지 않아 GitHub 측 설치 화면 기준으로 안내합니다.)

4. 프로덕션 vs 프리뷰 브랜치

구분트리거결과
ProductionProduction 브랜치(보통 main)에 push / merge프로덕션 배포 생성 → 커스텀 도메인이 최신 배포로 갱신
Preview그 외 모든 브랜치 push, PR 열기고유 미리보기 URL 생성(프로덕션에 영향 없음)

Production 브랜치는 단 하나이고, 그 외 모든 브랜치는 미리보기로 배포됩니다. Production 브랜치 자동 선택 순서는 main → 없으면 master → 저장소 기본 브랜치입니다. 프로젝트 Settings → Environments → Production → Branch Tracking에서 변경할 수 있습니다.

5. PR 미리보기 코멘트

PR을 열면 Vercel이 그 변경에 대한 고유 미리보기 배포를 만들고, 그 URL을 PR에 자동으로 코멘트로 남깁니다. GitHub의 Deployments API로 배포 상태를 GitHub 안에서 보여 주고, GitHub Checks로 다른 서비스와도 연동됩니다.

PR 미리보기에서 합치면 프로덕션으로 가는 흐름 브랜치 생성, commit과 push, PR 열기, Preview 배포 생성과 봇 코멘트, Merge 후 Production 배포까지 5단계 가로 타임라인 다이어그램. PR 미리보기 → 합치면 프로덕션 1 브랜치 생성 2 commit & push 3 PR 열기 4 Preview 배포 생성 봇이 URL 코멘트 5 Merge → Production 배포 검토용 미리보기 합치기 전 팀과 공유
그림. PR 미리보기에서 프로덕션 배포까지의 흐름
github.com/.../pull/42
▲vercel bot · 방금
ProjectStatusPreview
my-first-app✓ ReadyVisit Preview ↗
이 미리보기 덕분에 합치기(merge) 전에 실제로 동작하는 화면을 팀원과 링크 하나로 공유할 수 있습니다. Vercel의 가장 큰 협업 강점입니다.

봇 코멘트가 너무 잦으면 프로젝트 Settings → Git에서 끌 수 있습니다(특정 브랜치만 끄는 것은 현재 불가).

6. 빌드 설정 자동 감지

구성 페이지에서 Framework Preset을 감지하면 아래 3개가 자동으로 채워집니다. 필요할 때만 수동 변경하면 됩니다.

설정의미
Build Command빌드를 실행하는 명령(예: Next.js는 next build). 프레임워크 기준 자동 설정
Output Directory빌드 결과가 출력되는 폴더. 이 폴더 내용만 서빙됨
Install Command의존성 설치 방식(npm install, pnpm install 등)
Root Directory소스 코드 위치(저장소 루트 기준). 모노레포에서 하위 폴더를 가리킬 때 사용
빌드 파이프라인 — Vercel 서버에서 자동 소스 코드에서 시작해 Install, Build, Output Directory, 전 세계 CDN 배포를 거쳐 라이브 상태가 되는 5단계 빌드 파이프라인. Install·Build·Output Directory 세 단계는 Framework Preset이 자동 설정합니다. 빌드 파이프라인 — Vercel 서버에서 자동 Framework Preset이 자동 설정 소스 코드 ① Install 의존성 설치 ② Build 예: next build ③ Output Directory 빌드 결과물 ④ 전 세계 CDN 배포 라이브 ✓ 대부분 자동 감지되어 채워집니다 — 필요할 때만 수동 변경
그림. Vercel 빌드 파이프라인 (자동)

이 값들은 대시보드 Settings 또는 저장소 루트의 vercel.json에서도 바꿀 수 있습니다(vercel.json 상세는 ③ 섹션 참고).

7. 모노레포 & 고급 옵션

입문 단계에서는 "저장소 1개 = 프로젝트 1개"로 시작하면 충분합니다. 모노레포·빌드 스킵은 앱이 여러 개로 늘어났을 때 다시 보세요.

8. GitLab · Bitbucket · Azure DevOps

Vercel은 GitHub 외에도 GitLab, Bitbucket, Azure DevOps Pipelines 저장소의 자동 배포를 지원합니다. 동작 방식(push 트리거, 프로덕션/프리뷰 분리, PR 코멘트)은 GitHub과 동일한 모델입니다. self-hosted 저장소나 목록에 없는 provider는 Vercel CLI로 배포할 수 있습니다(③ 섹션).

참고 링크

다음 문서: GitHub 연동 실습 예시 → · ③ MCP·CLI·v0 직접 배포 →