왜 이 기능이 나왔을까요?
여러분 팀에 Vercel 프로젝트가 두 개 이상 있다면, 피처 플래그(Feature Flag) 하나 공유하려고 서버 SDK 키를 복사해서 환경변수에 붙여넣은 경험이 한 번쯤 있으실 거예요. 문제는 이 방식이 생각보다 손이 많이 간다는 점이에요.
- 키를 복사한 순간부터 누가 어디에 어떤 키를 넣었는지 추적이 안 돼요.
- 키를 로테이션(rotation)하면 소비 측 프로젝트를 전부 다시 배포해야 해요.
- 로컬 개발 환경에서는
.env파일에 키를 또 넣어야 하고, 이게 커밋되면 보안 사고로 이어지기 쉬워요.
Vercel이 이번에 공개한 Project Connections는 이 지점을 정면으로 해결합니다. 핵심은 "키를 공유하지 않는다"는 거예요. 소비 측 프로젝트는 자기 배포(deployment)의 OIDC 아이덴티티로 인증하고, 소스 프로젝트는 그 접근을 읽기 전용으로 허용합니다. 근거자료는 Vercel 공식 체인지로그에서 확인할 수 있어요.
💡 한 줄 요약: SDK 키 복사 → OIDC 기반 프로젝트 간 인증으로 전환.

실제로 어떻게 쓰나요?
1) 연결 만들기
연결은 두 가지 방법으로 만들 수 있어요.
- 대시보드: 프로젝트 → Flags 섹션 → Connections 페이지
- CLI:
vercel flags connections(Vercel CLI 63.0.0 이상 필요)
연결은 모든 환경에 대해 읽기 전용으로 부여됩니다. 어떤 환경의 플래그를 평가할지는 소비 측 배포가 결정해요. 예를 들어 프로덕션 배포는 자동으로 프로덕션 플래그를 평가합니다.
2) 소비 측 코드에 어댑터 붙이기
소스 프로젝트의 ID만 넘기면 됩니다. 키는 필요 없어요.
// flags/next 어댑터로 소스 프로젝트 연결하기
import { flag } from 'flags/next';
import { createVercelAdapter } from '@flags-sdk/vercel';
// 소스 프로젝트 ID만 있으면 됩니다. SDK 키는 필요 없어요.
const sharedFlagsAdapter = createVercelAdapter({
projectId: 'prj_source',
});
// 연결된 소스 프로젝트에 정의된 플래그를 그대로 평가합니다.
export const newCheckout = flag({
key: 'new-checkout',
defaultValue: false,
adapter: sharedFlagsAdapter(),
});
3) 로컬 개발 환경
로컬에서는 vercel env pull을 실행하면 프로젝트의 OIDC 토큰을 받아옵니다. 즉, .env에 SDK 키를 손으로 넣을 필요가 없어요. 팀원 온보딩할 때 "키 어디서 받아요?" 질문이 사라진다는 뜻입니다 😅
4) 접근 회수(Revoke)
연결을 끊어도 재배포가 필요 없어요. 이게 생각보다 큰 차이입니다. 기존 방식은 키를 바꾸면 소비 측 프로젝트를 다시 빌드해야 했는데, 연결 해제는 대시보드에서 클릭 한 번이면 끝나요.
5) 버전 요구사항
@flags-sdk/vercel1.6.0 이상- 코어 라이브러리를 직접 쓸 경우
@vercel/flags-core1.11.0 이상 - CLI로 연결 관리 시 Vercel CLI 63.0.0 이상
모든 플랜에서 사용 가능하다는 점도 기억해두세요.

장단점 및 실무 주의사항
| 항목 | 기존 방식 (SDK 키 복사) | Project Connections |
|---|---|---|
| 인증 방식 | 서버 SDK 키 (장기 비밀값) | 배포 OIDC 아이덴티티 (단기) |
| 키 로테이션 | 소비 측 재배포 필요 | 재배포 불필요 (연결만 해제) |
| 로컬 개발 | .env에 키 수동 관리 | vercel env pull로 자동 |
| 권한 범위 | 키 권한 그대로 (넓음) | 읽기 전용으로 한정 |
| 감사/추적 | 키 배포 현황 파악 어려움 | 프로젝트 단위로 연결 관리 |
| 플랜 제약 | 없음 | 모든 플랜 가능 |
주의할 점
- 읽기 전용이라는 점을 잊지 마세요. 소스 프로젝트의 플래그를 소비 측에서 변경할 수는 없습니다. 플래그 값을 바꾸려면 소스 프로젝트에서 해야 해요.
- 환경 매핑은 소비 측 배포 기준입니다. 소비 측이 프리뷰 배포면 소스 프로젝트의 프리뷰 플래그를 평가해요. 팀에서 "프리뷰에서 프로덕션 플래그가 왜 보이지?" 같은 혼동이 생기기 쉬운 지점이에요.
- 버전 요구사항을 CI 파이프라인에서 강제해두세요.
@flags-sdk/vercel1.6.0 미만이면 조용히 실패할 수 있어요. - 연결 해제 시 즉시 반영됩니다. 소비 측에서 폴백(fallback) 값이 어떻게 동작하는지 미리 확인해두는 게 안전해요.

정리 및 다음 단계
Project Connections는 "피처 플래그를 팀 단위 자산으로 다룬다"는 방향성을 보여줍니다. 키를 복사해서 붙이는 방식은 빠르지만, 프로젝트가 늘어날수록 관리 부채가 커지기 마련이에요. OIDC 기반 인증으로 옮기면 보안 표면도 줄고, 키 로테이션 지옥에서도 벗어날 수 있습니다.
실무 적용 팁
- 모노레포가 아닌 멀티 프로젝트 팀이라면 가장 체감이 큰 기능이에요. 특히 마케팅 사이트와 앱이 분리된 구조에서 유용합니다.
- 플래그 소유권을 명확히 하세요. 소스 프로젝트가 "플래그 정의의 단일 출처(Single Source of Truth)"가 됩니다.
- CI에서 버전 체크를 자동화해서
@flags-sdk/vercel최소 버전을 강제하세요.
함께 보면 좋은 글
- "2026년, 에이전틱 개발이 현실이 되다: Spotify x Anthropic 대담에서 본 5가지 핵심 인사이트"
- "NVIDIA Nemotron 3 Nano Omni, 문서·영상·음성을 동시에 이해하는 오픈소스 멀티모달 모델 분석"
다음 단계로는 Vercel Flags의 A/B 테스트 연동이나 플래그 수명 관리(flag lifecycle) 문서를 함께 읽어보시길 추천해요. 플래그는 결국 "지우는 것"이 가장 어려운 작업이니까요 😅