Supabase Keepalive

Supabase pauses free-tier projects after 7 days of inactivity. This kills them before they die.

Runs on GitHub Actions. Zero dependencies. Zero servers. Zero cost.

Built by OpenSourcePatents LLC

---

The Problem

You have Supabase projects on the free tier. You don't hit them for a week. Supabase pauses them. Your users get errors. You scramble to restore them manually.

The Solution

This script pings every one of your Supabase projects every 3 days (safe margin under the 7-day limit). If a ping fails, it doesn't just shrug. It:

1. Retries 5 times with exponential backoff + random jitter
2. Falls back to the auth health endpoint if the REST API is unresponsive
3. Fires every alarm at once if it still can't reach the project:
   • Creates a GitHub Issue with full failure details
   • Sends you an email (via SendGrid or SMTP)
   • Sends a push notification (via Pushover)
   • Logs the result to a Supabase table so you have history

---

Quick Start

1. Fork or Clone

git clone https://github.com/OpenSourcePatents/supabase-keepalive.git
cd supabase-keepalive

2. Add Your Projects

Open config/projects.json and add your projects:

[
  {
    "name": "MyApp",
    "envUrl": "MYAPP_SUPABASE_URL",
    "envKey": "MYAPP_SUPABASE_ANON_KEY"
  },
  {
    "name": "MySideProject",
    "envUrl": "SIDEPROJECT_SUPABASE_URL",
    "envKey": "SIDEPROJECT_SUPABASE_ANON_KEY"
  }
]

The envUrl and envKey fields are the names of the environment variables (GitHub Secrets) that hold your actual credentials. The script reads them at runtime. Your keys never touch the code.

3. Add GitHub Secrets

Go to your repo > Settings > Secrets and Variables > Actions.

For each project, add two secrets:

Secret	Value
MYAPP_SUPABASE_URL	https://yourproject.supabase.co
MYAPP_SUPABASE_ANON_KEY	Your project's anon/public key

Find these in your Supabase Dashboard > Project Settings > API.

4. (Optional) Set Up Notifications

All of these are optional. The script works without them, but you won't know if something fails unless you check the GitHub Actions logs.

Secret	What it does
NOTIFY_EMAIL	Where failure alerts go
SENDGRID_API_KEY	Sends email via SendGrid
SMTP_USERNAME	Gmail SMTP (alternative to SendGrid)
SMTP_PASSWORD	Gmail app password
PUSHOVER_USER_KEY	Push notifications to your phone
PUSHOVER_APP_TOKEN	Pushover app token
STATUS_SUPABASE_URL	Supabase project to log results to
STATUS_SUPABASE_ANON_KEY	Anon key for the status project

5. (Optional) Set Up the Status Log Table

If you want ping history stored in Supabase, run the SQL in sql/create_keepalive_log.sql in your status project's SQL editor. This gives you a keepalive_log table and two views: keepalive_latest (last status per project) and keepalive_failures (last 30 days of failures).

6. Test It

From the GitHub Actions tab: click Supabase Keepalive > Run workflow.

Or run locally:

export MYAPP_SUPABASE_URL="https://yourproject.supabase.co"
export MYAPP_SUPABASE_ANON_KEY="your-anon-key"
node src/keepalive.js

---

How It Works

The script merges project config from three sources (highest priority first):

1. Environment variables - individual vars like MYAPP_SUPABASE_URL, or a single SUPABASE_PROJECTS JSON array
2. JSON config file - config/projects.json
3. Hardcoded fallback - the HARDCODED_PROJECTS array in src/keepalive.js

All three get merged. Duplicates are resolved by name. You can use any combination.

Adding More Projects Later

Add an entry to config/projects.json, add the two GitHub Secrets, done. No code changes needed.

Why Every 3 Days?

GitHub Actions cron doesn't support "every 6 days." Running every 3 days gives a comfortable safety margin. The pings are lightweight GET requests, so this costs you nothing.

---

License

Apache-2.0

---

Built by OpenSourcePatents LLC. If this saved your projects from pausing, star the repo.