Skip to main content

Source: ocean/docs/SUPABASE_CICD_SETUP.md | ✏️ Edit on GitHub

Supabase CI/CD Setup Guide

This guide explains how to set up the GitHub Actions workflows for automated Supabase deployments.

Required GitHub Secrets​

Add these secrets to your GitHub repository under Settings → Secrets and variables → Actions:

1. SUPABASE_ACCESS_TOKEN (Required)​

Your personal Supabase access token for CLI authentication.

# Generate token at: https://supabase.com/dashboard/account/tokens
# Or use Supabase CLI:
supabase login

2. SUPABASE_DB_PASSWORD (Required)​

The database password for your Supabase project.

# Find in Supabase Dashboard:
# Settings → Database → Connection string → Password

3. SUPABASE_ANON_KEY (Required)​

The anonymous/public key for your Supabase project.

# Find in Supabase Dashboard:
# Settings → API → anon/public key

4. NEON_API_KEY (Optional)​

API key for Neon database provisioning.

# Get from: https://console.neon.tech/app/settings/api-keys

5. STRIPE_SECRET_KEY (Optional)​

Stripe secret key for billing integration.

# Get from: https://dashboard.stripe.com/apikeys

6. STRIPE_WEBHOOK_SECRET (Optional)​

Stripe webhook endpoint secret.

# Get from: https://dashboard.stripe.com/webhooks

7. SLACK_WEBHOOK_CRITICAL (Optional)​

Slack webhook URL for critical alerts.

Workflows​

1. deploy-Supabase.yml​

  • Trigger: Push to main branch (when Supabase/* files change)
  • Purpose: Automatically deploy migrations and Edge Functions
  • Safety: Runs on every push to main

2. deploy-Supabase-production.yml​

  • Trigger: GitHub Release or manual workflow dispatch
  • Purpose: Production deployments with extra safety checks
  • Safety: Requires explicit confirmation, includes backup step

Usage​

Automatic Deployments​

  1. Make changes to Supabase files
  2. Push to main branch
  3. CI/CD automatically deploys changes

Manual Production Deployment​

  1. Go to Actions → Deploy Supabase to Production
  2. Click "Run workflow"
  3. Type "production" to confirm
  4. Click "Run workflow"

Creating a Release​

  1. Create a new GitHub release
  2. Production deployment automatically triggers
  3. Includes all safety checks and smoke tests

Monitoring Deployments​

Check Deployment Status​

  • Go to Actions tab in GitHub
  • View running/completed workflows
  • Check logs for any errors

Rollback Procedures​

If a deployment fails:

  1. The workflow will attempt automatic rollback

  2. Check Supabase Dashboard for current state

  3. Manually revert if needed using:

    git revert <commit>
    git push origin main

Local Development​

Before pushing changes:

# Test migrations locally
supabase db push --dry-run

# Test Edge Functions
supabase functions serve

# Run local tests
pnpm test

Troubleshooting​

Migration Failures​

  • Check for SQL syntax errors
  • Ensure no breaking schema changes
  • Verify permissions (don't modify Supabase-owned schemas)

Edge Function Deployment Failures​

  • Check function has index.ts file
  • Verify no import errors
  • Test locally first with supabase functions serve

Secret Issues​

  • Ensure all required secrets are set
  • Check secret names match exactly
  • Rotate tokens if authentication fails

Best Practices​

  1. Always test locally first
  2. Use feature branches for development
  3. Create migrations carefully - they can't be easily rolled back
  4. Monitor deployments - check Actions tab after pushing
  5. Document breaking changes in pull requests

Emergency Contacts​

If production deployment fails and needs immediate attention:

  1. Check #alerts Slack channel
  2. Review Supabase Dashboard logs
  3. Contact on-call engineer