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 Workspace.
Branches are only available in Tinybird Workspaces connected to a remote Git provider (for example, GitHub).
Tinybird represents branches using the icon.
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.
Branches are temporary. If you need a long-lived non-production environment, take a look at the docs on staging and production Workspaces.
Data in Branches¶
Creating a Branch copies all the resources from the Workspace 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.
Users with the Viewer role are restricted from making changes in the Workspace, but not in Branches. These users will have the same permissions in a Branch as standard users.
Branch Tokens¶
When a new Branch is created, all Tokens from the Workspace are mirrored in the new Branch. These are new Tokens that are completely independent of the production Tokens, but with the same names and scopes. This means you can delete or update the scopes of the Tokens in the new Branch without affecting production.
When you are on a branch in the CLI using the command tb branch use BRANCH_NAME_OR_ID the admin token of the branch is on the .tinyb file. If you need this token (usually on CI/CD processes) you can extract it from this auth file.
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 CI/CD actions should 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.
The JOIN Engine has been deprecated and will be fully removed in a future release. You should not create new JOIN Engine Data Sources. If you need support, contact Tinybird at support@tinybird.co or in the Community Slack.