Skip to content

Supabase Setup Guide: Step-by-Step

This document provides a step-by-step guide for setting up your Supabase projects for Staging and Production environments, and configuring the necessary credentials for database migrations via GitHub Actions.

Part 1: Creating Supabase Projects

You will need two separate Supabase projects: one for staging and one for production. This ensures complete isolation between your environments.

Steps to Create a Supabase Project (Repeat for Staging and Production):

  1. Sign up/Log in to Supabase: Go to app.supabase.com and sign up or log in.
  2. Create New Project:
    • If you're part of an organization, select it. Otherwise, projects are created under your personal account.
    • Click "New project".
    • Organization: Choose your organization (or it defaults to your personal account).
    • Name:
    • For Staging: e.g., delta-staging or my-app-staging.
    • For Production: e.g., delta-production or my-app-prod.
    • Database Password: Create a strong password and save it securely. You might need this for direct database access or certain Supabase CLI operations. This will be the value for STAGING_SUPABASE_DB_PASSWORD or PRODUCTION_SUPABASE_DB_PASSWORD GitHub secrets.
    • Region: Choose the AWS region closest to your users or your other backend services (e.g., eu-west-2 if aligning with your Fargate/Lambda).
    • Pricing Plan: Choose the appropriate plan (e.g., Free tier for staging, a paid tier for production).
  3. Click "Create new project". Wait for the project to be provisioned.

Repeat these steps to create both your staging and production projects.

Part 2: Finding Essential Supabase Project Details

For each project (Staging and Production), you need to find the following:

  1. Navigate to Your Project: In the Supabase dashboard, select the project (e.g., delta-staging).

  2. Go to API Settings:

    • In the left sidebar, click on Project Settings (the gear icon).
    • Select the API tab.

  3. Collect the following details from this page:

    • Project URL:
    • Found under "Project Configuration" > "URL".
    • Looks like: https://<your-project-ref>.supabase.co
    • This will be used for NEXT_PUBLIC_SUPABASE_URL in your app's Vercel environment variables.
    • Project Ref (ID):
    • This is the <your-project-ref> part of the URL.
    • It's also often explicitly listed.
    • This value will be configured as a GitHub Variable (e.g., SUPABASE_PROJECT_REF) within specific GitHub Environments (like "Production" and "Staging").
    • Public publishable Key:
    • Found under "Project API keys" > Publishable Key.
    • This is a long JWT-like string.
    • This will be used for NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY in your app's Vercel environment variables.
    • Secret Key:
    • Found under "Project API keys" > Secret keys.
    • CRITICAL: This key bypasses Row Level Security. Keep it extremely secure.
    • This will be used for SUPABASE_SECRET_KEY in your app's Vercel environment variables (for server-side use only).

Collect these four pieces of information for both your staging and production Supabase projects.

Part 3: Creating a Supabase Access Token

This token is used by the GitHub Actions workflow to run Supabase CLI commands (like supabase migration up).

  1. Go to your Supabase Account Settings: app.supabase.com/account/tokens
  2. Click "Generate New Token".
  3. Name: Give it a descriptive name, e.g., GitHub Actions CI/CD.
  4. Click "Generate Token".
  5. Immediately copy the generated token value. Supabase will only show it once.
    • Store this value for a GitHub Secret named SUPABASE_ACCESS_TOKEN. This secret can be defined at the repository level or, for better practice, within each GitHub Environment ("Production", "Staging").

Part 4: GitHub Variables and Secrets for Supabase Workflows

Configure these in your GitHub repository under "Settings" > "Environments". Create an environment for "Production" and another for "Staging".

  • For the "Production" GitHub Environment:
  • Environment variable (Variable):
    • SUPABASE_PROJECT_REF: The Project Ref of your production Supabase project (from Part 2).

  • Environment secrets (Secrets):

    • SUPABASE_ACCESS_TOKEN: The Access Token generated in Part 3.
    • SUPABASE_DB_PASSWORD: The database password for your production Supabase project (from Part 1). (Optional for migration up but recommended for other CLI operations or direct access).

  • For the "Staging" GitHub Environment:

  • Environment variable (Variable):
    • SUPABASE_PROJECT_REF: The Project Ref of your staging Supabase project (from Part 2).
  • Environment secrets (Secrets):
    • SUPABASE_ACCESS_TOKEN: The same Access Token generated in Part 3 (or a different one if preferred for staging).
    • SUPABASE_DB_PASSWORD: The database password for your staging Supabase project (from Part 1). (Optional).

Using GitHub Environments allows you to scope these variables and secrets correctly when the workflow job specifies environment: Production or environment: Staging.

Part 5: Database Migrations

  • Your database schema changes should be managed as migration files located in packages/database/supabase/migrations/.
  • The GitHub Actions workflows (deploy-supabase-migrations-staging.yml and deploy-supabase-migrations-production.yml) are configured to:
  • Set up the Supabase CLI.
  • Link to the appropriate Supabase project (staging or production) using the Project Ref and Access Token secrets.
  • Run supabase migration up --linked from the packages/database directory. This command applies any new migration files found in the supabase/migrations subfolder that have not yet been applied to the linked database.

This setup ensures that your database schema evolves consistently with your codebase for both staging and production environments.