Vercel 연동
OAuth 한 번으로 Vercel Preview Deployments 를 자동 설정합니다
목차
Vercel 연동이란?
QA Note의 Vercel 연동은 Connectable Account Integration(OAuth 2.0) 으로 팀을 인증한 뒤, 배포 이벤트 수신에 필요한 모든 Vercel 설정을 자동으로 수행합니다. 수신된 배포 이벤트는 커밋 키로 기록된 수정 커밋과 상관되어 이슈에 '검수 가능' 을 표시하는 데 사용됩니다.
수동 설정이 요구하던 단계(Project ID 복붙 → Preview Deployments 활성화 확인)가 프로젝트 선택 한 번으로 끝나며, previewDeploymentsDisabled: true 같은 조용한 실패 지점이 사라집니다.
Webhook 은 Vercel Integration Console 에 자동 구성되는 단일 채널로 수신하며, 설치 시점에 자동으로 등록됩니다. 프로젝트마다 별도의 Webhook URL 을 등록하거나 Signing Secret 을 복사할 필요가 없습니다.
설치 절차
1. Vercel 연동하기
프로젝트 설정 → 연동 탭에서 Vercel 연동하기 버튼을 클릭합니다. QA Note가 Vercel OAuth 승인 화면으로 이동시킵니다.
2. 팀 선택 및 Install
Vercel에서 QA Note가 접근할 팀을 선택하고 Install 을 누릅니다. QA Note로 돌아오면 해당 팀의 Vercel 프로젝트 목록이 드롭다운에 표시됩니다.
3. 프로젝트 선택 (자동화 실행)
드롭다운에서 QA Note와 연결할 Vercel 프로젝트를 선택하면 아래가 한 번에 실행됩니다.
| 동작 | API | 효과 |
|---|---|---|
| 권한 검증 | GET /v9/projects | 선택한 팀에 실제 접근 가능한지 확인 |
| Preview 활성화 | PATCH /v9/projects/{id} | previewDeploymentsDisabled=false |
| 프로젝트 연결 저장 | (내부 DB) | projects.vercel_project_id 에 저장 — 공용 Integration Console Webhook 이 전달하는 배포 이벤트를 올바른 QA Note 프로젝트로 라우팅하기 위한 키 |
성공하면 토스트에 "Vercel Preview 연결 완료" 가 표시되고, 상태 뱃지가 연결됨 으로 전환됩니다.
연결 해제
QA Note에서 프로젝트 연결 해제
연결된 프로젝트 박스의 해제 버튼을 누르면 QA Note 내부의 vercelProjectId 가 정리됩니다. 공용 Integration Console Webhook 은 조직 내 다른 프로젝트에서도 사용되므로 그대로 유지됩니다. 채널 전체를 제거하려면 Vercel Integration 자체를 제거하세요.
Vercel에서 Integration 제거
Vercel 계정 → Integrations → QA Note → Remove 로 팀 전체에서 제거할 수 있습니다. QA Note는 Vercel이 발송하는 integration-configuration.removed 웹훅을 받아 설치 row를 자동 정리합니다.
권한 범위
설치 토큰은 아래 범위 안에서만 동작합니다.
- Projects Read/Write — 프로젝트 목록 조회, Preview Deployments 활성화
- Deployments Read — 배포 상태 수신
- Integration Configuration / Resource Read/Write — 설치 메타데이터 관리
환경 변수, 도메인, 빌링 정보 등 자동화에 불필요한 스코프는 요청하지 않습니다.
재설치가 필요한 경우
Vercel 이 새로운 스코프를 요구하거나 설치가 취소된 상황에서는 Vercel Integrations Console 에서 QA Note 항목을 제거한 뒤 다시 설치하세요. Integration Console Webhook 은 설치 시점에 자동으로 재구성되므로 프로젝트별 Webhook 설정을 따로 건드릴 필요가 없습니다.
문제 해결
- 배포 이벤트가 수신되지 않는다 — 해당 Vercel 프로젝트의 Preview Deployments가 꺼져 있을 가능성이 높습니다. QA Note에서 Vercel 연동 을 다시 실행해 자동 경로로 활성화하거나, Vercel 대시보드 → Project Settings → Git 에서 수동으로 켜주세요.
- 토큰 유출 대응 — Vercel Integrations Console 에서 Client Secret 을 Regenerate 하고,
VERCEL_INTEGRATION_CLIENT_SECRET을 교체한 뒤 OAuth 왕복을 재수행합니다. 설치별access_token은 영향받지 않습니다.