mirror of
https://github.com/supabase/supabase.git
synced 2026-10-10 03:45:06 +03:00
Tina HaandClaude Opus 4.7
25fcf26c55
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update ## What is the current behavior? The dashboard branching guide doesn't mention that the first "Create branch" action on a project requires Owner/Administrator access. Combined with cosmetic UI behavior: the branch dropdown displays `main / PRODUCTION` on every project from day one, even though the backend hasn't registered a production branch yet. Developer-role users hit a 403 with a generic "Not authorized to enable preview branching" toast on their first branch attempt, with no docs or UI hint that an implicit production-branch registration step is happening. Customer-reported in [SU-383693](https://supabase.frontapp.com/open/cnv_1mz95u3i?key=wbyHQkruuZ_KYRGnRPB5_yHzm5-fr_k4) ## What is the new behavior? Adds an admonition under the "Creating a branch" heading in the dashboard-branching guide explaining: - The cosmetic UI vs. backend state mismatch (`main / PRODUCTION` shown before any row exists) - That the first "Create branch" click is what technically enables branching on the project (populates `preview_branches` with`is_default = true`) - This step requires Owner/Administrator access - After that one-time step, anyone with the Developer role can create, update, and delete preview branches Scoped to the gitless dashboard flow only. The GitHub-integrated path bootstraps automatically during admin-only integration setup. ## Additional context - Mechanism confirmed with the team in [Slack](https://supabase.slack.com/archives/C02BJ2239GA/p1779978863774239) "the first time branching is used we populate the preview_branches table with the base project and have is_default set as true. This is technically what enables branching. A developer role can't do that." - Related FE improvement being escalated separately (clearer error message and/or disabling the Create branch button for Developers when the production branch hasn't been registered yet) - The [Branching 2.0 announcement](https://supabase.com/blog/branching-without-git-is-now-the-default) (May 2026) made gitless branching the default for new projects, and more customers can walk into the dashboard flow without ever touching GitHub integration. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added clarification on dashboard branching behavior when GitHub integration is not configured, including details on branch dropdown display and initial setup requirements with permission levels. <!-- review_stack_entry_start --> [](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46471?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) <!-- review_stack_entry_end --> <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
72 lines
4.0 KiB
Plaintext
72 lines
4.0 KiB
Plaintext
---
|
|
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.
|
|
|
|
<Admonition type="note" title="Public Alpha">
|
|
|
|
Branch management via the 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:
|
|
|
|
- Create preview branches
|
|
- Make changes to your public schema or edge functions
|
|
- Merge these changes back into production when ready
|
|
- Pull in updates from production
|
|
|
|
## Enable branch management via the dashboard
|
|
|
|
This functionality is currently in beta and requires opting in. To opt in you must enable the feature preview:
|
|
|
|
1. Open the user menu by clicking on your user icon in the top right.
|
|
1. Select **Branching via dashboard**.
|
|
1. Click **Enable feature**.
|
|
|
|
## Creating a branch
|
|
|
|
<Admonition type="note">
|
|
|
|
When using dashboard branching without a GitHub integration, the branch dropdown displays `main / PRODUCTION` on every project, but on a brand-new project the production branch hasn't been registered yet. The first "Create branch" click populates this row behind the scenes — technically enabling branching on the project — and requires Owner/Administrator access. After that one-time step, anyone with the Developer role can create, update, and delete preview branches.
|
|
|
|
</Admonition>
|
|
|
|
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`.
|
|
|
|
## Making changes to a 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 now made against 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.
|
|
|
|
## Creating a merge request
|
|
|
|
To review and merge changes from a branch back into your production branch, you must first create a merge request. There are two ways to do this.
|
|
|
|
The first is to click the merge request button next to the branch selector that's located in the top menu. This will create the merge request and redirect you to the merge page where you can review and merge any changes.
|
|
|
|
The second is to click on manage branches from within the branch selector, then in the left hand navigation you can click on merge requests. From here you can view all open merge requests and create new ones.
|
|
|
|
## Pulling changes from production into a branch
|
|
|
|
When reviewing a merge request you may see a notice at the top of the page asking you to update your branch. This appears when your preview branch has drifted from your production branch. There may be public schema or edge function changes that have been made after your preview branch was created. Clicking update branch will attempt to pull in these changes, but be aware that by doing this your existing edge functions will be replaced. Any new edge functions created on the preview branch will remain untouched.
|
|
|
|
## Limitations
|
|
|
|
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
|
|
- 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
|
|
- Migration conflicts must be manually resolved on the preview branch
|
|
- If you have run migrations on main, new branches will be created from existing migrations instead of a full schema dump
|