The short answer
With Supabase branching connected to GitHub, each pull request gets an isolated preview environment with its own Supabase instance and API credentials, built from the migrations in your repository.1 New branches start without data or storage objects from the base project, by default; you add data with a seed file.1 Preview branches are deleted when the pull request is merged or closed.1
And when you merge, Supabase runs a deployment workflow whose migrate step applies pending migrations to your production project.1 So for a pull request an agent opened, the merge button is the moment the agent’s migration reaches production. Review accordingly.
Deedglass
A database change, checked and put back
-
1The agent’s change
Change order 42
UPDATE orders … WHERE id = 42
The agent: “1 row updated” -
2What the database really did
301 rows
A hidden trigger changed 300 more
Doesn’t match -
3Put back
301 rows restored
Signed off by a person
Matches
What a preview branch is
| Preview branch | Persistent branch | |
|---|---|---|
| For | Focused testing of one pull request | Long-lived environments such as staging or QA |
| Lifetime | Deleted when the pull request is merged or closed | Not paused or deleted for inactivity or on merge |
| Schema | Built from the repository’s migrations | Same |
| Data | None by default | None by default |
From Supabase’s docs.1 Each branch has its own credentials, so an agent working on a preview branch holds keys for that branch, not production. That’s the property you want: the service_role key of a disposable, data-less instance is a far smaller thing to lose.
No data by default, and why that matters
Supabase states that branches are data-less by default to protect sensitive production data.1 Our approved row on branching says the same, and adds that merging runs a deployment workflow that applies pending migrations.1
For agent work, data-less is mostly a gift:
- An agent on a preview branch can’t leak customer data it never had. The lethal trifecta loses its private-data leg.
- Destructive mistakes cost nothing. A dropped table on a preview branch is a reason to push another commit.
The cost: a migration that’s fine on an empty table can fail or lock on a big one. A NOT NULL column without a default, a unique index over duplicate rows or a type change on millions of rows behaves differently with real data. Cover that with a seed file of realistic fake data, sized to resemble production where it matters.
Merge means deploy
When you merge any branch into the base project, Supabase runs a deployment workflow; the migrate step applies pending database migrations (and vault secrets); if a parent step fails, dependent steps are skipped.1
Three consequences:
- The migration in the pull request is the production change. There’s no separate “apply” step for a person to run later, unless you build one.
- A failed migration stops the deploy. Good: dependent steps are skipped.1 Plan what you’ll do with a half-applied change; migrations that wrap their work in one transaction make that simpler.
- Who can merge decides who can change production. Branch protection and required reviews on the default branch are your migration approval process.
Reviewing an agent’s migration pull request
A short review routine for migrations an agent wrote:
| Check | Why |
|---|---|
| Read every statement in the new migration file | It runs on production at merge1 |
Look for DROP, TRUNCATE, DELETE, type changes and NOT NULL additions |
The usual data-loss and lock risks |
| Check the preview branch ran it cleanly | Schema builds from migrations on the branch1 |
| Check it against a realistic seed, not only an empty database | No data by default hides size problems |
| Confirm a backup or point-in-time restore exists for production | Our Supabase restore post covers what each plan keeps |
| Require a human approval on the pull request | Merge is deploy |
If the agent edited an existing migration file instead of adding a new one, stop: a migration that already ran in production won’t run again, and the branch and production will disagree.
Giving the agent a branch to work in
Preview branches also make a good sandbox for the agent itself, not just for CI. When an agent needs a database while it writes code:
- Open the pull request early, so the preview branch exists.
- Give the agent that branch’s credentials, and nothing for production.
- Let it run migrations, seed data and break things there.
- Close the pull request when you’re done; the branch is deleted with it.1
The agent never holds a production key, and the work it did on the database is visible as migrations in the pull request rather than as changes nobody wrote down.
Supabase and Neon side by side
| Supabase preview branch | Neon branch from a pull request | |
|---|---|---|
| Starts with data | No, by default1 | Yes, a copy-on-write clone of the parent |
| Credentials | Its own instance and API keys1 | A connection string for the branch |
| On merge | Deployment workflow applies migrations to production1 | Your pipeline decides |
| Cleanup | Deleted on merge or close1 | Delete action or expires_at |
Neon’s approach catches size and data problems; Supabase’s keeps data out. Our Neon branch-per-PR post covers that side, and we compare branching products in database branches compared.
A checklist
- GitHub integration on; every agent pull request gets a preview branch.
- Agents work against preview branches, with that branch’s credentials only.
- A realistic seed file, so migrations meet more than an empty table.
- Required human review on the default branch; merge treated as deploy.
- Migrations are new files, never edits to applied ones.
- Production backups or point-in-time recovery in place before merging risky migrations.
- Persistent branches used for staging only, with their own data rules.
For the MCP side of Supabase, see is Supabase MCP safe?. To check agent configs and workflows on each pull request, add the Deedglass scan Action; locally, paste a config into the check page or run npx deedglass scan (how the grade works); to try tool-call rules in your browser, open the playground.
Written with AI assistance and checked against our claims register.