Supabase

The Supabase plugin lets formae manage Supabase resources through the Supabase Management API (https://api.supabase.com): projects and their nested configuration, preview branches, project API keys, Edge Functions, and Edge Function secrets.

Repository: formae-plugin-supabase

Installation

Install from the platform.engineering hub:

formae plugin install supabase

Configuration

Target

Configure a Supabase target in your Forma file. Every field is optional — a bare Config {} is enough to deploy and to discover every project the access token can see:

import "@formae/formae.pkl"
import "@supabase/supabase.pkl"

target: formae.Target = new formae.Target {
    label = "supabase"
    config = new supabase.Config {}
}

Field	Description	Default
baseUrl	Override the Management API base URL.	https://api.supabase.com
projectRef	Advanced / conformance-only. Scopes sub-resource List() and discovery (Branch, APIKey, EdgeFunction, Secrets) to a single project. Leave unset in normal use — discovery then walks every project the token can see. Project discovery is always global regardless of this field.	unset

Credentials

The plugin reads a Supabase Personal Access Token from the environment — it is never stored in the target config. Create one at https://supabase.com/dashboard/account/tokens.

export SUPABASE_ACCESS_TOKEN="sbp_..."

Set it before starting the formae agent.

Examples

Examples live in the plugin repository. Clone the repo and resolve Pkl dependencies before running:

git clone https://github.com/platform-engineering-labs/formae-plugin-supabase.git
cd formae-plugin-supabase
pkl project resolve examples/full-project

Available examples (all require SUPABASE_ACCESS_TOKEN):

Example	Shows	Also needs
full-project	A whole stack from one apply: Project + nested config, API keys, a secret, and an Edge Function wired via project.res.id. DB password is a formae-managed secret.	SUPABASE_ORG_ID
branching	Preview environments: a persistent develop branch plus a git-tracked ephemeral branch.	SUPABASE_PROJECT_REF (paid plan)
edge-secrets	An Edge Function plus the write-only secrets it reads.	SUPABASE_PROJECT_REF
basic	The smallest possible forma: one Edge Function.	SUPABASE_PROJECT_REF
discover	A bare target; the agent discovers every project the token can see.	—

# Evaluate an example
formae eval examples/full-project/main.pkl

# Apply resources
formae apply --mode reconcile --watch examples/full-project/main.pkl

Supported Resources

Five resource types across three namespaces. Each implements full Create, Read, Update, Delete, and List, with async Status polling where the API is asynchronous.

Type	Description	Native ID	Discoverable	Extractable
SUPABASE::Platform::Project	A Supabase project. Async create — polls to ACTIVE_HEALTHY; provisioning bills the account and takes ~2–3 min. Carries optional nested auth, API, database, and network-restriction config blocks.	id	Yes	No
SUPABASE::Platform::Branch	A preview branch on a project. Async; requires a paid plan.	id	Yes	No
SUPABASE::Auth::APIKey	A publishable or secret project API key. Reference it from other resources via .res.apiKey.	id	Yes	No
SUPABASE::Functions::EdgeFunction	An Edge Function deployed from an inline JS/TS (Deno) body.	slug	Yes	No
SUPABASE::Functions::Secrets	All of a project's Edge Function secrets as one bag (values is a name→value map).	projectRef	Yes	No

What's next

• Learn more about resolvables in Res
• See Values for managed secrets like dbPass
• See Discovery for how the bare-target scan finds projects

Release notes

See release notes for changes per version.