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 when fixture data is enough and you want a fully local loop.

For the concept model, see 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.

tinybird.config.json
{
  "dev_mode": "branch",
  "include": [
    "tinybird"
  ]
}

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.
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>.

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.

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

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:

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:

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

Open Tinybird UI for the branch:

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:

curl -H "Authorization: Bearer <branch-token>" \
  "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.

tb build --with-connections

Kafka

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

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

Stop it when you finish:

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:

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.

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

For SDK projects, use the matching SDK commands:

npx tinybird build
npx tinybird deploy --dry-run

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:

npx tinybird preview --check

For Python SDK projects:

uv run tinybird preview --check

For datafile projects, create and build a branch explicitly:

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

See CI/CD.

Work without Git

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

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.

tb branch rm preview_1

When to use Local instead

Use 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.

Updated
Looking for Classic docs?