Configuration Management
Version-control schemas and the entity tree with git-like branching and validation.
Config Manager brings git-like version control to ControlBird's configuration system. Your schemas and entity tree are versioned, so every change is tracked. Config Manager lets you create branches, edit entities, validate the changes, preview field-level diffs, commit, and atomically apply the result to the live Store, all with full change tracking and commit history.
Reach for Config Manager whenever you need to evolve configuration safely: staging a schema change before it touches production, capturing UI-driven edits back into source control, reviewing exactly what changed between two revisions, or syncing configuration between environments. Because changes are validated and applied as an all-or-nothing transaction, you get the auditability and rollback discipline of git without leaving the ControlBird UI.
Prefer a guided tutorial?
New to this? Follow the Configuration Management walkthrough for a step-by-step tour, then come back here for the full reference.
Key Concepts
A few ideas underpin everything Config Manager does:
- Version-controlled configuration: your schemas and entity tree are versioned, so every change is tracked, reviewable, and reversible.
- The entity tree: every configuration entity has a hierarchical path representing its location in the tree (for example
/Root/Controllers/Singletons/Config), matching the Store's tree structure. - Branches and worktrees: you can create branches, edit on them in isolation, and merge. Worktrees let multiple users or sessions work on different branches simultaneously without stepping on each other.
- Validation before apply: every change set is validated for syntax, schema violations, reference errors, and circular dependencies before it can be applied.
- Atomic apply-to-live: validation, diff generation, and confirmation lead to an apply step that either commits every change to the live Store or fails entirely.
- Storage scope: only Configuration-scoped fields are version-controlled. Runtime-scoped fields exist only in memory and reset on restart, so they never appear in version control.
Change tracking
As you edit, Config Manager highlights added entities in green, modified entities in yellow, and removed entities in red, with field-level diffs for each. The same model drives merge-conflict resolution and the diff preview shown before an apply.
The cb-config CLI
Config Manager is backed by the same workflow exposed on the command line through cb-config. The four core operations are:
| Command | Purpose |
|---|---|
dump | Export a configuration database back out to source files. |
restore | Assemble source files into a configuration database. |
diff | Compare two configuration databases and report the differences. |
build | Assemble base configuration plus overlays into a single configuration database. |
Common Patterns
- Branch → edit → validate → apply: create a branch, edit entities, review the change tracker (green/yellow/red), validate, preview the diff, then apply atomically to the live Store.
- Parallel work with worktrees: switching branches while another session is active automatically creates a worktree so each session edits its own branch in isolation.
- Export from Live: capture the running Store state to source files for baseline migration, to record UI-driven changes back into source control, or to sync configuration between environments.
- Diff between revisions: use
cb-config diffto compare two configuration databases when reviewing what changed between builds.
Atomic apply has no auto-rollback
Apply-to-live is all-or-nothing: either every change succeeds or every change fails. There is no automatic rollback after a successful apply: to revert, use the version history to recover a known-good configuration and apply that.
Troubleshooting & Limitations
- Validation blocks apply: syntax errors, schema violations, and reference cycles block an apply. Warnings are allowed but indicate potential runtime issues, so review them before applying.
- Circular schema inheritance: a type cannot inherit a chain that leads back to itself (Type A → Type B → Type A). Validation detects and prevents this.
- Orphaned references: entity references must point to existing entities; orphaned references are flagged as warnings during validation.
- Worktree data loss: worktrees are workspace-scoped checkouts. Deleting a worktree discards any uncommitted changes on that branch, so commit before cleanup.
- Runtime fields are not versioned: only Configuration-scoped fields are version-controlled. Runtime-scoped fields are memory-only and reset on restart.
- Merge conflicts: when two branches modify the same configuration, you must manually resolve by choosing or combining versions using the merge-conflict dialog.
- Field-name conflicts in inheritance: child entity types inherit Configuration-scoped fields from parent schemas; field names must not conflict across the inheritance chain.