Working with Branches and Environments
Available to: Developers, Admins Minimum plan: Free (all plans include branching)
This guide covers the practical workflows for switching environments, and for creating and managing branches in TitanRDM. For the conceptual background, see Branches and Environments.
Prerequisites
- Any plan — all plans include branching and environments
- Developer licence to work with development branches; Admin to manage shared branches and environments
Switching Your Current Environment
Your current environment decides what you see throughout the application. Developers work on the table definitions of the branch that deploys to it.
To switch, click the Environment chooser in the top-right of the header and pick an environment. Your own environments are listed first, then shared environments (production first), then other developers' environments you have access to. Each entry shows the branch it is deployed from.
What Changes When You Switch
| Area | Behaviour |
|---|---|
| Tables sidebar and Tables page | Shows the tables deployed to the new environment |
| Data grid, imports and exports | Work with the new environment's data |
| Table Definitions | Shows the definitions of the branch that deploys to the new environment |
| Deployments | Opens on the new environment's tab |
| Promotions | Opens on the tab of the branch your branch promotes into |
After switching, end users are taken to the Tables page and developers to the Table Definitions page.
Viewing a Shared Branch
To see the definitions of a shared branch — for example to clone tables from main into your branch — switch to an environment that the shared branch deploys to (such as Stage). The branch pill at the top of the Table Definitions page shows which branch you are viewing. Definitions on shared branches are read-only; clone them to your development branch to change them.
My Branches
Development > My Branches lists your development branches and the private environment each one deploys to.
Creating a Development Branch
- Navigate to Development > My Branches
- Click New Branch
- Fill in the form:
| Field | Required | Description |
|---|---|---|
| Name | Yes | A descriptive name, e.g. currency-tables. Must not already be used by another branch. Its environment gets the same name. |
| Promotes to | Yes | The shared branch your changes will be promoted to. Defaults to the integration branch (typically main). |
| External id | No | The matching branch in your Git provider. |
| Description | No | Optional context about what this branch is for. |
- Leave Switch to its environment after creating ticked to start working on it straight away
- Click Create Branch
TitanRDM creates the branch and a private environment for it, and adds you to their user groups.
After Creation
A new branch starts empty — it does not inherit table definitions from its parent. To bring table definitions into it:
- Clone individual tables from a shared branch (see Cloning Tables)
- Bulk Clone multiple tables at once from the Table Definitions page
Editing and Deleting
- Edit changes the name, parent branch, external id or description.
- Delete removes the branch and its environment from view. They are kept for 30 days and can be restored from the Deleted Branches section of My Branches; after that they are permanently removed, including the environment's data.
Admin > Branches
Administrators manage every branch in Admin > Branches. The page shows:
- A diagram of your branches and the environments each one deploys to (click Show developer branches to include development branches)
- Shared Branches, with the environments each deploys to
- Developer Branches
- Deleted Branches, which can be restored for 30 days
Administrators can create shared branches, and create development branches for any developer. A new shared branch does not deploy anywhere until you give it an environment in Admin > Environments. Until then developers cannot open it from the environment chooser.
Integration Branch
One branch can be the integration branch (typically main, or test if you use one). It is the default parent for new development branches.
Admin > Environments
Administrators manage environments in Admin > Environments: create environments, choose the branch each one is deployed from, arrange them in a hierarchy, and mark production environments. See Environments.
Permissions
| Action | Required Permission |
|---|---|
| Select an environment and work with its data | Environment Editor or Deployer membership (or owning the private environment), plus a domain permission for the data |
| Create a development branch | Account-level develop permission (or admin) |
| Edit table definitions on a branch | develop on the branch and develop on the domain or table definition |
| Deploy to an environment | Environment Deployer membership; developers can always deploy to their own private environment |
| Approve promotions to a branch | approve on the branch |
| Manage shared branches and environments | Account administrator |
Workflow Example
- Switch to Stage to view
main, and clone the table definitions you need into your development branch - Switch back to your Dev environment
- Edit the column definitions
- Deploy to your Dev environment and test
- Promote your branch to
main— deployments are created for Stage and Prod - Deploy to Stage and test
- Deploy to Prod
Related Pages
- Branches (Concept) — conceptual overview of the branching model
- Environments (Concept) — where your data lives
- Deploying Changes — applying changes to an environment
- Promoting Changes — moving changes to the parent branch
- Cloning Tables — bringing table definitions into a branch
- Permissions — how permissions combine