はじめに: なぜ OIDC ベースのレジストリ認証が必要なのか

CI/CD パイプラインからコンテナイメージをレジストリへプッシュする場合、通常は docker login 用の認証情報が必要です。しかし、この認証情報を GitHub Secrets に長期間保存すると、漏洩時の影響範囲が大きくなり、定期的なローテーション運用の負担も発生します。

Vercel が公開した vercel/vcr-action/login アクションは、GitHub OIDC(OpenID Connect) を用いてこの課題を解決します。ワークフローが発行する短命な OIDC トークンを Vercel のアクセストークンと交換し、VCR(vcr.vercel.com) にログインします。ジョブ終了時にはログアウトし、Vercel トークンを失効させます。つまり、長期間有効なシークレットを保存しない方式です。

根拠資料: Vercel 公式チェンジログ

Developer configuring Vercel Container Registry authentication in cloud dashboard IT Technology Image

設定手順: OIDC ポリシーからワークフローまで

1) Vercel チームに OIDC ポリシーを作成

GitHub リポジトリとワークフローに一致する OIDC ポリシーを作成し、VCR への read-write 権限を付与します。

2) GitHub リポジトリ変数の設定

以下の値をリポジトリ変数として保存します。

  • VERCEL_TEAM_ID(必須)
  • VERCEL_TEAM_SLUG
  • VERCEL_PROJECT_SLUG
  • VCR_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 でも利用できます。

GitHub Actions workflow pushing Docker image to Vercel Container Registry with OIDC Algorithm Concept Visual

実務適用時の注意点と限界

項目内容
プラットフォーム制約現状の例は linux/amd64 イメージが前提です。他のアーキテクチャが必要な場合は platforms の値を調整してください。
権限の最小化OIDC ポリシーは特定のリポジトリ・ブランチ・ワークフローにのみ一致するよう狭く設定してください。
トークンの寿命アクションはジョブ終了時にログアウトとトークン失効を行いますが、ジョブが異常終了した場合は失効タイミングが変わり得るため、ポリシー側で有効期限を短く設定するのが安全です。
イメージの利用VCR がイメージの準備を完了すると、同一プロジェクト内でカスタム Vercel Sandbox イメージとして参照できます。
デバッグOIDC 交換に失敗する場合、id-token: write 権限の欠落が最も多い原因です。

また、Vercel のマイクロフロントエンドルーティングのようにドメインやエイリアスが絡む環境では、イメージタグとプロジェクトスラッグを一貫して管理することが重要です。関連情報は Vercel Microfrontends ルーティング更新ガイド をご参照ください。

OIDC token exchange between GitHub and Vercel for secure registry access Technical Structure Concept

まとめ: 次の学習ステップ

今回のアップデートの本質は 「長期間有効なシークレットをゼロにする」 ことです。GitHub OIDC と Vercel の短命トークン交換を組み合わせることで、CI/CD パイプラインの攻撃対象領域を大幅に削減できます。

  • 次のステップとして、OIDC ポリシーをブランチや環境ごとに分離し、最小権限の原則を適用してみてください。
  • Podman/Buildah など他のエンジンへの切り替えも engines オプションで試験可能です。
  • UI/UX 観点の認証体験設計に関心がある場合は、Cloudflare Turnstile リデザインのインサイト も合わせてご覧ください。

日本の開発現場では依然としてレジストリ認証情報を Secrets に保管するケースが多いですが、本アップデートを機に OIDC ベース認証への移行を検討する価値は十分にあります。

本コンテンツは、信頼性の高い情報源をもとにAIツールを活用して作成され、編集者によるレビューを経て公開されています。専門家によるアドバイスの代替となるものではありません。