Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(branching): explain what a new branch inherits and what each push runs (#51753)

Wen Bo Xie626f0d412a5f
diff --git a/apps/docs/content/guides/deployment/branching.mdx b/apps/docs/content/guides/deployment/branching.mdx
index d4f3ed3ca11..db01c8e408d 100644
--- a/apps/docs/content/guides/deployment/branching.mdx
+++ b/apps/docs/content/guides/deployment/branching.mdx
@@ -7,27 +7,42 @@ You can deploy directly from GitHub on any plan — connect your repository and
Use branching to safely experiment with changes to your Supabase project.
-Supabase branches create separate environments that spin off from your main project. You can use these branching environments to create and test changes like new configurations, database schemas, or features without affecting your production setup. When you're ready to ship your changes, merge your branch to update your production instance with the new changes.
+Supabase branches create separate environments that spin off from your base project. You can use these branching environments to create and test changes like new configurations, database schemas, or features without affecting your production setup. When you're ready to ship your changes, merge your branch to update your production instance with the new changes.
## How branching works
- **Separate Environments**: Each branch is a separate environment with its own Supabase instance and API credentials.
- **Preview Branches**: Preview branches are ephemeral and best suited for focused testing. They are automatically deleted when a PR is merged or closed.
- **Persistent Branches**: Persistent branches are long-lived and recommended for environments like staging, QA, or development. They aren't automatically paused or deleted due to inactivity or when a PR is merged or closed.
-- **Managing Branches**: You can create, review, and merge branches either automatically via our [GitHub integration](/docs/guides/deployment/branching/github-integration) or directly [through the dashboard](/docs/guides/deployment/branching/dashboard) (currently in beta). All branches show up in the branches page in the dashboard, regardless of how they were created.
-- **Cloned from your main project**: Each new branch is created as a clone of your main project. It starts with that project's Edge Functions deployed and the configuration set.
-- **Data-less by default**: By default, new branches do not start with any data or storage objects from your main project. This is meant to better protect your sensitive production data. To start your branches with data, you can use a [seed file](/docs/guides/deployment/branching/github-integration#seeding) if using the GitHub integration, or the [Include data](/docs/guides/deployment/branching/dashboard#include-production-data) option if you create the branch from the dashboard.
+- **Managing Branches**: You can create, review, and merge branches either automatically via our [GitHub integration](/docs/guides/deployment/branching/github-integration) or directly [through the Supabase Dashboard](/docs/guides/deployment/branching/dashboard) (currently in beta). All branches show up in the branches page in the dashboard, regardless of how they were created.
+- **Cloned from your base project**: Each new branch is created as a clone of your base project. It starts with that project's Edge Functions deployed and the configuration set.
+- **Data-less by default**: By default, new branches do not start with any data or storage objects from your base project. This is meant to better protect your sensitive production data. To start your branches with data, you can use a [seed file](/docs/guides/deployment/branching/github-integration#seeding) if using the GitHub integration, or the [Include data](/docs/guides/deployment/branching/dashboard#include-production-data) option if you create the branch from the Supabase Dashboard.
+
+## What a new branch starts with
+
+Whether you create a branch from a pull request or from the Supabase Dashboard, Supabase creates a project with default settings then copies these settings from your base project:
+
+- Postgres settings
+- Connection pooler settings
+- Auth, Data API, Realtime, and Storage settings
+- SSL enforcement
+- Network restrictions, when your base project has them
+- Deployed Edge Functions
+
+Auth secrets, such as OAuth provider secrets and SMTP passwords, get placeholder values instead. Set the real values with [branch secrets](/docs/guides/deployment/branching/configuration#managing-secrets-for-branches). Supabase also turns on Database Webhooks for every branch.
+
+The database schema isn't cloned. A GitHub-connected branch builds it from the [migrations in your repository](/docs/guides/deployment/branching/github-integration#migrations). A dashboard branch builds it from your [base project's migration history](/docs/guides/deployment/branching/dashboard#where-a-dashboard-branch-gets-its-schema). The branch is ready when the settings, the schema, and the Edge Functions are all in place.
## Deploying to production
-When you merge any branch into your main project, Supabase automatically runs a deployment workflow to deploy your changes to production. The deployment workflow is expressed as a Directed Acyclic Graph where each node represents one of the following deployment steps.
+When you merge any branch into your base project, Supabase automatically runs a deployment workflow to deploy your changes to production. The deployment workflow is expressed as a Directed Acyclic Graph where each node represents one of the following deployment steps.
1. **Clone** - Checks out your repository at the specified git branch (optional for [Branching via Dashboard](/docs/guides/deployment/branching/dashboard))
-2. **Pull** - Retrieves database migrations from your main project (also initialises the migration history table when Branching via Dashboard)
+2. **Pull** - Retrieves database migrations from your base project (also initialises the migration history table when Branching via Dashboard)
3. **Health** - Waits up to 2 minutes for all Supabase services on your branch to be running and healthy, including Auth, API, Database, Storage, and Realtime
4. **Configure** - Updates service configurations based on your config.toml file (only available for [Branching via GitHub](/docs/guides/deployment/branching/github-integration))
5. **Migrate** - Applies pending database migrations and vault secrets to your branch
6. **Seed** - Runs seed files to populate your branch with initial data (must be [enabled in config.toml](/docs/guides/deployment/branching/configuration#branch-configuration-with-remotes) for persistent branches)
7. **Deploy** - Deploys any changed Edge Functions and updates function secrets
-If a parent deployment step fails, all dependent child steps will be skipped. For instance, if your database migrations failed at step 5, our runner will not seed your branch because step 6 is skipped. If you are using GitHub integration, the same deployment workflow will be run on every commit pushed to your git branch.
+If a parent deployment step fails, all dependent child steps are skipped. For instance, if your database migrations fail at step 5, our runner doesn't seed your branch because step 6 is skipped. If you are using GitHub integration, the same deployment workflow runs on every commit pushed to your git branch. To check each step's status in the Supabase Dashboard, see [Monitoring deployments](/docs/guides/deployment/branching/troubleshooting#monitoring-deployments).
diff --git a/apps/docs/content/guides/deployment/branching/dashboard.mdx b/apps/docs/content/guides/deployment/branching/dashboard.mdx
index e10efb1c2ce..767c6540f6d 100644
--- a/apps/docs/content/guides/deployment/branching/dashboard.mdx
+++ b/apps/docs/content/guides/deployment/branching/dashboard.mdx
@@ -3,17 +3,17 @@ title: 'Branching via the dashboard'
subtitle: 'Create, manage, review, and merge branches directly in the dashboard'
---
-You can create, manage, review, and merge Supabase branches directly via the dashboard. This is useful for quick testing, prototyping, or when you prefer to work in a no-code way. You can also connect a Supabase branch to a GitHub branch at a later time if needed.
+You can create, manage, review, and merge Supabase branches directly in the Supabase Dashboard. This is useful for quick testing, prototyping, or when you prefer to work in a no-code way. You can also connect a Supabase branch to a GitHub branch at a later time if needed.
<Admonition type="note" title="Public Alpha">
-Branch management via the dashboard is currently in public alpha. Features and functionality may change.
+Branch management in the Supabase Dashboard is currently in public alpha. Features and functionality may change.
</Admonition>
## How Branching works
-You can do the following directly from the Supabase dashboard:
+You can do the following directly from the Supabase Dashboard:
- Create preview branches
- Make changes to your public schema or edge functions
@@ -41,7 +41,11 @@ Once you've enabled the feature, you can create a new branch:
1. Click the arrows next to the branch name in the top menu bar. (The top menu bar has the format `YOUR_ORGANIZATION / YOUR_PROJECT / CURRENT_BRANCH_NAME`.)
2. Click `Create branch`.
-The new branch is a clone of your base project. It starts with the project's schema, Edge Functions, and the configuration set.
+The new branch is a clone of your base project. It starts with the project's schema, Edge Functions, and the configuration set. For the full list of what it inherits, see [What a new branch starts with](/docs/guides/deployment/branching#what-a-new-branch-starts-with).
+
+### Where a dashboard branch gets its schema
+
+A dashboard branch has no git branch to read migrations from. Instead, it reads your base project's migration history and applies each entry as a migration. The branch ends up with the same schema as your base project. If your base project has no migration history, the branch dumps the base project's schema and uses the dump as its first migration.
### Include production data
@@ -81,7 +85,7 @@ When reviewing a merge request you may see a notice at the top of the page askin
There are a few limitations you should be aware of before deciding to use branching without git.
-- Custom roles created through the dashboard are not captured on branch creation
+- Custom roles created through the Supabase Dashboard are not captured on branch creation
- Branches can only be merged to main; merging between preview branches is not supported
- If your branch is out of date, you can pull in latest changes from main, but keep in mind that all functions will be overwritten
- Deleting functions must be done manually on main branch
diff --git a/apps/docs/content/guides/deployment/branching/github-integration.mdx b/apps/docs/content/guides/deployment/branching/github-integration.mdx
index c9ae8315c2d..74e2e265a7a 100644
--- a/apps/docs/content/guides/deployment/branching/github-integration.mdx
+++ b/apps/docs/content/guides/deployment/branching/github-integration.mdx
@@ -43,7 +43,7 @@ You will be using the [Supabase CLI](/docs/guides/local-development) to initiali
<StepHikeCompact.Step step={2}>
<StepHikeCompact.Details title="Pull your database migration" fullWidth>
- Pull your database changes using `supabase db pull`. To get your database connection string, go to your project dashboard, click [Connect](/dashboard/project/_?showConnect=true&method=session) and look for the Session pooler connection string.
+ Pull your database changes using `supabase db pull`. To get your database connection string, open the Supabase Dashboard, click [Connect](/dashboard/project/_?showConnect=true&method=session) and look for the Session pooler connection string.
```markdown
supabase db pull --db-url <db_connection_string>
@@ -83,13 +83,23 @@ Enable the **Automatic branching** option in your GitHub Integration configurati
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.)
-Every Supabase branch, preview or persistent, is created as a clone of your base project. The new branch starts with the Edge Functions and configuration of that project. Its database schema is not cloned. Instead, it is built from the migrations you commit to your repository.
+Every Supabase branch, preview or persistent, is created as a clone of your base project. The new branch starts with the Edge Functions and configuration of that project. Its database schema is not cloned. Instead, it is built from the migrations you commit to your repository. For the full list of what a branch inherits, see [What a new branch starts with](/docs/guides/deployment/branching#what-a-new-branch-starts-with).
+
+### What runs on each push
+
+After Supabase creates the branch and copies your base project's settings, it runs the branching workflow against the files in your repository. The workflow applies your `config.toml` first, then runs any migrations the branch hasn't applied yet. After that it seeds the database and Storage buckets, and finally deploys your Edge Functions. On a persistent branch, including your production branch, the `config.toml` and seed steps apply only when a `[remotes]` block names that branch, as described in [Configuration](#configuration). The same workflow runs again on every push to the git branch. You don't need a GitHub Action to deploy migrations or sync `config.toml` to a branch.
+
+For what each step does, see [Deploying to production](/docs/guides/deployment/branching#deploying-to-production). To check a step's status and read its logs, see [Monitoring deployments](/docs/guides/deployment/branching/troubleshooting#monitoring-deployments).
### Configuration
You can test configuration changes on your Preview Branch by configuring the `config.toml` file in your Supabase directory. See the [Configuration docs](/docs/guides/deployment/branching/configuration) for more information.
-Your branch starts with the configuration of your base project. The settings in your `config.toml` file are applied on top of that clone.
+Supabase applies the settings in your `config.toml` on top of the configuration copied from your base project, and where the two differ, your repository wins.
+
+The `configure` step compares the `[db]`, `[api]`, `[auth]`, `[storage]`, and `[experimental]` sections of `config.toml` with the branch's current settings and updates the ones that differ. The migrate, seed, and deploy steps read the other sections, such as `[functions]` and `[db.seed]`. If your repository has no `config.toml`, the step only turns on Database Webhooks.
+
+On a persistent branch, including your production branch, the step runs only when a `[remotes]` block names that branch's project ID. For the `[remotes]` syntax, see [Remote-specific configuration](/docs/guides/deployment/branching/configuration#remote-specific-configuration).
A comment is added to your PR with the deployment status of your preview branch.
@@ -97,11 +107,18 @@ A comment is added to your PR with the deployment status of your preview branch.
The migrations in the `migrations` subdirectory of your Supabase directory are automatically run when the branch is created. Each later commit runs only the migrations that haven't been applied yet.
+The `migrate` step compares the files in `supabase/migrations` with the branch's migration history and applies every file without a history entry. Before it runs them, it saves the Vault secrets declared under `[db.vault]` to the branch. Keep two cases in mind:
+
+- A migration file with a timestamp older than the latest applied migration still runs and the step finishes with a warning.
+- A version in the branch's migration history with no matching file fails the step.
+
+To stop branching from running migrations, set `enabled = false` under `[db.migrations]` in `config.toml`.
+
If your project uses [declarative schemas](/docs/guides/local-development/declarative-database-schemas), the files in `supabase/schemas/` are not applied by branching. Run `supabase db schema declarative sync` to generate a migration from your schema changes, and commit the generated migration alongside your schema files.
Branching runs each migration file inside a single transaction and does not honor the `-- pg-delta: transaction=false` directive. A migration that can't run in a transaction (for example, one that uses `create index concurrently`, or a [`pg-delta`](/docs/guides/local-development/diff-engines) file that carries the directive) applies with `supabase db push` but fails when branching deploys it.
-If you want to rerun existing migrations, reset the branch from the Supabase dashboard to start from scratch. Note that existing data on your branch will also be dropped by a reset.
+If you want to rerun existing migrations, reset the branch from the Supabase Dashboard to start from scratch. Note that existing data on your branch will also be dropped by a reset.
### Seeding
@@ -111,6 +128,15 @@ You can seed your Preview Branch with sample data using the `seed.sql` file in y
Data changes in your seed files are not merged to production.
+### Edge Functions
+
+Edge Functions reach your branch in the `deploy` step, the last step of the workflow. The step saves the function secrets declared under `[edge_runtime.secrets]` then deploys functions:
+
+- If your repository has a `supabase/functions` directory, the step deploys the functions declared in `config.toml` under `[functions.<slug>]`. If the directory has functions but `config.toml` declares none, the step deploys nothing and finishes with a warning.
+- If your repository has no functions directory, the step copies the functions deployed on your base project. `config.toml` can still disable a copied function or change its JWT verification.
+
+A function is uploaded again only when it changed. For each function, the step compares the checksum of the new bundle and the JWT verification setting against the version already deployed on the branch. If both are the same, the step skips that function.
+
## Deploying changes to production
Enable the **Deploy to production** option in your GitHub Integration configuration to automatically deploy changes when you push or merge to production branch.
diff --git a/apps/docs/content/guides/deployment/branching/troubleshooting.mdx b/apps/docs/content/guides/deployment/branching/troubleshooting.mdx
index 8970d6daada..06f1b79c4dc 100644
--- a/apps/docs/content/guides/deployment/branching/troubleshooting.mdx
+++ b/apps/docs/content/guides/deployment/branching/troubleshooting.mdx
@@ -10,11 +10,23 @@ This guide covers common issues you might encounter when using Supabase branchin
To check deployment status and troubleshoot failures:
-1. Go to your project dashboard
+1. Open the Supabase Dashboard
2. Navigate to "Manage Branches"
3. Click on your branch to view deployment logs
4. Check the "View logs" section for detailed error messages
+Each step in a workflow run reports one of these statuses:
+
+| Status | Meaning |
+| --------- | ----------------------------------------------------------------------------------- |
+| `CREATED` | The step hasn't started. |
+| `RUNNING` | The step is in progress. |
+| `EXITED` | The step succeeded. |
+| `PAUSED` | The step finished with a warning, or was skipped on purpose. Later steps still run. |
+| `DEAD` | The step failed. Steps that depend on it don't run. |
+
+A failed health check is a warning. The `health` step shows `PAUSED` and the workflow continues. A `DEAD` `migrate` step stops the `seed` and `deploy` steps.
+
For programmatic monitoring, you can use the [Management API](https://api.supabase.com/api/v1#tag/environments/post/v1/projects/{ref}/branches) to poll branch status.
For detailed troubleshooting guidance, see our [Troubleshooting guide](/docs/guides/deployment/branching/troubleshooting).
@@ -29,7 +41,7 @@ To fix this, push the latest changes, then delete the preview branch in Supabase
The new preview branch is a fresh clone of your base project and is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost.
-To rerun migrations that your base project has already applied, reset the branch from the Supabase dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.
+To rerun migrations that your base project has already applied, reset the branch from the Supabase Dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.
### Deployment failures
@@ -123,6 +135,8 @@ If configuration changes aren't applying:
1. **Syntax errors**: Validate your `config.toml` syntax
2. **Git sync**: Ensure changes are committed and pushed
3. **Branch refresh**: Try deleting and recreating the branch
+4. **Persistent branch**: Configuration runs on a persistent branch, including your production branch, only when a `[remotes]` block names its project ID. For the `[remotes]` syntax, see [Remote-specific configuration](/docs/guides/deployment/branching/configuration#remote-specific-configuration)
+5. **Section not applied by branching**: The `configure` step applies only the `[db]`, `[api]`, `[auth]`, `[storage]`, and `[experimental]` sections. For which steps read the other sections, see [Configuration](/docs/guides/deployment/branching/github-integration#configuration)
### Secrets not available
@@ -172,7 +186,7 @@ Remember that preview branch data:
If you're still experiencing issues:
-1. **Check logs**: Review branch logs in the dashboard
+1. **Check logs**: Review branch logs in the Supabase Dashboard
2. **Community**: Ask in [GitHub discussions](https://github.com/orgs/supabase/discussions/18937)
3. **Support**: Contact support for project-specific issues
4. **Documentation**: Review the latest documentation for updates