Skip to main content
Version: 2.4

Installation Process

This page explains how to download, package, and install configuration — from a full release to targeted story-level deployments.

There are two installation patterns:

PatternPipelineWhen to use
Direct installDownload → Validate → Diff → InstallQuick full-package deployment; the diff is computed at install time.
Artifact-based installDownload → Create artifact (diff pre-computed) → Publish → Install from artifactControlled releases; you know exactly what will be installed before deployment.

What varies is how the content is prepared and what is included. There are four strategies:

StrategyWhat is installedPatternWhen to use
Full packageAll items matching package.yaml.Direct installInitial deployment, full baseline.
Diff to targetOnly items that differ from the target environment.ArtifactIncremental update to a known environment.
Diff between branchesOnly items changed between Git branches.ArtifactCI/CD feature release.
Change SetOnly items tracked by a Change Set.ArtifactStory-level release from parallel development.

See also:

Key concepts​

Installation artifact​

An installation artifact is a self-contained archive (ZIP) that holds exactly the items to be installed — no more, no less. When using the artifact-based pattern, the diff to the target environment is computed at artifact creation time, so you know precisely what will be installed before the artifact ever reaches the target.

Artifacts are written to a separate, non-versioned directory (e.g. build/). They should be added to .gitignore — they are build outputs, not source.

build/
  AllConfig-1.1.0-prod.zip        # artifact ready for installation
  SDWAN-1.5.0-test.zip

Direct install (shortcut)​

Running tsm package install directly against a package directory (without --file) is equivalent to the full package strategy — the server computes the diff at install time and applies everything. This is a convenient shortcut but does not produce a reviewable artifact.

The installation pipeline​

Both patterns share the same server-side steps. The difference is whether the diff is computed beforehand (artifact) or at install time (direct).

Validate​

tsm package validate AllConfig

Parses package.yaml, resolves dependencies, and checks for structural or compatibility issues. No changes are made. If validation fails, the process stops.

Diff​

tsm package diff AllConfig --target-env prod

Compares the package content with the current state of the target environment. The output shows which items would be added, modified, removed, or left unchanged.

Install​

# Direct install (full package shortcut)
tsm package install AllConfig --target-env prod \
  --notes "Release 1.0.0"

# Install from an artifact
tsm package install --file build/AllConfig-1.1.0-prod.zip \
  --target-env prod --notes "Release 1.1.0"

Applies configuration to the target environment and creates an Installed Package record for traceability.

Strategy 1: Full package​

A full package install deploys all configuration items that match the package.yaml definition — every area, every ConfigType, every entity type. This is the direct install pattern.

When to use​

  • first-time deployment to a new environment
  • full baseline release where you want a complete, known state
  • reset of an environment to match the package exactly

How it works​

Step 1: Download configuration from the source environment​

tsm package download AllConfig

This downloads all configuration items matching package.yaml into the local package directory, organized by area and entity type.

Step 2: Commit to Git​

git add AllConfig
git commit -m "AllConfig 1.0.0 — initial baseline"

Step 3: Validate, diff, install​

tsm package validate --target-env prod AllConfig
tsm package diff     --target-env prod AllConfig
tsm package install  --target-env prod AllConfig \
  --notes "AllConfig 1.0.0 — initial production deployment"

What gets installed​

Every item in every area — the full package content. On the target environment, the diff will show all items as ADDED (for a first-time deployment) or a mix of ADDED, MODIFIED, and UNCHANGED (for a re-deployment).

Strategy 2: Diff to target environment​

A diff-to-target install deploys only the items that differ between the local package and the target environment. Unlike the full package, the diff is computed at artifact creation time — the artifact contains only the changes, so you can review and approve the exact delta before deployment.

When to use​

  • incremental update to a known, running environment
  • regular update cycle where most configuration has not changed
  • you want to review and approve the exact set of changes before deployment
  • you want to publish the artifact to a repository (Nexus, Harbor) for controlled rollout

How it works​

Step 1: Download updated configuration​

tsm package download AllConfig

Step 2: Commit and bump version​

git add AllConfig
git commit -m "AllConfig 1.1.0 — ordering form improvements"

Update version in package.yaml to reflect the new release.

Step 3: Create the installation artifact​

tsm package artifact AllConfig --target-env prod

This computes the diff against the target environment and produces an artifact containing only the changed items:

Artifact: build/AllConfig-1.1.0-prod.zip

ADDED (1):
  Form/SDWAN_SiteSetup

MODIFIED (2):
  Form/OrderEntry            [fields changed]
  Process/OrderProvisioning  [steps changed]

Total: 3 items (139 unchanged, excluded from artifact)

The artifact is written to build/ (not versioned).

Step 4: Publish the artifact (optional)​

tsm package publish build/AllConfig-1.1.0-prod.zip \
  --repository nexus \
  --notes "AllConfig 1.1.0 — ordering form improvements, PROJ-456"

This uploads the artifact to a repository (Nexus, Harbor, or another configured registry) for downstream consumption by deployment pipelines or other teams.

Step 5: Install from the artifact​

tsm package install --file build/AllConfig-1.1.0-prod.zip \
  --target-env prod \
  --notes "AllConfig 1.1.0 — ordering form improvements, PROJ-456"

Only the 3 items in the artifact are installed. Nothing else is touched.

Filtering by area or entity type​

You can narrow the artifact further using --area-code and --entity-types when creating it:

# Artifact containing only the ordering area
tsm package artifact AllConfig --target-env prod \
  --area-code ordering

# Artifact containing only Forms and Processes
tsm package artifact AllConfig --target-env prod \
  --entity-types Form,Process

The resulting artifact still contains only the filtered items — review, publish, and install the same way.

Strategy 3: Diff between Git branches​

A branch-based install deploys only the items that changed between two Git branches — for example, a feature branch versus the main branch. Like Strategy 2, this produces an artifact.

When to use​

  • CI/CD pipeline deploys a feature branch
  • you want to release exactly what was developed in a branch, nothing more
  • team reviews a pull request and wants to know what would be installed

How it works​

Step 1: Create the artifact from a branch diff​

tsm package artifact AllConfig \
  --branch-diff main...feature/ordering-improvements \
  --target-env test

The CLI determines which configuration files changed between the two branches, computes the diff against the target environment for those files, and produces an artifact.

Step 2: Publish and install​

tsm package publish build/AllConfig-1.1.0-test.zip \
  --repository nexus

tsm package install --file build/AllConfig-1.1.0-test.zip \
  --target-env test \
  --notes "Feature: ordering improvements (branch: feature/ordering-improvements)"

CI/CD integration​

# Example CI step (pseudo-YAML)
steps:
  - name: Create artifact from branch diff
    run: |
      tsm package artifact AllConfig \
        --branch-diff origin/main...HEAD \
        --target-env $TARGET

  - name: Publish
    run: |
      tsm package publish build/AllConfig-*-$TARGET.zip \
        --repository nexus

  - name: Install
    run: |
      tsm package install \
        --file build/AllConfig-*-$TARGET.zip \
        --target-env $TARGET \
        --notes "CI deploy: $CI_COMMIT_REF_NAME ($CI_COMMIT_SHORT_SHA)"

Strategy 4: Change Set​

A Change Set install deploys only the items tracked by a specific Change Set — typically the work for one user story or task. The workflow integrates with Git branching and produces an artifact.

When to use​

  • multiple developers work in parallel on the same project
  • each story must be releasable independently
  • you want automatic entity tracking instead of manual file selection

How it works​

Step 1: Create a Change Set​

tsm changeset create \
  --code US-1234 \
  --name "SD-WAN site setup form and provisioning"

Step 2: Develop​

Work in the development environment. All configuration changes are automatically tracked under the active Change Set — no manual bookkeeping.

Step 3: Review and submit​

tsm changeset show US-1234
Change Set: US-1234
Status:      OPEN

ITEMS (4):
  CHANGE     ENTITY TYPE      CODE                        CONFIG TYPE        BASE VERSION
  ADDED      Form             SDWAN_SiteSetup             SDWAN.Ordering     —
  ADDED      Characteristic   SiteRole                    SDWAN.Ordering     —
  ADDED      Process          SDWAN_OrderProvisioning     SDWAN.Provisioning —
  MODIFIED   Register         SDWANStatuses               SDWAN              2026-03-01T10:00:00Z

When ready, submit for review:

tsm changeset submit US-1234

Step 4: Create a Git branch and download changeset items​

git checkout -b feature/US-1234

tsm package download SDWAN --changeset US-1234

This downloads only the items tracked by the Change Set into the local package directory — not the entire package content. The result is a branch containing exactly the story's changes.

git add SDWAN
git commit -m "US-1234: SD-WAN site setup form and provisioning"

Step 5: Create the installation artifact​

tsm package artifact SDWAN --target-env test

The artifact contains only the changeset items, diffed against the target.

Step 6: Merge and install​

Merge the feature branch into main (via pull request, code review, etc.):

git checkout main
git merge feature/US-1234

Install the artifact:

tsm package install --file build/SDWAN-1.5.0-test.zip \
  --notes "US-1234: SD-WAN site setup and provisioning"

After a successful install, close the Change Set:

tsm changeset close US-1234

For the full Change Set lifecycle, see Change Sets and Change Set Workflow.

Choosing a strategy​

Question→ Strategy
Is this the first deployment or a full environment reset?Full package (direct install)
Are you using Change Sets for story-level tracking?Change Set (artifact)
Is a CI/CD pipeline deploying from a feature branch?Diff between branches (artifact)
Regular incremental update to a known environment?Diff to target (artifact)

Strategies 2–4 produce an installation artifact — a reviewable, publishable archive with the diff pre-computed. Strategy 1 uses the direct install shortcut where the diff is computed at install time.

Summary​

  • There are two patterns: direct install (diff at install time) and artifact-based install (diff pre-computed).
  • A full package uses direct install — deploys all items. Use for initial deployments or full resets.
  • A diff to target creates an artifact with only the changed items compared to the target environment — the most common incremental update.
  • A diff between branches creates an artifact from Git branch differences — ideal for CI/CD pipelines and feature releases.
  • A Change Set downloads only tracked items into a Git branch and creates an artifact — enables independent, story-level releases.
  • Artifacts are stored in a non-versioned directory (build/) and can be published to Nexus or Harbor via tsm package publish.
  • Use --area-code and --entity-types to narrow artifact content further.
  • The --notes flag should always describe the release context for traceability.