Configuration Lifecycle
This page provides an overview of how configuration is managed, versioned, and deployed in tSM — from development through production.
tSM Studio and the tSM CLI together provide a complete model for moving configuration between environments — reliably, repeatably, and with full traceability. This page introduces the core concepts and how they fit together. Detailed pages cover each topic in depth.
The problem
In any non-trivial tSM project, configuration must move from development to production. Without a structured model, this raises difficult questions:
- What exactly was deployed?
- Which version is running in production?
- Who owns which part of the configuration?
- How do we upgrade safely without breaking related items?
- How do parallel teams release independently?
The packaging model answers all of these.
Core concepts
The model is built from six concepts:
| Concept | Role |
|---|---|
| ConfigType | Ownership taxonomy — where every configuration entity belongs. |
| Configuration Package | Source unit in Git — what is versioned, built, and released. |
| Configuration Area | Logical subdivision inside a package — where content is stored on disk. |
| Change Set | Story-level tracking — what changed for one user story or task. |
| Deployment Artifact | Immutable deployable artifact — the built result ready for installation. |
| Installed Package | Deployment record — what is actually installed in an environment. |
How they relate
ConfigType
└── defines ownership of every configuration entity
Configuration Package (package.yaml in Git)
├── contains one or more Configuration Areas
│ └── each area scopes content by ConfigType
├── declares dependencies on other packages
└── build → produces an immutable Deployment Artifact
Change Set (optional, story-level)
└── selects a subset of changes for independent release
Deployment Artifact (immutable artifact)
└── install → creates an Installed Package record
ConfigType is the foundation. It assigns every configuration entity to an owner.
Configuration Package uses ConfigType to decide what belongs inside. A package is defined by package.yaml and stored in Git. It contains one or more Configuration Areas, each scoped to a set of ConfigTypes. Areas determine where content is stored on disk — entity-type subfolders are created automatically by Studio during sync.
Change Set is an optional layer for parallel development. When multiple stories are in progress inside the same package, each developer opens a Change Set that tracks exactly which entities were touched. This enables independent, story-level releases without waiting for other work to finish.
Deployment Artifact is the immutable artifact produced by a build. It contains the configuration content exactly as it was at build time.
Installed Package is the record created when a package is installed into a target environment. It provides the deployment history, version tracking, and drift detection for each environment.
Lifecycle
A typical configuration delivery lifecycle looks like this:
- Configure — developers create or modify configuration in a development environment.
- Version — changes are downloaded into tSM Studio, committed to Git, and tracked under a Configuration Package.
- Build — the CLI or pipeline produces an immutable deployment artifact from the committed state.
- Deploy — the deployment artifact is validated, diffed, and installed into the target environment.
- Track — an Installed Package record captures exactly what was deployed, when, and by whom.
For later updates, the same cycle repeats: modify in DEV, commit, bump version, build, install.
ConfigType — the ownership foundation
Every configuration entity in tSM has a configType field. ConfigType codes are hierarchical:
BSS
BSS.CRM
BSS.ProductCatalog
BSS.Ordering
SDWAN
SDWAN.ProductCatalog
SDWAN.Ordering
ConfigType determines:
- ownership — who is responsible for an entity
- navigation — how users browse configuration in Configuration Explorer
- packaging scope — which package an entity belongs to
ConfigType is not defined by the packaging model — it exists independently. Packages build on top of it.
Configuration Package — the release unit
A Configuration Package is defined by a package.yaml file inside a Git repository:
packages/
ordering-sdwan/
package.yaml # package definition
sdwan-product/ # configuration area
sdwan-fulfillment/ # configuration area
A package declares:
- identity and version —
packageId,name,version - areas — where content is stored, scoped by ConfigType
- dependencies — other packages that must be present
- policy — install and upgrade behavior
A package contains one or more areas, and each area should follow one clear ConfigType subtree. A good area is easy to explain — "everything under SDWAN.ProductCatalog.*" or "everything under BSS.Ordering.*".
→ Configuration Packages — full model, areas, membership rules, examples, and schema reference
Configuration Area — content organization
Inside a package, areas subdivide the content into logical groups. Each area:
- is scoped to one or more ConfigTypes
- maps to a directory on disk
- gets entity-type subfolders created automatically during sync
areas:
- id: sdwan-product
path: sdwan-product
configTypes:
- code: SDWAN.ProductCatalog
includeSubtree: true
Areas should be business-oriented — sdwan-product, shared, ticketing-flow — not technical (forms, registers). Studio handles entity-type separation automatically inside each area.
Change Set — story-level tracking
When multiple developers work in parallel on the same project, a Change Set provides story-level tracking:
- each developer opens a Change Set linked to their user story
- the system automatically tracks which entities are created, modified, or deleted
- Change Sets go through a review workflow:
OPEN → IN_REVIEW → CLOSED - deployment follows the normal package pipeline — Change Sets provide the audit trail
Change Sets do not replace packages. They are a tracking and review layer that sits on top of the existing package model.
→ Change Sets — lifecycle, entity model, review workflow
Installed Package — deployment record
When a package is installed into an environment, tSM creates an Installed Package record. This record answers:
- which package was installed
- which version
- when and by whom
- which individual items were included
Over time, the Installed Package history provides a complete audit trail for any environment.
→ Installed Package — entity model and attributes
Types of changes in a development environment
At any point in time, a shared development environment contains a mix of changes in different states. Understanding these categories is essential for choosing the right deployment approach.
Tracked changes — Change Set active
A developer has an active Change Set (e.g. US-1234). Every entity they create or modify is automatically recorded under that Change Set. These changes have:
- a clear story reference
- an exact list of affected entities
- a reviewable scope before release
Deployment path: Download the Change Set items → create an artifact → deploy.
Untracked configuration changes — no Change Set
A developer modifies configuration without activating a Change Set. The change exists in the environment but has no story-level tracking. This is the most common source of deployment surprises:
- no record of which story the change belongs to
- the change may be incomplete or experimental
- it will appear in a full download but may be unintentionally included in a release
Deployment path: These changes are captured when the full package is downloaded. They become visible during diff or validate. The team must review them manually and decide whether to include or revert them.
Prevention: Require every developer to activate a Change Set before making changes. Use periodic tsm package download + git diff to detect untracked drift early.
Unchanged items
Items that exist in the environment and in Git but have not been modified since the last download. They are the stable baseline.
Deployment path: Included in a full artifact automatically. Excluded from an incremental artifact because there is no delta.
Non-packageable items
Some items in a development environment cannot be part of a Configuration Package. Examples:
- user-specific dashboard layouts or personal UI preferences
- temporary test data created during development
- runtime state (running process instances, tickets, orders)
- entities whose ConfigType is not included in any package scope
These items are outside the packaging model. They are not downloaded, not versioned, and not deployed. If an entity type needs to be promoted across environments, it must belong to a ConfigType that is included in a package area's configTypes scope.
If you expect an entity to be part of a package but it does not appear during download — check that its configType belongs to an area with includeSubtree: true if needed. Studio only downloads entities whose ConfigType matches the package scope.
Summary: what happens to each change type
| Change type | Downloaded? | In Git? | In full artifact? | In incremental artifact? | Action needed |
|---|---|---|---|---|---|
| Tracked (Change Set) | Yes | After commit | Yes | Yes (if diff exists) | Download → commit → deploy |
| Untracked (no Change Set) | Yes | After commit | Yes | Yes (if diff exists) | Review carefully — include or revert |
| Unchanged | Yes | Already there | Yes | No (no delta) | Nothing — stable baseline |
| Non-packageable | No | No | No | No | Outside the model — manage separately |
The deployment toolbox
The packaging model provides several tools for different deployment needs. Each tool addresses a specific combination of change types and release requirements.
| Tool | What it deploys | When to use |
|---|---|---|
| Full artifact | All items matching package.yaml. Target environment converges to package state. | Baseline release, environment reset, first deployment, sprint release where you want a clean known state. |
| Incremental — diff to target | Only items that differ from the target environment. | Regular update to a known environment. Most common for incremental releases. |
| Incremental — branch diff | Only items changed between two Git refs. | CI/CD feature release from a branch. Deploys exactly what the branch introduced. |
| Incremental — file list | Only items in an explicit list. | Story-level release, Change Set deployment, targeted fix. |
| Change Set download | Downloads only entities tracked by one Change Set. | Targeted download before artifact creation when you want to isolate one story. |
| Direct install | All items (equivalent to full artifact, but no reviewable archive). | Quick development-time test. Not for production. |
Choosing the right tool
For detailed CLI usage of each tool, see Deployment Artifacts and Deployment Process.
Environment promotion
Same artifact, multiple environments
A deployment artifact is built once and promoted through environments. You do not rebuild per environment.
This guarantees that what was tested is exactly what reaches production.
Environment naming
The examples use TEST and PROD. In practice, environments may be called REF, UAT, STAGING, PRE-PROD, etc. The model is the same regardless of naming — build once, promote through a chain.
A diff-to-target artifact is computed against a specific target environment. When the same artifact is installed into a different environment, items in the artifact are applied and items not in the artifact are not touched. This is safe when environments are reasonably aligned. For the first deployment to a new environment that differs significantly from the target the artifact was diffed against, use a full artifact instead.
Tracking deployed state
A common question is: "Do we need a Git branch per environment?"
No. Git tracks source — what was authored and committed. Installed Package records track deployment — what is actually running in each environment.
| Question | Answer source |
|---|---|
| What is the latest source version? | Git (main branch, package.yaml version) |
| What was deployed to PROD? | tsm package installed list --target-env prod |
| Which items were included in that deployment? | tsm package installed items <id> |
| Has PROD drifted since the last deployment? | tsm package diff --target-env prod against the installed version |
| Which story introduced a specific change? | Change Set audit trail + --notes on the Installed Package record |
You do not need release/*, prod/*, or ref/* branches to track deployed state. Git tags on main (e.g. v1.5.0) are sufficient for marking release points in source history.
Common anti-patterns
| Anti-pattern | Risk | Recommended approach |
|---|---|---|
| Modifying DEV without an active Change Set | Untracked changes appear unexpectedly in the next download. No story-level audit trail. | Always activate a Change Set before making changes. |
| Manual file rollback in a Git branch | Error-prone, may leave partial state. Hard to verify completeness. | Use incremental artifacts (--diff, --branch-diff) to deploy only the intended changes. Do not manually revert files in Git to exclude them from a release. |
| Rebuilding the artifact per environment | TEST and PROD may receive different content. What was tested is not what was deployed. | Build once, promote the same artifact. |
| No version bump before release | Same version installed twice with different content. Installed Package history becomes unreliable. | Always bump version in package.yaml before building a release artifact. |
| Deploying from a working branch instead of main | main does not reflect what is deployed. Future releases may miss or duplicate changes. | Merge to main first, then build and deploy from main. |
| Skipping diff review before PROD | Unexpected items reach production. | Always run tsm package diff or inspect the artifact manifest before PROD install. |
| Using a "PROD Git branch" for deployed state | Branch drifts from actual environment state. Manual sync is fragile. | Use Installed Package records for environment state. Git tracks source, not what is deployed. |
Workflows
The packaging model supports different team sizes and release strategies.
Basic workflow
A small team with two packages (System and AllConfig) and a straight DEV → PROD flow.
Example packages: System (platform baseline) and AllConfig (all business configuration). A single team configures in DEV, syncs to Studio, builds both packages, then installs into PROD. For updates, the same cycle repeats with a version bump.
Enterprise workflow
Multiple independent teams, each owning distinct ConfigType subtrees and shipping their own packages. The SD-WAN solution spans several domains but is delivered as one coherent package that depends on the base packages.
Five teams own six packages. Each team configures in DEV, builds their packages, and installs through TEST into PROD:
| Team | Packages | ConfigType root |
|---|---|---|
| Platform | System, InfraCommon | System.*, Infra.* |
| BSS | BSSBase | BSS.* |
| OSS | OSSBase | OSS.* |
| Ticketing | TicketingBase | Ticketing.* |
| SD-WAN | SDWAN | SDWAN.* |
The SDWAN package declares dependencies on BSSBase, OSSBase, and TicketingBase. tSM enforces install order automatically — base packages must be installed before SDWAN.
Change Set workflow
Story-level tracking on top of any package structure. Multiple developers work in the same shared DEV environment. Each developer opens a Change Set linked to their user story — the system automatically tracks which entities each story touches. Stories are reviewed and closed independently. Deployment follows the normal package pipeline.
Example: Bob adds an SD-WAN site setup form (US-1234) while Alice revises common statuses (US-5678). Both work in the same shared DEV. Each Change Set captures only the touched entities. After review, Change Sets are closed and packages are deployed through the standard pipeline — independently and without blocking each other.
Tooling
| Tool | Purpose | Page |
|---|---|---|
| tSM Studio | VS Code extension for editing configuration locally, managing packages, and working with change sets. | tSM Studio |
| tSM CLI | Command-line tool for package authoring, validation, diff, installation, and change set management. | tSM CLI |
| Configuration Reference | Full schema for package.yaml, tsm-project.yaml, and ~/.tsm/ settings. | Configuration Reference |
Where to start
- New to packaging? Start with the Basic Workflow — it walks through a minimal project from scratch.
- Designing a multi-team project? Read the Enterprise Workflow for a real SD-WAN example.
- Need story-level tracking? See Change Sets and the Change Set Workflow.
- Looking for schema details? Go to the Configuration Reference.
For stronger isolation, each developer can optionally work in a scratch environment — a short-lived copy of the shared baseline (e.g. DEV-bob, DEV-alice). Changes in a scratch environment do not affect other developers until explicitly merged. This model is experimental and is useful when stories may conflict at runtime — but it adds environment management overhead.