Skip to content

Vercel Setup Guide: Step-by-Step

This document provides a step-by-step guide for setting up your app Vercel project, configuring environments, and managing necessary credentials for deployment via GitHub Actions.

Part 1: Initial Vercel Project Setup (If Not Already Done)

If you haven't already created a Vercel project for your app application:

  1. Sign up/Log in to Vercel: Go to vercel.com and sign up or log in, preferably using your GitHub account.
  2. Import Project:
    • From your Vercel dashboard, click "Add New..." > "Project".
    • Import Git Repository: Select your GitHub repository where this monorepo resides. You may need to grant Vercel access to your repositories if you haven't already.
  3. Configure Project:
    • Select Root Directory: This is crucial for monorepos. When Vercel asks for the "Root Directory," click the "Edit" button next to it and change it from the repository root to packages/app.
    • Framework Preset: Vercel should automatically detect "Next.js".
    • Project Name: Give your project a name on Vercel (e.g., delta-app).
    • Build and Output Settings: Defaults are usually fine for Next.js.
    • Environment Variables: You can add these now or later (see Part 3).
  4. Deploy: Click "Deploy". Vercel will attempt an initial deployment.

Part 2: Finding Essential Vercel IDs and Creating an Access Token

These are needed for your GitHub Actions workflows.

2.1. Finding Your Vercel Organization ID (VERCEL_ORG_ID)

  • If using a Vercel Team:
  • Go to your Vercel Dashboard.
  • Select your Team from the scope selector (top-left).
  • Navigate to the team's Settings tab.
  • The Organization ID (Team ID) is usually visible here or in the URL (e.g., vercel.com/teams/YOUR_TEAM_SLUG/...).
  • If using a Personal Account (Hobby plan): The orgId might correspond to your user ID.
  • Reliable Method (using Vercel CLI after linking):
  • Install Vercel CLI: npm install -g vercel
  • Login: vercel login
  • Navigate to your local repository root: cd /path/to/your/delta-project
  • Link the project: vercel link (follow prompts, select existing project, set root to packages/app).
  • Inspect the generated file: cat .vercel/project.json. This file will contain orgId. Store this value for the VERCEL_ORG_ID GitHub Variable.

2.2. Finding Your Vercel Project ID (VERCEL_PROJECT_ID)

  • Via Vercel Dashboard:
  • Go to your Vercel Dashboard.
  • Select your app project.
  • Navigate to the project's Settings tab.
  • Under the General section, scroll down to find the Project ID (usually starts with prj_).
  • Via Vercel CLI (after linking, as above):
  • The projectId is also present in the .vercel/project.json file. Store this value for the VERCEL_PROJECT_ID GitHub Variable.

2.3. Creating a Vercel Access Token (VERCEL_TOKEN)

  1. Go to your Vercel Dashboard.
  2. Click on your avatar/profile icon (top-right) > Settings.
  3. In the left sidebar, under "Personal Account" or your "Team Settings", click on Tokens.
  4. Click "Create".
    • Token Name: Descriptive, e.g., GitHub Actions - Delta App.
    • Scope: Select the appropriate scope (your account or the specific team owning the project).
    • Expiration: Choose an appropriate duration (e.g., 1 year, or "No Expiration" with a plan to rotate manually).
  5. Click "Create Token".
  6. Immediately copy the generated token value. Vercel will only show it once. Store this value for the VERCEL_TOKEN GitHub Secret. This token will be used for both production and staging deployments as configured in the workflows.

Part 3: Configuring Environment Variables in Vercel

Set these directly in your Vercel Project's UI.

  1. Go to your Vercel Dashboard.
  2. Select your app project.
  3. Navigate to Settings > Environment Variables.

You need to add variables for Production, Preview (for staging), and optionally Development environments.

For EACH variable listed below, add it for the "Production" environment and then add it again for the "Preview" environment (with potentially different values for staging).

  • Variable Name (in Vercel UI): NEXT_PUBLIC_SUPABASE_URL
  • Value (Production): Your production Supabase project URL.
  • Value (Preview/Staging): Your staging Supabase project URL.
  • Type: Plaintext. Ensure "All Environments" or specific ones are checked. (Available to Browser)
  • Variable Name: NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
  • Value (Production): Your production Supabase anon key.
  • Value (Preview/Staging): Your staging Supabase anon key.
  • Type: Secret. (Available to Browser - Vercel will warn; this is expected for this specific key).
  • Variable Name: SUPABASE_SECRET_KEY
  • Value (Production): Your production Supabase service role key.
  • Value (Preview/Staging): Your staging Supabase service role key.
  • Type: Secret. Crucially, ensure this is NOT exposed to the browser (do not check "Available to Browser" if Vercel UI has such an option, or ensure it's not prefixed NEXT_PUBLIC_).
  • Variable Name: AIHUB_API_GATEWAY_URL
  • Value (Production): URL of your production aiHub service.
  • Value (Preview/Staging): URL of your staging aiHub service.
  • Type: Secret. (Server-side only)
  • Variable Name: AIHUB_CUSTOM_SHARED_KEY (App sends to aiHub)
  • Value (Production): Unique secret string for production.
  • Value (Preview/Staging): Unique secret string for staging.
  • Type: Secret. (Server-side only)
  • Variable Name: VERCEL_AUTHORIZATION_API_KEY (App expects from aiHub)
  • Value (Production): Unique secret string for production (must match what prod aiHub sends).
  • Value (Preview/Staging): Unique secret string for staging (must match what staging aiHub sends).
  • Type: Secret. (Server-side only)
  • Variable Name: LOKI_URL
  • Value (Production): Your production Loki URL.
  • Value (Preview/Staging): Your staging Loki URL.
  • Type: Secret. (Server-side only)
  • Variable Name: LOKI_USER
  • Value (Production/Staging): Loki username (if auth enabled).
  • Type: Secret. (Server-side only)
  • Variable Name: LOKI_PASSWORD
  • Value (Production/Staging): Loki password (if auth enabled).
  • Type: Secret. (Server-side only)
  • Variable Name: SEND_DEV_LOGS_TO_LOKI
  • Value (Production): false
  • Value (Preview/Staging): true or false as desired.
  • Type: Plaintext. (Server-side only)
  • Variable Name: NEXT_PUBLIC_SEND_DEV_LOGS_TO_LOKI
  • Value (Production): false
  • Value (Preview/Staging): true or false as desired.
  • Type: Plaintext. (Client-side logging control)

(Note: NODE_ENV is typically set automatically by Vercel.)

Part 4: GitHub Variables and Secrets for Workflow Execution

Your GitHub Actions workflows use a combination of Variables (for non-sensitive IDs) and Secrets (for sensitive tokens) to interact with Vercel.

  1. Navigate to your GitHub repository.

  2. Go to Settings > Secrets and variables > Actions.

  3. Configure Variables:

    • Under the "Variables" tab, click "New repository variable" for each:
    • VERCEL_ORG_ID: (Value from step 2.1)
    • VERCEL_PROJECT_ID: (Value from step 2.2)

  4. Configure Secrets:

    • Under the "Secrets" tab, click "New repository secret" for:
    • VERCEL_TOKEN: (Value from step 2.3)

How it all connects:

  • The GitHub Actions use VERCEL_ORG_ID (from vars), VERCEL_PROJECT_ID (from vars), and VERCEL_TOKEN (from secrets) to interact with your Vercel project (link, pull settings, trigger builds/deploys).
  • The vercel pull command in the workflow fetches the application-specific environment variables (like NEXT_PUBLIC_SUPABASE_URL) that you configured in the Vercel UI (Part 3) into the build environment of the GitHub Action.
  • Your Next.js application code (process.env.NEXT_PUBLIC_SUPABASE_URL) then uses these values during build and runtime.

Part 5: Configuring Vercel Deployment Protection for API Access

To ensure that your Vercel-deployed app APIs can be securely accessed by other services (like your aiHub service running on Fargate) without exposing them publicly, you need to configure Vercel's Deployment Protection. This involves enabling standard Vercel Authentication and then setting up a bypass secret for automation.

The aiHub service is configured to send a specific header x-vercel-protection-bypass with the value of the VERCEL_AUTOMATION_BYPASS_SECRET when calling Vercel APIs. You can refer to packages/aiHub/src/index.ts for an example of how this header is implemented.

5.1. Accessing Deployment Protection Settings

  1. Go to your Vercel Dashboard.
  2. Select your app project (e.g., delta or delta-app).
  3. Navigate to the project's Settings tab.
  4. In the left sidebar, click on Deployment Protection. (Example URL provided by user: https://vercel.com/chris-parkers-projects-e12d04e3/delta/settings/deployment-protection. Adapt chris-parkers-projects-e12d04e3 to your Vercel team/username and delta to your Vercel project name.) (General Vercel documentation: https://vercel.com/docs/deployment-protection)

5.2. Enabling Vercel Authentication

  1. Under the "Deployment Protection" section, ensure that Vercel Authentication is selected as the "Standard Protection" method. This is usually the default. If it's set to "No protection" or another method, change it to "Vercel Authentication".

5.3. Setting up Protection Bypass for Automation

  1. Scroll down to the Protection Bypass for Automation section.
  2. Click the "Create Secret" button (or similar, the UI might vary slightly).
  3. Secret Name: Give it a descriptive name, for example, AIHUB_BYPASS_SECRET. (This name is for your reference in the Vercel UI and does not need to match the environment variable name used by aiHub).
  4. Secret Value:
    • This is the crucial part. The value you enter here must match the value of the VERCEL_AUTOMATION_BYPASS_SECRET environment variable that your aiHub service (and other automated services) will use.
    • This VERCEL_AUTOMATION_BYPASS_SECRET should be securely stored (e.g., as a GitHub repository secret if your aiHub deployment process pulls it from there, or directly in your Fargate task definition's environment variables).
    • Important: Generate a strong, unique secret for this purpose.
  5. Click "Add" or "Create".

5.4. How it Works

  • When Vercel Authentication is active, direct access to your deployment URLs (including API routes) will require Vercel login.
  • Services like aiHub can bypass this authentication by including the x-vercel-protection-bypass header with the correct secret value you just configured in Vercel's "Protection Bypass for Automation" setting.
  • The VERCEL_AUTOMATION_BYPASS_SECRET environment variable (used by aiHub) provides the value for this header.

Note: The VERCEL_AUTOMATION_BYPASS_SECRET itself is managed outside of Vercel's environment variables for the app project. It's a secret known by the calling service (aiHub) and its value is what you configure in Vercel's "Protection Bypass for Automation" setting.