> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/guides/manage-branches.md).

# Managing branches

Every app in FlowCP can expose **multiple branches**. Each branch is its own MCP server with an independent tool set, OAuth-backed execution context, and publish state, with its own `/mcp/<server-id>` endpoint.

> **Branches are most useful with the Bubble provider**, which maps them to Bubble's live and development environments (Live/Main, plus named branches). A **Generic OpenAPI** app starts with a single **Default** branch pointing at the document you connected; you can still add more branches manually if your API serves different environments at different URLs.

The rest of this guide describes the Bubble branch model in detail.

## How branches map to Bubble

Bubble serves your live app at the bare URL and development branches at `/version-<id>/` (Bubble's own URL format). FlowCP mirrors that:

| Branch             | Branch id      | Bubble URL (default)                              |
| ------------------ | -------------- | ------------------------------------------------- |
| **Live** (default) | `live`         | `https://<app-id>.bubbleapps.io/...`              |
| **Main** (default) | `version-test` | `https://<app-id>.bubbleapps.io/version-test/...` |
| Any added branch   | `version-<id>` | `https://<app-id>.bubbleapps.io/version-<id>/...` |

When you configure a **custom domain** (at connect or in **Settings**), FlowCP uses that host for **all** branches: live at the bare path and development branches at `/version-<id>/` on the same domain (for example `https://your-domain.com/version-test/api/1.1/meta/swagger.json`). Saving a custom domain updates every branch's Swagger URL and queues a fresh import for each verified branch.

After you verify your app, FlowCP automatically creates the **Live** and **Main** branches and imports tools for each.

## The branch switcher and Deploy button

The dashboard header shows a **branch switcher** next to the app selector whenever you're inside an app. It lists every branch with its status — **Production**, **Development**, or **Offline** — and switching branches changes which branch's data the Tools, Skills, Widgets, Prompts, and Resources pages show. Your selection is remembered per app.

On the far right of the header, the **Deploy** button promotes the selected branch to production. Clicking it opens a confirmation dialog; confirming runs the same safety validation as the [publish page](/guides/publish-your-mcp-server.md) and, on success, the branch's MCP server goes live at its production URL. If the deploy is blocked (for example, destructive tools without confirmation), the blocker message is shown so you can fix it first.

Next to the Deploy button, an **issues tracker** shows how many issues would currently block deploying the selected branch (destructive tools without confirmation, enabled resources with a missing or disabled backing tool, a shared-credential mode with no stored credential, or scope-gated tools under a non-OAuth mode). When issues exist the counter is shown in red — click it to see the full list and a shortcut to the branch's deploy settings. A `0` with a check mark means the branch is clear to deploy.

## The Branches page

Open an app, go to **Settings** in the sidebar, then open the **Branches** tab. Each branch row shows its name, branch URL, the source URL it imports from (with a copy button), current status, and its **Authentication** setting, with actions to:

* **Authentication** — choose how this branch authenticates to the upstream API: **User OAuth** (and which OAuth config), **API key**, **Static bearer**, or **None** (see [Setting a branch's authentication](#setting-a-branchs-authentication))
* **Tools** — review and enable that branch's tools
* **Deploy** — deploy or recall that branch's MCP server
* **Re-import** — fetch a fresh copy of that branch's Swagger spec (opens the import status page so you can see progress and any errors)
* **Delete** — remove the branch (see below)

For **Git repository** apps, the line under each branch shows the git-aware source — `repo/project @ branch · file path` — rather than a raw fetch URL, and every branch imports from the same git source. Change the git branch or file path from **Settings → General** (see [Editing the git source later](/guides/connect-your-api.md#editing-the-git-source-later)).

## Setting a branch's authentication

Each branch has an **Authentication** dropdown choosing how its hosted MCP server authenticates to the upstream API. See [Authentication modes](/guides/configure-oauth.md#authentication-modes) for the full comparison.

* **User OAuth** (default, recommended) — reveals an **OAuth config** dropdown listing the app's [OAuth configs](/guides/configure-oauth.md). Pick the config this branch should use to authenticate end users — a config can be shared by several branches, but each branch uses exactly one. A branch left on **None — not configured** is flagged **“Won't authenticate”** and its published MCP endpoint returns an error until you assign a config. New branches inherit the app's default (first) config automatically.
* **API key** — enter a shared static key and whether to send it as a header or query parameter (with the parameter name).
* **Static bearer** — enter a shared static bearer token.
* **None** — no credential is sent; all calls are unauthenticated.

> **API key, Static bearer, and None are shared-credential modes:** every end user acts through one identity, so per-user authorization is not enforced. The credential is encrypted at rest and never shown again after saving — leave the field blank when editing to keep the existing value.

## Creating a branch

In the **Create branch** form at the bottom of the page:

1. Enter a **Name** (e.g. `Staging`).
2. Enter a **Branch id** — the URL segment Bubble uses for that branch (e.g. `version-staging`). Use `live` to point a branch at the Bubble live URL.
3. Click **Create**.

FlowCP creates a new MCP server for that branch, queues a Swagger import, and takes you to the import status page while tools are generated.

## Deleting a branch

Click the trash icon on any branch row and confirm. Deleting removes that branch's MCP server, its tools, its import history, and its execution logs. The **Live** and **Main** defaults are not special — they can be deleted like any other branch, and an app may have zero branches.

> Deleting a branch immediately stops its `/mcp/<server-id>` endpoint. Any AI client configured against that server will no longer connect.