Smithery is now a part of Arcade.dev! Read more in our announcement here
Configure Supabase CI/CD integration with GitHub Actions and testing. Use when setting up automated testing, configuring CI pipelines, or integrating Supabase tests into your build process. Trigger...
Build GitHub Actions workflows that automate the full Supabase lifecycle: link projects in CI, push migrations on merge, deploy Edge Functions, generate TypeScript types, run tests against a local Supabase instance, and create preview branches for pull requests. Every database change gets validated before it reaches production.
The pull-request CI pipeline runs these stages, all detailed in ci-workflows.md:
npx supabase db reset.npx supabase init)@supabase/supabase-js installed:npm install @supabase/supabase-js
Store credentials as GitHub repository secrets. The CI pipeline uses these to authenticate with your Supabase project without exposing tokens in code.
# Set secrets via GitHub CLI
gh secret set SUPABASE_ACCESS_TOKEN --body "<your-access-token>"
gh secret set SUPABASE_DB_PASSWORD --body "<your-database-password>"
gh secret set SUPABASE_PROJECT_REF --body "<your-project-ref>"
Generate your access token at supabase.com/dashboard/account/tokens. Find your project ref in Project Settings > General.
Link the project in any CI job that needs remote access:
- name: Install Supabase CLI
uses: supabase/setup-cli@v1
with:
version: latest
- name: Link Supabase project
run: npx supabase link --project-ref ${{ secrets.SUPABASE_PROJECT_REF }}
env:
SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
Add .github/workflows/supabase-ci.yml that runs on every pull request. It starts a local Supabase instance, runs db reset to apply all migrations from scratch, regenerates types and fails on drift (git diff --exit-code), then runs pgTAP and application tests. The default local dev keys are safe to commit — they only work against the local instance. Copy the complete workflow from ci-workflows.md.
Add .github/workflows/supabase-deploy.yml, scoped with paths: to supabase/migrations/** and supabase/functions/** so it only runs when database or function code changes on main. It links the remote project, runs npx supabase db push, deploys Edge Functions, and regenerates types from the production schema. Full workflow in ci-workflows.md.
Create isolated Supabase environments per pull request with npx supabase branches create, so reviewers test against real infrastructure with migrations applied. Preview branches require a Supabase Pro plan and incur compute costs while running. Workflow snippet in ci-workflows.md.
Two test layers run inside the CI workflow:
supabase/tests/ validate that RLS is enabled on public tables and that policies behave correctly. Run locally with npx supabase test db.createClient from @supabase/supabase-js pointed at http://127.0.0.1:54321 with the local anon key.Both patterns — the pgTAP SQL and the TypeScript client setup — are in testing-patterns.md.
After implementing these workflows:
SUPABASE_ACCESS_TOKEN and SUPABASE_DB_PASSWORD out of code| Error | Cause | Solution |
|---|---|---|
supabase start fails in CI |
Docker not available | Use ubuntu-latest runner (includes Docker by default) |
supabase db push returns "permission denied" |
Invalid or expired access token | Regenerate token at supabase.com/dashboard/account/tokens |
supabase link fails |
Wrong project ref | Check project ref in Settings > General, must match SUPABASE_PROJECT_REF secret |
| Type drift detected in PR | Schema changed without regenerating types | Run npx supabase gen types typescript --local > src/types/database.types.ts |
supabase functions deploy fails |
Missing Deno types or syntax errors | Run npx supabase functions serve locally first to catch issues |
| pgTAP tests fail | Missing RLS policies or schema constraints | Add policies before merging — npx supabase test db runs locally |
| Preview branch creation fails | Free plan limitation | Preview branches require Supabase Pro plan |
| Migration conflict on push | Divergent migration history | Run npx supabase db pull to reconcile remote vs local migrations |
Minimal CI for a new project — just migration validation and type checking:
name: Supabase CI
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: supabase/setup-cli@v1
with: { version: latest }
- run: npx supabase start -x realtime,storage-api,imgproxy,inbucket,edge-runtime
- run: npx supabase db reset
- run: npx supabase gen types typescript --local > /tmp/types.ts && diff src/types/database.types.ts /tmp/types.ts
- if: always()
run: npx supabase stop
For the full CI + deploy + preview workflows and an Edge Function deploy-with-verification snippet, see ci-workflows.md.
For deploying Supabase-backed applications to hosting platforms, see supabase-deploy-integration. For configuring RLS policies, see supabase-rls-policies.
