Nightly Supabase Backups via GitHub Actions

Why GitHub Actions for Supabase Backups

GitHub Actions gives you 2,000 free minutes per month on private repos. For indie developers, that's unlimited nightly backups at zero marginal cost. Unlike manual exports or paid backup services, Actions integrates directly into your existing workflow without new infrastructure.

When you're running Claude-powered agents that depend on Supabase as the source of truth, data loss isn't just inconvenient—it breaks your system. Nightly backups mean you can recover in hours, not days.

Setting Up the GitHub Actions Workflow

Create a `.github/workflows/backup-supabase.yml` file in your repository. The workflow should trigger on a schedule (cron expression for 2 AM UTC works well for most teams), authenticate to Supabase via API key, export your database, and commit the backup to a separate branch or cloud storage.

You'll need two secrets in your GitHub repo: `SUPABASE_URL` and `SUPABASE_SERVICE_KEY`. The service key has full database access and should only be used in Actions—never commit it to your repo.

name: Nightly Supabase Backup
on:
  schedule:
    - cron: '0 2 * * *'
jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Backup Supabase
        env:
          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
          SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }}
        run: |
          npm install @supabase/supabase-js
          node backup.js

Exporting Data with the Supabase API

Use the Supabase management API to export your database as SQL or JSON. A Node.js script can fetch all tables, transform them into backup-friendly formats, and commit them to Git. This approach works for databases under 1GB; larger databases may need PostgreSQL's native pg_dump tool.

Store backups in a dedicated `backups/` folder on a separate branch, or push them to an S3 bucket if you prefer cloud storage over Git history.

Restoring from Backups

When disaster strikes, restoration is one SQL query away. Run your backup file against your Supabase database using the SQL editor in the dashboard, or pipe it through `psql` if you have direct PostgreSQL access. Test restore procedures quarterly—backups are only useful if they actually work.

For AI agent systems, ensure your backup includes all vector embeddings, agent state tables, and conversation history. Missing a single critical table defeats the purpose.

Monitoring and Alerting

GitHub Actions logs tell you if backups succeeded or failed, but add a slack notification step so you see failures immediately. A failed backup that goes unnoticed is worse than no backup at all.

Track backup file sizes over time to catch runaway growth early. If your backup suddenly jumps from 50MB to 500MB, something's probably wrong with your cleanup jobs.

Open-Source Implementation

The Pantheon project on GitHub (github.com/lewisallena17/pantheon) provides a complete, production-ready implementation of Supabase backups via GitHub Actions. It includes the workflow YAML, backup script, restore utilities, and monitoring setup. Fork it as a starter template for your Next.js + Supabase project.

Pantheon handles vector embeddings, handles large tables efficiently, and includes retry logic for flaky network conditions—all the edge cases you'll hit in production.

Open-source implementation

Everything in this article runs in pantheon — a production-ready Next.js + Supabase + Claude starter. Clone it, deploy to Vercel, run PM2. The dashboard auto-commits every agent edit and reverts itself if TypeScript breaks.