Branches
Available to: Developers, Admins Minimum plan: Free (all plans include branching)
TitanRDM uses a branching model to manage changes to your reference data structures safely. A branch holds a set of table definitions — similar to a branch in Git, but designed for data management rather than source code. Developers change definitions on their own branch, test them, and then promote them to a shared branch.
Branches hold definitions, not data. Data lives in environments: each environment (for example Prod, Stage, or a developer's Dev environment) is deployed from one branch, and one branch can deploy to several environments.
Why Branches?
Without branches, every change to a table definition would take effect immediately for everyone:
- A column rename could break a downstream report
- An accidental deletion could remove critical reference data
- There would be no way to test changes in isolation before making them public
Branches solve this by giving each developer an isolated place to make, deploy and test changes before they are reviewed and promoted.
Branch Types
Shared Branches
Shared branches, such as main, collect changes that are ready. They are managed by administrators in Admin > Branches. New accounts start with a single shared branch, main, which deploys to the Stage and Prod environments. Some teams add a test branch between developer branches and main.
Development (Private) Branches
Every developer gets their own development branch, together with their own private Dev environment to deploy and test it in.
- Each development branch has a parent branch (typically
main), which is where its changes are promoted - Changes on a development branch are invisible to other developers until promoted
- Through user group permissions, several developers can share a development branch
Recommendation: We recommend using your default development branch for all your work. Because of the "cherry-pick" nature of the promotion process, it is easier to keep working on one branch, even when you make distinct changes that are promoted at different times.
Branch Hierarchy
Branches form a parent-child hierarchy. Changes flow upward through promotion:
main
├── development branch (developer 1)
└── development branch (developer 2)
or, with a test branch:
main
└── test
├── development branch (developer 1)
└── development branch (developer 2)
Each promotion moves table definition changes from one branch to its parent, with a review and approval step.
Branch Properties
| Property | Description |
|---|---|
| Name | A descriptive name. Must be unique among open branches; only developers' default branches share a name, and are shown with their owner, e.g. dev (Jane Smith). |
| Branch Type | shared or private (a developer branch). |
| Parent Branch | The branch changes are promoted to. |
| Status | open or closed. |
| Owner | For development branches, the developer who owns it. |
| Integration Branch | The default parent for new development branches. At most one per account. |
| External id | Optional. The matching branch in your Git provider, for CI/CD integrations. |
The Deploys to column on the Branches page shows the environments each branch deploys to.
Working with Branches
Which Branch Am I On?
The branch you work on is the branch that deploys to your current environment. Switch environment with the Environment chooser in the top-right of the header. The Table Definitions page shows the branch in a prominent pill at the top.
To view the definitions of a shared branch — for example to clone them into your own branch — switch to an environment that branch deploys to, such as Stage for main.
My Branches
Developers manage their own development branches in Development > My Branches:
- New Branch — creates a development branch and a private environment for it. Choose the branch your changes will be promoted to.
- Switch — makes the branch's environment your current environment.
- Edit — change the name, parent branch, description or external id.
- Delete — deletes the branch and its environment. They can be restored from the Deleted Branches list for 30 days, after which they are permanently removed.
Admin > Branches
Administrators manage every branch in Admin > Branches, which starts with a diagram of your branches and the environments they deploy to. Administrators can create, edit and delete both shared and development branches. A shared branch can only be deleted when no environment deploys from it, it has no open child branches, and it has no table definitions.
Branch Permissions
Each branch has two auto-created user groups:
| User Group | Permission | What It Grants |
|---|---|---|
| Branch [Name] Approver | approve | Can approve promotions targeting this branch |
| Branch [Name] Developer | develop | Can create and manage table definitions on this branch, and promote from it |
Access to data, and permission to deploy, are granted on environments.
Related Pages
- Environments — where your data lives and branches are deployed
- Deploying Changes — how to apply a branch's definitions to an environment
- Promoting Changes — how to move changes between branches
- Permissions — how branch, environment and domain permissions interact