Branches¶

What is a Branch?¶

Branches are isolated, temporary copies of your Tinybird project and the resources it contains (including Data Sources, Pipes, API Endpoints). They are inspired by Git branches, allowing you to make changes and develop new features, then merge those changes back into the Live Release.

Branches are only available in Tinybird Workspaces connected to a remote Git provider (for example, GitHub).

What should I use Branches for?¶

Use Branches to develop new features without affecting production or other developers. Tinybird Branches mirror the intent behind Git branches, and should be used for the same reasons.

Branches are intended to be temporary, rather than long lived, so they are ideal for building new features and prototyping. Branches should be removed when their work is complete (either merged or deleted).

Common uses for Branches include:

• Designing new Data Sources or Pipes.
• Iterating the schema of a Data Source.
• Testing the backfill strategy of a new Data Source.
• Changing the output of a Pipe.
• Modifying API Endpoint query parameters.

Data in Branches¶

Creating a Branch copies all the resources from the Live Release to the new Branch, but it does not copy all the production data.

When creating a Branch, you can choose to copy a segment of data from production into the new Branch. This will duplicate the latest active partition (up to a maximum of 50GB) of data from all production Data Sources, and attach the copies to the new Branch Data Sources. This data is a copy (or clone), and is physically separate from the production data. This means you can ingest or drop data from the Branch and it will not affect production data. If you choose not to copy data, the new Branch will contain no data, and you will need to ingest data into the Branch Data Sources.

When a Branch is deleted, the Branch data is also deleted. There is a soft limit on the number of Branches you can create per Workspace (3). Contact us at support@tinybird.co if you need to increase this limit.

Branch users¶

When a new Branch is created, all Workspace users are added to the new Branch with their current roles. Since the new Branch is completely independent, user management is also independent. You can update the roles of users in the new Branch without affecting the main Workspace.

Branch Auth Tokens¶

When a new Branch is created, all Auth Tokens from the Live Release are mirrored in the new Branch. These are new Auth Tokens that are completely independent of the production Auth Tokens, but with the same names and scopes. This means you can delete or update the scopes of the Auth Tokens in the new Branch without affecting production.

Create a Branch¶

A Branch can be created via the Tinybird UI, Tinybird CLI, or automatically as part of your CI/CD process. You can only create Branches in Workspaces connected to a remote Git provider (for example, GitHub).

Using the Tinybird UI¶

To create a new Branch with the Tinybird UI, click the Branch dropdown in the top bar, and click on the Branch tab. Click the Create Branch button.

Using the Tinybird CLI¶

To create a new Branch with the Tinybird CLI, use the tb branch create command. See the tb branch Command Reference for more information.

Using a Pull Request¶

To create a new Branch with a Pull Request (PR), push your local feature branch to your Git provider and open a new PR. The automated CI/CD actions sync the branch from your PR to Tinybird.

Delete a Branch¶

A Branch can be deleted via the Tinybird UI, Tinybird CLI, or automatically as part of your CI/CD process. You can only delete Branches in Workspaces connected to a remote Git provider (for example, GitHub).

Using the Tinybird UI¶

To delete a Branch with the Tinybird UI, click the Branch dropdown in the top bar, and click on the Branch tab. Find your Branch in the list, and click the trash button to the right.

Using the Tinybird CLI¶

To delete a Branch with the Tinybird CLI, use the tb branch rm command. See the tb branch Command Reference for more information.

Using a Pull Request¶

To delete a Branch from a Pull Request (PR), close or merge the associated PR in your Git provider. The automated CI/CD actions delete the Branch from Tinybird.

Limitations¶

JOIN Engine Data Sources

Data Sources using the JOIN Engine are not fully supported in Branches.

You can create a Branch with JOIN Engine Data Sources, but the data will not be copied into the new Branch.

Next steps¶

Familiar with Branches? Read the docs on Releases in Tinybird.