---
title: Using Cloud Branches
meta:
  description: Use Tinybird Cloud Branches in your development workflow.
---

# Using Cloud Branches

Use Cloud Branches to build and test changes in Tinybird Cloud before deploying them to your main Workspace. The workflow is the same one used in the quickstarts: configure the project, build in a branch, test with branch data, then deploy.

Use Cloud Branches when you need production-like data, connector validation, shared preview URLs, or pull request review. Use [Tinybird Local](/forward/development-workflow/local-development) when fixture data is enough and you want a fully local loop.

For the concept model, see [Branches](/forward/core-concepts/branches). Branches are not promoted to production. You validate changes in a branch, then deploy the project to your main Tinybird Cloud Workspace with `tb deploy`, an SDK deploy command, or CI/CD.

## Check your project config

Your project config defines which files Tinybird builds and which development environment commands use by default.

Use `include` to point at your datafiles or SDK resource definitions. Set `dev_mode` or `devMode` to `branch` when you want `build` to target Cloud Branches by default. You can still override the target with `--branch` or `--local` on the command line.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```json {% title="tinybird.config.json" %}
{
  "dev_mode": "branch",
  "include": [
    "tinybird"
  ]
}
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```json {% title="tinybird.config.json" %}
{
  "include": [
    "lib/tinybird.ts"
  ],
  "token": "${TINYBIRD_TOKEN}",
  "baseUrl": "${TINYBIRD_URL}",
  "devMode": "branch"
}
```

{% /tab %}

{% tab label="Python SDK" %}

```json {% title="tinybird.config.json" %}
{
  "include": [
    "src/tinybird"
  ],
  "token": "${TINYBIRD_TOKEN}",
  "baseUrl": "${TINYBIRD_URL}",
  "devMode": "branch"
}
```

{% /tab %}
{% /tabs %}

## Typical branch workflow

1. Set the development environment to Cloud Branches in `tinybird.config.json`.
2. Create a Git branch.
3. Build the project in a matching Tinybird Cloud Branch.
4. Edit Data Sources, Pipes, Endpoints, Tokens, or Connections.
5. Rebuild and test the branch with fixture data, production-like data, or connector data.
6. Run a deployment check against the main Cloud Workspace.
7. Merge and deploy.

```shell
git checkout -b add-plan-to-events
tb build
```

With `dev_mode` or `devMode` set to `branch`, `tb build` uses your Git branch name as the Tinybird Cloud Branch name. If the Cloud Branch does not exist, Tinybird creates it. Run `tb build` again after editing project files.

For commands other than `build`, pass the branch name explicitly with `--branch=<git-branch-name>`.

```shell
Using dev_mode=branch. Running build against Tinybird branch 'add-plan-to-events'.
Running against Tinybird Cloud: Workspace production | branch add-plan-to-events
» Git branch:            add-plan-to-events
» Tinybird Cloud branch: add-plan-to-events ✓ created
» Building project...
✓ datasources/events.datasource created
✓ Build completed in 6.2s
```

## Build in a branch

Run a build before testing changes. If your project is in Git, Tinybird creates or reuses a Cloud Branch with the same name as your Git branch.

{% tabs initial="Datafiles" %}
{% tab label="Datafiles" %}

```shell
git checkout -b add-plan-to-events
tb build
```

{% /tab %}
{% tab label="TypeScript SDK" %}

```shell
git checkout -b add-plan-to-events
npx tinybird build
```

{% /tab %}
{% tab label="Python SDK" %}

```shell
git checkout -b add-plan-to-events
uv run tinybird build
```

{% /tab %}
{% /tabs %}

When you edit project files, run build again to apply the changes to the Cloud Branch.

## Bring production-like data into a branch

By default, a branch copies Workspace resources, not data. For most changes, let `tb build` create the branch from your Git branch. Create the branch explicitly only when you need branch options, such as attaching the latest production partition:

```shell
tb branch create add-plan-to-events --last-partition
tb build
```

This attaches the latest production partition to the branch without copying the underlying data. Writes, deletes, and schema changes stay isolated in the branch.

Use `--last-partition` for:

- Schema changes that need real values.
- Endpoint changes where fixture data is not enough.
- Query performance checks on realistic partition sizes.
- Review apps that need production-like responses.

Do not use branch data as a backup or long-lived replica. Branches are short-lived validation environments.

## Query and call branch resources

Run SQL against the branch:

```shell
tb --branch=add-plan-to-events sql "SELECT plan, count() FROM events GROUP BY plan"
```

Open Tinybird UI for the branch:

```shell
tb --branch=add-plan-to-events open
```

The URL is `https://cloud.tinybird.co/<cloud-provider>/<region>/<workspace-name>~<branch-name>`.

Call a branch Endpoint with a branch Token:

```shell
curl -H "Authorization: Bearer <branch-token>" \
  "{% user("apiHost", "https://api.tinybird.co") %}/v0/pipes/events_by_plan.json"
```

## Test connector data

Use `--with-connections` when your branch needs Kafka, S3, or GCS connector Data Sources.

```shell
tb build --with-connections
```

### Kafka

Kafka ingestion starts stopped in branches. Start it only when you are ready to test:

```shell
tb --branch=add-plan-to-events datasource start my_kafka_datasource
```

Stop it when you finish:

```shell
tb --branch=add-plan-to-events datasource stop my_kafka_datasource
```

Each start creates a new consumer group for the branch and starts from the latest offset. This avoids collisions with production and other branches.

### S3 and GCS

Import a sample instead of syncing the whole bucket:

```shell
tb --branch=add-plan-to-events datasource sample my_s3_datasource --wait
```

Sample imports are separate jobs and do not affect production sync state.

## Validate before deploy

Before merging, run the checks that match the change. For schema or connector changes, include a Cloud deployment check.

```shell
tb build
tb test run
tb --cloud deploy --check
```

For SDK projects, use the matching SDK commands:

{% tabs initial="TypeScript SDK" %}
{% tab label="TypeScript SDK" %}

```shell
npx tinybird build
npx tinybird deploy --dry-run
```

{% /tab %}
{% tab label="Python SDK" %}

```shell
uv run tinybird build
uv run tinybird deploy --check
```

{% /tab %}
{% /tabs %}

## Preview branches in CI

Use preview branches for pull requests. They let reviewers and preview deployments call the changed Tinybird project before it is merged.

For TypeScript SDK projects:

```shell
npx tinybird preview --check
```

For Python SDK projects:

```shell
uv run tinybird preview --check
```

For datafile projects, create and build a branch explicitly:

```shell
tb branch create tmp_ci_my_feature --last-partition
tb --branch=tmp_ci_my_feature build
```

See [CI/CD](/forward/development-workflow/cicd#preview-deployments).

## Work without Git

If your project is not in a Git repository, pass the branch name explicitly to `build` too:

```shell
tb --branch=add-plan-to-events build
```

## Clean up branches

Branches are meant to be temporary. Delete them after the pull request is merged or closed.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```shell
tb branch rm preview_1
```

{% /tab %}
{% tab label="TypeScript SDK" %}

```shell
npx tinybird branch delete preview_1
```

{% /tab %}
{% tab label="Python SDK" %}

```shell
uv run tinybird branch rm preview_1
```

{% /tab %}
{% /tabs %}

## When to use Local instead

Use [Tinybird Local](/forward/core-concepts/tinybird-local) instead of Cloud Branches when fixture data is enough, you need a fully local loop, or you want CI checks that do not touch Cloud resources.