Deployment Process

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

There are two deployment patterns:

Pattern	Pipeline	When to use
Direct install	Download → Validate → Diff → Install	Quick deployment; the diff is computed at install time.
Artifact-based deployment	Download → Create artifact → Publish → Install from artifact	Controlled releases; you know exactly what will be deployed before deployment.

Artifacts come in two modes — full and incremental. A full artifact contains the complete Configuration Package; when installed the target environment converges to the package state. An incremental artifact contains only selected items; everything else in the target is left untouched.

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

Strategy	What is installed	Artifact mode	When to use
Full package	All items matching package.yaml.	Full	Initial deployment, full baseline, environment reset.
Diff to target	Only items that differ from the target environment.	Incremental	Regular update to a known environment.
Diff between branches	Only items changed between Git branches.	Incremental	CI/CD feature release.
Change Set / file list	Only items tracked by a Change Set or listed explicitly.	Incremental	Story-level release from parallel development.

See also:

• Configuration Packages
• Deployment Artifacts
• Change Sets
• tSM CLI
• Configuration Reference

---

Key concepts

Deployment artifact

A deployment artifact is a self-contained archive (ZIP) ready for review, publishing, and deployment.

• Full artifact — contains all configuration items matching package.yaml. When installed, the target environment is brought into full conformance with the Configuration Package.
• Incremental artifact — contains only selected items (by diff to target, Git diff, or explicit file list). Only the included items are applied; everything else is left untouched.

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 deployment 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 can be done via direct install or via a full artifact.

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 an incremental artifact

tsm package artifact AllConfig --target-env prod --diff

The --diff flag produces an incremental artifact containing only the items that differ from the target environment:

Artifact: build/AllConfig-1.1.0-prod.zip  (incremental, diff-to-target)

ADDED (1):
  Form/SDWAN_SiteSetup

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

Total: 3 items (139 unchanged, not included)

The artifact is written to build/ (not versioned). Only the 3 changed items will be installed — everything else in the target environment stays as-is.

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 incremental 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 deployment 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	Artifact mode
Is this the first deployment or a full environment reset?	Full package	Full
Are you using Change Sets for story-level tracking?	Change Set	Incremental
Is a CI/CD pipeline deploying from a feature branch?	Diff between branches	Incremental
Regular incremental update to a known environment?	Diff to target	Incremental

Strategy 1 produces a full artifact (or can use the direct install shortcut). Strategies 2–4 produce incremental artifacts — only the selected items are applied, and everything else in the target environment is left untouched.

---

Summary

• Artifacts come in two modes: full (all package content) and incremental (only selected items).
• A full artifact brings the target environment into full conformance with the Configuration Package. Use for initial deployments, full releases, or environment resets. Can also be deployed via direct install (tsm package install without --file).
• An incremental diff-to-target artifact contains only items that differ from the target — the most common update mode.
• An incremental branch-diff artifact contains only items changed between Git refs — ideal for CI/CD feature releases.
• An incremental file-list or Change Set artifact contains only explicitly selected items — 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.