Environment tree

Environments form a tree rooted at master. Each environment has exactly one parent (the source it was branched from) and can have any number of children. The tree visualization is the right starting point for planning merges — it shows lineage at a glance and tells you which environments are eligible targets for a given merge.

Environment tree structure and status lifecycle

What each node shows

Each node in the tree displays the metadata recorded when the environment was created:

Field	What it shows
Name	Environment identifier — `master`, `staging`, `feature-auth`.
Status	Current lifecycle state — `active`, `branching`, `merging`, `error`, `archived`.
Parent	The environment this branch was created from.
Branch mode	`full` (schema + data) or `system` (schema only).
Branched at	Timestamp when the branch was created.
Children	Other environments branched from this one.

For the full status lifecycle, see Overview → Status lifecycle.

Tree shape

The tree is rooted at master — every project starts there and master can never be deleted.
Each environment has exactly one parent.
Each environment can have zero or more children.
Branching is the only way to add a node. Merging schema between environments doesn’t change the tree shape.

When the tree matters

The tree shape isn’t decorative — it informs three operations:

Operation	How the tree drives it
Merge target selection	The merge UI lets you pick any source/target pair, but the most common pattern is “merge child → parent” or “merge parent → child”. The tree makes those relationships visible.
Backup restore scope	A backup is restored into a target environment. The tree tells you which environments are still around and which have been deleted (deleted nodes can be re-created via restore).
Deletion ordering	An environment with active children can’t be deleted. The tree shows you the children to delete or archive first. See Deleting.

Reading the tree via GraphQL

Two queries cover the surface:

`environmentTree` — nested structure

Returns the full tree with children nested under parents. Easiest to render directly in a UI.

query EnvironmentTree($projectId: String!) {
  environmentTree(projectId: $projectId) {
    success
    tree {
      environment {
        id
        name
        status
        parentName
        branchMode
        branchedAt
      }
      children {
        environment {
          id
          name
          status
          parentName
          branchMode
          branchedAt
        }
        children {
          environment { id name status }
        }
      }
    }
  }
}

`projectEnvironments` — flat list

Returns every environment as a flat array. Useful for syncing the list into your own UI or for programmatic operations that don’t need nesting.

query GetProjectEnvironments($projectId: String!) {
  projectEnvironments(projectId: $projectId) {
    success
    environments {
      id
      name
      parentId
      parentName
      branchMode
      branchedAt
      status
      createdAt
      updatedAt
    }
  }
}

FAQ

Can an environment have multiple parents?

No. Each environment has exactly one parent — the source it was branched from. The tree is strict (no merging of branches into a DAG). Schema changes propagate via merge, which doesn’t change the tree shape.

What happens to children if I delete the parent?

You can’t. An environment with active children can’t be deleted. Delete or archive every child first, then the parent. See Deleting.

If I branch B from A, then merge changes from C into B, what does the tree look like?

Unchanged. B’s parent is still A — the tree records lineage at branch time, not merge history. To see merge activity, look at History.

Can I rename an environment?

Names are stable identifiers. Renaming would invalidate every URL, integration credential, and migration record that references the old name. To “rename”, branch a fresh environment with the new name and merge changes into it.

Is the tree visible in the dashboard?

Yes — open the environment switcher and choose the tree view. The same data is available via the GraphQL queries above for programmatic use.

Home

Blueprint

Design

Frontend

Backend

Assets

What each node shows

Tree shape

When the tree matters

Reading the tree via GraphQL

`environmentTree` — nested structure

`projectEnvironments` — flat list

FAQ

​What each node shows

​Tree shape

​When the tree matters

​Reading the tree via GraphQL

​environmentTree — nested structure

​projectEnvironments — flat list

​FAQ

What each node shows

Tree shape

When the tree matters

Reading the tree via GraphQL

`environmentTree` — nested structure

`projectEnvironments` — flat list

FAQ