Vercel 연동

Vercel 연동이란?

QA Note의 Vercel 연동은 Connectable Account Integration(OAuth 2.0) 으로 팀을 인증한 뒤, AI Fix 파이프라인이 필요로 하는 모든 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 프로젝트를 선택하면 아래가 한 번에 실행됩니다.

성공하면 토스트에 "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 설정을 따로 건드릴 필요가 없습니다.

문제 해결

• AI Fix 가 pr_created 에서 멈춘다 — 해당 Vercel 프로젝트의 Preview Deployments가 꺼져 있을 가능성이 높습니다. QA Note에서 Vercel 연동 을 다시 실행해 자동 경로로 활성화하거나, Vercel 대시보드 → Project Settings → Git 에서 수동으로 켜주세요.
• 토큰 유출 대응 — Vercel Integrations Console 에서 Client Secret 을 Regenerate 하고, VERCEL_INTEGRATION_CLIENT_SECRET 을 교체한 뒤 OAuth 왕복을 재수행합니다. 설치별 access_token 은 영향받지 않습니다.

관련 문서

• GitHub 연동
• Slack 연동