들어가며: 왜 OIDC 기반 레지스트리 인증이 필요할까?
컨테이너 이미지를 CI/CD 파이프라인에서 레지스트리에 푸시하려면 보통 docker login에 사용할 자격 증명이 필요합니다. 그런데 이 자격 증명을 GitHub Secrets에 장기 보관하면 유출 시 피해 범위가 커지고, 주기적 로테이션 관리 부담도 생깁니다.
Vercel이 공개한 vercel/vcr-action/login 액션은 GitHub OIDC(OpenID Connect) 를 이용해 이 문제를 해결합니다. 워크플로우가 발급받은 단기 OIDC 토큰을 Vercel 액세스 토큰으로 교환한 뒤 VCR(vcr.vercel.com)에 로그인하고, 작업이 끝나면 토큰을 즉시 폐기합니다. 즉, 장기 시크릿을 저장하지 않는 방식입니다.
근거자료: Vercel 공식 체인지로그

설정 단계: OIDC 정책부터 워크플로우까지
1) Vercel 팀에 OIDC 정책 생성
GitHub 리포지토리와 워크플로우를 매칭하는 OIDC 정책을 만들고, VCR에 대한 read-write 권한을 부여합니다.
2) GitHub 리포지토리 변수 설정
다음 값을 리포지토리 변수로 저장합니다.
VERCEL_TEAM_ID(필수)VERCEL_TEAM_SLUGVERCEL_PROJECT_SLUGVCR_REPOSITORY(이미지 태그에 사용할 리포지토리 이름)
3) 워크플로우에 id-token: write 권한 부여
OIDC 토큰을 발급받으려면 워크플로우 또는 잡에 id-token: write 권한이 반드시 있어야 합니다.
4) 로그인 → 빌드 → 푸시 스텝 추가
name: Push to VCR
on:
push:
branches: [main]
permissions:
contents: read
id-token: write # OIDC 토큰 발급에 필요
jobs:
push:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- name: Log in to VCR
uses: vercel/vcr-action/login@v1
with:
team: ${{ vars.VERCEL_TEAM_ID }}
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/amd64
provenance: false
tags: vcr.vercel.com/${{ vars.VERCEL_TEAM_SLUG }}/${{ vars.VERCEL_PROJECT_SLUG }}/${{ vars.VCR_REPOSITORY }}:latest
outputs: type=image,push=true,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true
기본적으로 Docker를 대상으로 인증하며, engines 입력값을 넘기면 Podman이나 Buildah로도 사용할 수 있습니다.
![]()
실무 적용 시 주의사항과 한계
| 항목 | 내용 |
|---|---|
| 플랫폼 제약 | 현재 예시는 linux/amd64 이미지 기준입니다. 다른 아키텍처가 필요하면 platforms 값을 조정해야 합니다. |
| 권한 최소화 | OIDC 정책은 특정 리포지토리·브랜치·워크플로우에만 매칭되도록 좁게 설정하세요. |
| 토큰 수명 | 액션은 잡 종료 시 로그아웃 및 토큰 폐기를 수행하지만, 잡이 비정상 종료되면 폐기 타이밍이 달라질 수 있으므로 정책 측면에서 만료 시간을 짧게 가져가는 것이 안전합니다. |
| 이미지 사용 | VCR이 이미지 준비를 마치면 동일 프로젝트 내에서 커스텀 Vercel Sandbox 이미지로 참조할 수 있습니다. |
| 디버깅 | OIDC 교환 실패 시 id-token: write 권한 누락이 가장 흔한 원인입니다. |
또한 Vercel의 마이크로프론트엔드 라우팅처럼 도메인·별칭 체계가 얽힌 환경에서는 이미지 태그와 프로젝트 슬러그를 일관되게 관리하는 것이 중요합니다. 관련 내용은 Vercel Microfrontends 라우팅 업데이트 가이드에서 확인할 수 있습니다.

마무리: 다음 단계 학습 방향
이번 업데이트의 핵심은 "장기 시크릿 제로" 입니다. GitHub OIDC와 Vercel의 단기 토큰 교환을 조합하면 CI/CD 파이프라인의 공격 표면을 크게 줄일 수 있습니다.
- 다음 단계로는 OIDC 정책을 브랜치·환경별로 분리해 최소 권한 원칙을 적용해 보세요.
- Podman/Buildah 등 다른 엔진으로의 전환도
engines옵션으로 실험해 볼 만합니다. - UI/UX 관점의 인증 경험 설계에 관심이 있다면 Cloudflare Turnstile 리디자인 인사이트도 함께 보면 좋습니다.
국내 SI·스타트업 환경에서는 여전히 레지스트리 자격 증명을 Secrets에 두는 경우가 많은데, 이번 사례를 계기로 OIDC 기반 인증으로 전환을 검토해 보시길 권합니다.