deployment

428 notes in this subject, read out of this brain and free to use. This is page 1 of 8.

Supabase deployment automation options

You can automate Supabase deployments using three methods: (1) The Supabase GitHub integration (recommended, deploys from main branch, works on all plans, can create preview environments for pull requests with branching on Pro Plan), (2) The Supabase CLI in your own continuous deployment pipeline, (3) The Supabase Terraform provider.

Git collaboration workflow with Supabase

Use Git branches to work on changes independently and share them with your team. When a change is ready, merge it into main to deploy it to production. On the Pro Plan with branching enabled, each pull request automatically gets a preview environment, allowing you to review and test database changes before they go live.

GitHub integration not required for Supabase deployment

GitHub integration is recommended but not required for Supabase deployment. You can deploy using the Supabase CLI in your own CI/CD pipeline without connecting a GitHub repository.

Recommended Supabase deployment workflow

The recommended workflow for deploying a Supabase project is: (1) Develop locally using the Supabase CLI, (2) Push changes to your GitHub repository, (3) Deploy automatically to your Supabase project from your main branch. This workflow works on all plans and does not require branching. If branching is enabled on the Pro Plan, you can extend this workflow with preview environments for pull requests.

Supabase branching feature requirements

Branching is an optional feature available exclusively on the Pro Plan. It creates isolated preview environments for each pull request, so you can test database changes before merging. Each pull request gets its own isolated Supabase environment with a full copy of the database schema (without any production data).

CI/CD systems compatible with Supabase CLI

You can use the Supabase CLI or the Terraform provider in any CI/CD system including GitHub Actions, GitLab CI, and CircleCI.

What gets deployed from Supabase local directory

When deploying from Supabase, the following items get deployed: database migrations in your supabase/ directory, plus Edge Functions and storage buckets that are declared in supabase/config.toml. Other local configuration files such as API or Auth settings are ignored by default.

Supabase environment management strategy

Supabase projects typically maintain three environments: Development (develop locally using the Supabase CLI), Staging/Preview (optional, use branching to create preview environments for pull requests or long-lived staging environments on Pro Plan), and Production (deploy changes from GitHub repository or custom CI/CD pipeline).

Deployment workflow steps

The deployment workflow consists of the following steps in order: (1) Clone - checks out the repository at the specified git branch (optional for dashboard branching); (2) Pull - retrieves database migrations from the main project and initializes the migration history table for dashboard branching; (3) Health - waits up to 2 minutes for all Supabase services (Auth, API, Database, Storage, and Realtime) to be running and healthy; (4) Configure - updates service configurations based on config.toml file (only for GitHub integration); (5) Migrate - applies pending database migrations and vault secrets; (6) Seed - runs seed files to populate the branch with initial data (must be enabled in config.toml for persistent branches); (7) Deploy - deploys changed Edge Functions and updates function secrets.

Branching overview and purpose

Supabase branching creates isolated preview environments for each pull request. Branches are separate environments with their own Supabase instance and API credentials, allowing you to safely experiment with changes to configurations, database schemas, or features without affecting production.

Deployment step failure behavior

If a parent deployment step fails, all dependent child steps are skipped. For example, if database migrations fail at step 5, the seed step (step 6) will not run. GitHub integration runs the same deployment workflow on every commit pushed to a git branch.

Preview branches characteristics

Preview branches are ephemeral and best suited for focused testing. They are automatically paused after inactivity or deleted when a PR is merged or closed.

Branch management methods

You can create, review, and merge branches either automatically via GitHub integration or directly through the dashboard (currently in beta). All branches appear on the branches page in the dashboard regardless of creation method.

Persistent branches characteristics

Persistent branches are long-lived and recommended for environments like staging, QA, or development. Unlike preview branches, they are not automatically paused or deleted due to inactivity or when a PR is merged or closed.

Branch data initialization

New branches do not start with any data from the main project to protect sensitive production data. To start branches with data, you can use a seed file if using the GitHub integration.

Automatic deployment on merge

When you merge any branch into the main project, Supabase automatically runs a deployment workflow to deploy changes to production. The workflow is expressed as a Directed Acyclic Graph with multiple sequential steps.

Feature branch configuration example with OAuth

Example feature branch configuration: [remotes.feature-oauth] project_id = "feature-branch-ref" [remotes.feature-oauth.auth.external.google] enabled = true client_id = "env(GOOGLE_CLIENT_ID)" secret = "env(GOOGLE_CLIENT_SECRET)"

Secrets are branch-specific and isolated

Secrets set for one branch are not automatically available in other branches. You must set them separately for each branch that needs them.

Available configuration options in remotes block

All standard configuration options are available in the [remotes] block, including database settings, API configurations, authentication settings, edge functions configuration, and more. This allows maintaining different configurations for different environments while keeping them all in version control.

config.toml automatic sync with Git branches

When Branching is enabled, config.toml settings automatically sync to all ephemeral branches through a one-to-one mapping between Git and Supabase branches. To update configuration for a Supabase branch, modify config.toml and push to git. The Supabase integration will detect the changes and apply them to the corresponding branch.

Staging-specific seed script configuration example

Example of configuring a separate seed script for a staging environment: [remotes.staging] project_id = "your-project-ref" [remotes.staging.db.seed] enabled = true sql_paths = ["./seeds/staging.sql"]

Multi-environment config.toml example

Example configuration with default settings for all branches and environment-specific overrides: [api] enabled = true port = 54321 schemas = ["public", "storage", "graphql_public"] [db] port = 54322 pool_size = 10 [remotes.staging] project_id = "staging-project-ref" [remotes.staging.api] max_rows = 1000 [remotes.staging.db.seed] sql_paths = ["./seeds/staging.sql"] [remotes.production] project_id = "prod-project-ref" [remotes.production.api] max_rows = 500 [remotes.production.db] pool_size = 25

Secret fields supporting encrypted syntax in config.toml

The following fields support the encrypted: syntax: Studio: studio.openai_api_key. Database: db.root_key, db.vault.* (any key in vault map). Auth Core Keys: auth.publishable_key, auth.secret_key, auth.jwt_secret. Auth Email SMTP: auth.email.smtp.pass. Auth Captcha: auth.captcha.secret. Auth Hooks: auth.hook.mfa_verification_attempt.secrets, auth.hook.password_verification_attempt.secrets, auth.hook.custom_access_token.secrets, auth.hook.send_sms.secrets, auth.hook.send_email.secrets, auth.hook.before_user_created.secrets. Auth SMS Providers: auth.sms.twilio.auth_token, auth.sms.twilio_verify.auth_token, auth.sms.messagebird.access_key, auth.sms.textlocal.api_key, auth.sms.vonage.api_secret. Auth External OAuth Providers: auth.external.*.secret. Edge Runtime: edge_runtime.secrets.* (any key in secrets map).

Using environment variables in config.toml

Environment variables can be referenced in config.toml using the env() syntax. Example: [auth.external.github] enabled = true client_id = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_CLIENT_ID)" secret = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET)". Variables are made available to branch services through the secrets set CLI command or environment files.

Using encrypted config with preview branches

When you commit your .env.preview file with encrypted values, the branching executor will automatically retrieve and use these values when deploying your branch. This allows you to maintain different configurations for different branches while keeping sensitive information secure.

Using SMTP configuration with secrets in config.toml

SMTP configuration can reference secrets set via CLI. Example: [auth.smtp] host = "env(SMTP_HOST)" user = "env(SMTP_USER)" password = "env(SMTP_PASSWORD)". These must be set first using: supabase secrets set SMTP_HOST=smtp.example.com and similar commands for other fields.

Configuration merging behavior for persistent branches

When merging a PR into a persistent branch, the Supabase integration checks for configuration changes, logs them, and applies them to the target remote. If no remote is declared or the project ID is incorrect, the configuration step is skipped.

dotenvx environment file structure for branch configuration

When using dotenvx for managing environment variables across branches, use the following files in the supabase directory: .env.keys (All environments, .gitignore it, not encrypted), .env.local (Local, .gitignore it, not encrypted), .env.production (Production, do not .gitignore, encrypted), .env.preview (Branches/preview, do not .gitignore, encrypted), .env (Any, maybe .gitignore, encrypted).

Remote-specific configuration in config.toml

For persistent branches that need specific settings, use the [remotes] block in config.toml. Each remote configuration must reference an existing project ID. A persistent branch must be created via CLI before adding its configuration using the command: supabase --experimental branches create --persistent

Setting branch secrets via CLI

Use the Supabase CLI to manage secrets for branches. Set secrets from a .env file with: supabase secrets set --env-file ./supabase/.env. Or set individual secrets with: supabase secrets set SMTP_HOST=smtp.example.com. These secrets will be available to the branch's services and can be used in config.toml using env() syntax.

Retrieve project ID for branch configuration

To retrieve the project ID for an existing branch, use the CLI command: supabase --experimental branches list. This displays a table showing all branches with their corresponding project ID. Use the value from the BRANCH PROJECT ID column as your project_id in the remote configuration.

Generate and manage encrypted secrets with dotenvx

To generate key pair and encrypt secrets: npx @dotenvx/dotenvx set SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET "<your-secret>" -f supabase/.env.preview. This creates a new encryption key in supabase/.env.preview and a new decryption key in supabase/.env.keys. Then update project secrets with: npx supabase secrets set --env-file supabase/.env.keys

Using encrypted values in config.toml

Encrypted values can be used directly in config.toml with the encrypted: syntax, but only for designated secret fields. Example: [auth.external.github] enabled = true secret = "encrypted:<encrypted-value>". For non-secret fields, use environment variables with env() syntax instead.

Creating a merge request

To review and merge changes from a branch back into production, create a merge request by clicking the merge request button next to the branch selector in the top menu, or by clicking 'manage branches' in the branch selector, then 'merge requests' in the left navigation.

Pulling changes from production into a branch

When reviewing a merge request, if your preview branch has drifted from the production branch, you may see a notice asking you to update your branch. Clicking 'update branch' pulls in public schema or edge function changes from production, but existing edge functions will be replaced. Any new edge functions created on the preview branch will remain untouched.

Making changes to a dashboard branch

Use the branch selector in the top bar to change to your branch. Any changes you make, including SQL run in the SQL editor, table editor changes, and configuration changes, are applied to the currently selected branch. You can also use the branch's API keys and connection strings to run changes against the branch from your own code or SQL client.

Dashboard branching limitations

Dashboard branching has the following limitations: custom roles created through the dashboard are not captured on branch creation; branches can only be merged to main (merging between preview branches is not supported); if a branch is out of date and you pull in changes from main, all functions will be overwritten; deleting functions must be done manually on the main branch; migration conflicts must be manually resolved on the preview branch; if migrations have been run on main, new branches will be created from existing migrations instead of a full schema dump.

Dashboard branching feature status

Branch management via the Supabase dashboard is currently in public alpha. Features and functionality may change.

Enable dashboard branching feature

Dashboard branching requires opting in. To enable it, open the user menu by clicking your user icon in the top right corner and select 'Branching via dashboard', then click 'Enable feature'.

Creating a branch via dashboard

To create a branch, click the arrows next to the branch name in the top menu bar (which has the format 'YOUR_ORGANIZATION / YOUR_PROJECT / CURRENT_BRANCH_NAME'), then click 'Create branch'.

Dashboard branching without GitHub integration

When using dashboard branching without a GitHub integration, the branch dropdown displays 'main / PRODUCTION' on every project. On a brand-new project, the production branch hasn't been registered yet until the first 'Create branch' action is performed.

Dashboard branching capabilities

Dashboard branching allows you to create preview branches, make changes to your public schema or edge functions, merge changes back into production when ready, and pull in updates from production.

Required status checks for migration safety

It is highly recommended to enable a 'required check' for the Supabase integration from your GitHub repository settings. This prevents PRs from being merged when migration checks fail and stops invalid migrations from being merged into your production branch.

Email notifications for branch failures

It is recommended to subscribe to email notifications on your branch to catch failures early. Common errors include migration conflict, function deployment failure, or invalid configuration file. You can setup a custom GitHub Action to monitor the status of any Supabase Branch.

GitHub Action for monitoring branch status

This GitHub Action monitors Supabase Branch deployment status and fails if the check fails. The action uses fountainhead/action-wait-for-check@v1.2.0, checks for the 'Supabase Preview' check, and exits with code 1 if the deployment failed.

Preview branch configuration

You can test configuration changes on your Preview Branch by configuring the config.toml file in your Supabase directory. A comment is added to your PR with the deployment status of your preview branch.

Working directory configuration

The working directory is the path from your repository root to the directory that contains the supabase/ folder. Enter . when supabase/ is at the repository root. If supabase/ is nested deeper, enter its parent directory instead. For example, if the layout is apps/web/supabase/, enter apps/web.

Preview branch seeding

No production data is copied to your Preview branch to protect sensitive production data. You can seed your Preview Branch with sample data using the seed.sql file in your Supabase directory. Data changes in your seed files are not merged to production.

Committing supabase directory to Git

After pulling database migrations, commit the supabase directory to Git using: git add supabase, git commit -m "Initial migration", and git push to push changes to your remote repository.

Production deployment configuration

Enable the Deploy to production option in your GitHub Integration configuration to automatically deploy changes when you push or merge to the production branch. The following changes are deployed: new migrations are applied, Edge Functions declared in config.toml are deployed, and storage buckets declared in config.toml are deployed. All other configurations, including API, Auth, and seed files, are ignored by default.

Automatic branching sync

Enable the Automatic branching option in your GitHub Integration configuration to automatically sync GitHub branches with Supabase branches. When a new branch is created in GitHub, a corresponding branch is created in Supabase. You can enable the Supabase changes only option to only create Supabase branches when Supabase files change.

GitHub integration installation steps

To install Supabase GitHub integration: 1) Go to Project Settings > Integrations in Supabase Dashboard. 2) Under GitHub Integration, click Authorize GitHub. 3) Authorize Supabase on the GitHub authorization page. 4) Choose a GitHub repository to connect to your project. 5) Set the Working directory field. 6) Configure other options to automate the GitHub connection. 7) Click Enable integration.

GitHub Action workflow for branch notifications

Example workflow file at .github/workflows/notify-failure.yaml that runs on pull requests to main or develop branches when supabase/ files change, waits for Supabase Preview check completion, and fails the workflow if the check failed: ```yaml name: Branch Status on: pull_request: types: - opened - reopened - synchronize branches: - main - develop paths: - 'supabase/**' jobs: failed: runs-on: ubuntu-latest steps: - uses: fountainhead/action-wait-for-check@v1.2.0 id: check with: checkName: Supabase Preview ref: ${{ github.event.pull_request.head.sha || github.sha }} token: ${{ secrets.GITHUB_TOKEN }} - if: ${{ steps.check.outputs.conclusion == 'failure' }} run: exit 1 ```

Vercel environment variables synchronization timing

Supabase automatically updates Vercel project environment variables for corresponding preview branches when a Pull Request is opened, not at the time of branch creation. This synchronization can have race conditions between Supabase setting variables and Vercel running deployment, so Supabase automatically re-deploys the most recent deployment of the given pull request.

Supabase branching with Vercel

Supabase branching integrates with Vercel by syncing the Git branch used by Vercel with the corresponding Supabase preview branch. This ensures that Vercel's preview deployment is matched to the correct database schema, edge functions, and other Supabase configurations.

Vercel integration setup requirements

To use Supabase branching with Vercel, you need to install the Vercel integration from the Vercel marketplace or by clicking the Deploy button in a Supabase example app's README file. You must also have the Vercel GitHub integration installed and connected your Supabase project to your Vercel project.

Supabase branching with hosting providers

Supabase branching works with hosting providers that support preview deployments. When integrated, the preview deployment built by the hosting provider is matched to the correct database schema, edge functions, and other Supabase configurations.

Using custom ORM or seed scripts with preview branches

If you want to use your own ORM for managing migrations and seed scripts instead of Supabase's default behavior, you must run them in GitHub Actions after the preview branch is ready. Branch credentials can be fetched using the Supabase CLI in a GitHub Actions workflow.

Branch webhook notification payload format

Branch action run completion webhooks follow the Standard Webhooks format. The payload includes: type (string, e.g., 'run.completed'), timestamp (ISO 8601), and data object containing project_ref, details_url, and action_run object with id, created_at, and steps array. Each step has name (clone, pull, health, configure, migrate, seed, deploy), status (e.g., 'exited'), and updated_at timestamp.

Subscribe to branch action run completion webhooks

You can register webhook notifications to be triggered when an action run completes on a persistent branch. The webhook payload follows Standard Webhooks format. A single webhook processor is recommended that dispatches events to downstream services based on the payload type. The easiest deployment method is using an Edge Function.

Give your agent this brain