How to Audit Storage Buckets for Config Drift

Why Storage Drift Matters

Supabase Storage buckets have their own configuration surface: public vs private visibility, file size limits, allowed MIME types, CORS origins, and RLS policies. These settings are configured per project in the Dashboard — they don't travel with migrations.

A bucket that is public in staging but was accidentally set to private in production will break every client upload. A missing CORS origin will cause silent failures from the browser.

What SupaForge Checks

• Bucket existence — buckets that exist in one environment but not the other.
• Public / private state — visibility mismatch.
• File size limits — fileSizeLimit differences.
• Allowed MIME types — allowedMimeTypes array comparison.
• CORS configuration — allowed origins, methods, and headers.
• Storage RLS policies — policies on storage.objects and storage.buckets.

Step 1 — Configure

npm i -g @akalforge/supaforge

{
  "environments": {
    "staging": {
      "dbUrl": "postgresql://user:pass@db.STAGING_REF.supabase.co:5432/postgres",
      "projectRef": "STAGING_REF",
      "apiKey": "your-staging-service-role-key"
    },
    "production": {
      "dbUrl": "postgresql://user:pass@db.PROD_REF.supabase.co:5432/postgres",
      "projectRef": "PROD_REF",
      "apiKey": "your-production-service-role-key"
    }
  },
  "source": "staging",
  "target": "production"
}

Step 2 — Scan Storage Check

supaforge scan --check storage

The output shows each bucket with its configuration delta. Buckets are matched by name across environments.

Step 3 — Interpret Results

Each finding includes:

1. Bucket name and the specific property that differs.
2. Source value and target value.
3. Severity — critical for public/private mismatch or missing buckets, warning for limit differences.

Step 4 — Promote

supaforge promote

supaforge promote --check storage --apply

Storage settings are applied through the Supabase Management API. RLS policy changes on storage.objects are applied as SQL statements.

Common Pitfalls

• Public buckets in dev, private in prod. Intentional or not? SupaForge flags the difference so you can decide.
• CORS origins with localhost. Staging may allow http://localhost:3000 — this should not be promoted to production. Review before promoting.
• Missing buckets. If a bucket exists in staging but not production, SupaForge reports it. Creating the bucket is part of the promote step.

Summary

Storage configuration is easy to change in the Dashboard and easy to forget to replicate. A storage check scan gives you confidence that buckets, policies, and CORS settings are consistent across environments.