【ITニュース解説】Fixing Vercel + Supabase env issues in GitHub Actions

現代のウェブアプリケーション開発では、Next.jsのようなフレームワーク、Vercelのようなデプロイサービス、そしてSupabaseのようなバックエンドサービスを組み合わせて利用することが一般的だ。これらのサービスを連携させ、開発から公開までのプロセスを自動化するために、GitHub Actionsのような継続的インテグレーション・継続的デプロイ（CI/CD）ツールが広く使われている。しかし、この自動化の過程で、アプリケーションの実行に必要な環境変数や、各サービスのAPIを操作するためのトークンに関する設定ミスが原因で、デプロイが失敗することが少なくない。この記事では、GitHub Actionsを使ってVercelとSupabaseを利用するNext.jsアプリケーションをデプロイする際に発生する、このような環境設定の問題と、その具体的な解決策について解説する。

筆者が直面したのは、ローカルの開発環境では問題なく動作するアプリケーションが、GitHub Actionsによるプレビューデプロイ、すなわちプルリクエストごとに自動的に構築されるテスト環境へのデプロイで失敗するという状況だった。この問題の根本原因は、アプリケーションの実行に必要な環境変数や、VercelのAPIを操作するためのトークンに設定された権限が、GitHub Actionsの実行環境に正しく渡されていなかったことにある。ローカルとCI/CD環境では環境が異なるため、特に機密情報である環境変数やトークンの管理方法が重要となる。

この環境設定の課題を解決するために、主に三つのアプローチが取られた。一つは環境変数の管理をGitHubの機能を使って一元化すること。二つ目は、デプロイ前に必要な環境変数が揃っているかを自動チェックする「事前検証」ステップの導入。そして三つ目は、Vercelへのデプロイに使用するAPIトークンの権限を必要最小限に限定することである。これらの対策により、デプロイプロセスの安定性とセキュリティが大きく向上する。

最初の解決策は、アプリケーションが依存する環境変数をGitHubのEnvironmentsとSecretsという機能を使って集中的に管理することだ。GitHub Environmentsは、本番環境やプレビュー環境といった異なるデプロイ先ごとに、それぞれ特化した設定や機密情報（シークレット）を紐付けられる機能である。これにより、デプロイされる環境に応じて適切な値が自動的に適用される。具体的には、VercelのAPIトークン（VERCEL_TOKEN）やSupabaseのURL（SUPABASE_URL）、匿名キー（SUPABASE_ANON_KEY）といった機密情報を、GitHubのSecretsに暗号化して保存する。こうすることで、これらの情報がコードリポジトリに直接記述されるのを防ぎ、セキュリティを強化する。

二つ目の対策として、デプロイプロセスを開始する前に、必要な環境変数が全て設定されているかを検証する「事前検証（Preflight validation）」ステップを導入する。このステップは、もし必須の環境変数が一つでも欠けている場合、デプロイを直ちに中止し、エラーを報告する。これにより、環境設定の不備が原因で発生する無駄なビルド時間やデプロイの失敗を未然に防ぐことができる。問題を早期に発見し、速やかに対応する「フェイルファスト」の原則に基づき、開発効率を高める。

三つ目の解決策は、Vercelへのデプロイに使用するVERCEL_TOKENに、必要最小限の権限（スコープ）のみを与えることだ。APIトークンに付与される権限は、そのトークンを使って行える操作の範囲を定義する。広範な権限を持つトークンが漏洩した場合、セキュリティ上の重大なリスクとなるため、デプロイに必要な「特定のプロジェクトに対する操作」といった限定的な権限のみを与える。この「最小権限の原則」を適用することで、万が一トークンが不正に利用されたとしても、その影響範囲を限定し、セキュリティリスクを大幅に低減できる。

これらの解決策は、GitHub Actionsのワークフロー定義ファイル（YAML形式）に具体的なステップとして記述される。このワークフローは、mainブランチへのプルリクエストが発生したときに実行されるように設定されている。まず、previewというジョブが定義され、これはubuntu-latest環境で動作し、GitHubのpreview環境に紐付けられ、そこで定義されたシークレットを利用する。ステップには、リポジトリのコードを取得するCheckout、Node.js環境をセットアップするSetup Node、そして前述の「事前検証」を行うPreflight env checkが含まれる。この事前検証ステップでは、シェルスクリプトで必須環境変数の存在チェックを行い、不足していればエラーで終了させる。

事前検証をパスした後、Installステップでプロジェクトの依存関係がインストールされ、Buildステップでアプリケーションがビルドされる。このビルド時には、Next.jsのクライアントサイドで利用されるNEXT_PUBLIC_SUPABASE_URLなどの環境変数が渡される。最後にVercel deploy (Preview)ステップが実行され、npx vercel pullでVercelのプロジェクト設定を同期し、npx vercel buildでアプリケーションをビルド、そしてnpx vercel deploy --prebuiltでビルド済みのアプリケーションをVercelにデプロイする。これらのVercelコマンドの実行時には、VERCEL_TOKENが環境変数として渡され、GitHub ActionsがVercelのAPIと安全に通信し、デプロイ操作を完了させる。

この仕組みを導入する上で、いくつかの注意点がある。一つは、Next.jsでブラウザからもアクセスされる可能性があるNEXT_PUBLIC_*で始まる環境変数と、サーバーサイドでのみ利用される機密性の高いキーを明確に区別することだ。機密情報は決してNEXT_PUBLIC_を付けて公開してはならない。また、Supabaseのservice_roleキーのように非常に強力な権限を持つキーは、セキュリティリスクが高いため、CI/CD環境には原則として含めるべきではない。GitHubのシークレットとしても、特別な理由がない限り保存しないのが賢明である。さらに、Vercel自体にも環境変数を設定する機能があるが、GitHub Actionsからデプロイする際には、Vercel側の環境変数もGitHub Actionsで設定している環境（PreviewやProduction）に合わせて正しく設定されていることを確認する必要がある。Vercel側の設定が不適切だと、vercel pullコマンドで空の値が取得され、デプロイが失敗する可能性がある。

このように、GitHub Actionsを用いたCI/CD環境でのデプロイは、環境変数の管理とセキュリティに細心の注意を払う必要がある。今回の解決策は、GitHubのEnvironmentsとSecretsを効果的に活用し、デプロイ前に厳密な事前検証を行うことで、環境設定の不備によるデプロイ失敗を防ぎ、安定した開発ワークフローを実現する。また、APIトークンの権限を最小限に抑えることで、セキュリティリスクも低減できる。これらの実践的なアプローチは、システム開発における自動化と信頼性を高める上で非常に重要だ。