From 25fcf26c55ac93c96d718d3a21a31bf0d23df57a Mon Sep 17 00:00:00 2001 From: Tina Ha Date: Fri, 29 May 2026 05:43:02 -0400 Subject: [PATCH] docs(branching): note admin requirement for first branch in dashboad (#46471) ## 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. ## 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 Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46471?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) Co-authored-by: Claude Opus 4.7 (1M context) --- apps/docs/content/guides/deployment/branching/dashboard.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/apps/docs/content/guides/deployment/branching/dashboard.mdx b/apps/docs/content/guides/deployment/branching/dashboard.mdx index e3367f382fe..ad1ae7021c8 100644 --- a/apps/docs/content/guides/deployment/branching/dashboard.mdx +++ b/apps/docs/content/guides/deployment/branching/dashboard.mdx @@ -30,6 +30,12 @@ This functionality is currently in beta and requires opting in. To opt in you mu ## Creating a branch + + +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. + + + 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`.)