How to Audit Storage Buckets for Config Drift

Why Storage Drift Matters

Supabase Storage buckets carry their own settings: public or private, a file size limit, allowed MIME types, and the RLS policies on storage.objects that decide who may read and write. They're usually set up in the dashboard and don't travel with your migrations.

A bucket that is private in staging but public in production exposes every file in it. A missing upload policy in production breaks uploads that worked in testing.

What SupaForge Checks

• Buckets - present in one environment but not the other, including analytics and vector buckets.
• Visibility - public versus private. A bucket public in the target but private in the source is critical.
• Limits - file size limit, allowed MIME types and the other bucket settings.
• Storage policies - policies on storage.objects and storage.buckets, compared like any other RLS policy.

Files themselves are never copied. To compare which files exist on each side, add --include-files.

Step 1 - Configure

npm install -g @akal/supaforge

{
  "environments": {
    "staging": {
      "dbUrl": "$STAGING_DATABASE_URL",
      "projectRef": "STAGING_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    },
    "production": {
      "dbUrl": "$PRODUCTION_DATABASE_URL",
      "projectRef": "PROD_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    }
  },
  "source": "staging",
  "target": "production"
}

Step 2 - Compare Storage

supaforge diff --check=storage --detail

Buckets are matched by id. Each finding names the bucket and the setting that differs, with the source and target values and the fix.

Step 3 - Sync

supaforge diff --check=storage --apply --dry-run

supaforge diff --check=storage --apply

Bucket changes are made through the Storage API when the environment has an apiUrl, and with SQL otherwise; policy changes are SQL. Removing a bucket or a policy is held back until you add --allow-destructive.

Common Pitfalls

• Public in one place only. Intentional or not, SupaForge flags it so you decide.
• Policies added through the dashboard. Storage policies are easy to create in Studio and forget to replicate - the most common cause of uploads that work in staging and fail in production.
• Missing buckets. A bucket created in staging but not production is reported, and creating it is part of the apply.

Summary

Storage configuration is easy to change in the dashboard and easy to forget. SupaForge compares buckets, their settings and their policies, and syncs them so staging and production behave the same way.