Version: 2.4

Deployment Artifacts

A deployment artifact is the deployable output of the packaging build process — a self-contained ZIP archive ready for review, publishing, and deployment.

Artifacts come in two modes:

Mode	Contents	Install behavior
Full	All configuration items matching `package.yaml`.	The target environment converges to the package state — items are added, updated, or removed to match.
Incremental	Only selected items (by diff, Git range, or explicit list).	Only the included items are applied; everything else in the target environment is left untouched.

Artifacts are build outputs, not source. They live in a non-versioned directory (typically build/) and should be added to .gitignore.

Why artifacts?

The direct tsm package install command computes the diff at install time and applies everything in one step. This is convenient but has drawbacks:

you cannot review the exact set of changes before they hit the target
there is no publishable, versioned object you can deploy through environments
rollback requires re-installing the previous package directory — there is no immutable snapshot

An artifact solves all three problems:

Concern	Direct install	Artifact-based deployment
Diff timing	Computed at install time	Pre-computed at creation time
Reviewable	No — install is immediate	Yes — inspect before deploying
Publishable	No	Yes — push to Nexus, Harbor, or file share
Immutable	No — source directory may change	Yes — ZIP is a frozen snapshot
CI/CD friendly	Possible but opaque	Designed for pipeline handoff

Where artifacts live

Artifacts are written to a build/ directory at the workspace root by default:

project/
  tsm-project.yaml
  packages/
    AllConfig/
      package.yaml
      ...
    SDWAN/
      package.yaml
      ...
  build/                          # ← artifact output (non-versioned)
    AllConfig-1.1.0-prod.zip
    SDWAN-1.5.0-test.zip

Add build/ to .gitignore:

# .gitignore
build/

The output directory can be overridden with the --out flag on tsm package artifact.

Creating an artifact

Use tsm package artifact to build an artifact.

Full artifact (default)

Without any scoping flag, the artifact includes all configuration items matching package.yaml. When installed, the target environment is brought into full conformance with the Configuration Package — items are added, updated, or (when allowDelete: true) removed.

tsm package artifact AllConfig --target-env prod

Artifact: build/AllConfig-1.1.0-prod.zip  (full)

Total: 142 items

Incremental artifact

Add a scoping flag to include only selected items. Everything else in the target environment stays untouched.

Three scoping methods are available:

Diff to target

Include only items that differ between the local package directory and the target environment:

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

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)

Git diff

Include only items whose files changed between two Git refs — ideal for feature-branch releases:

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

The CLI determines which configuration files changed in the branch range and includes only those items.

Explicit file list

Include only items listed in a text file (one path per line, relative to the package directory):

tsm package artifact AllConfig --target-env prod \
  --files release-items.txt

Further narrowing

Both full and incremental artifacts can be narrowed by area or entity type:

# Only the ordering area
tsm package artifact AllConfig --target-env prod \
  --area-code ordering

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

What an artifact contains

An artifact is a ZIP archive with:

Component	Description
`package.yaml`	The package definition at the time of creation.
Configuration items	Full: all items matching the package definition. Incremental: only the selected items.
Manifest	Summary of what is included: artifact mode, counts of added, modified, removed, and unchanged items.

Publishing an artifact

Push an artifact to a remote repository for controlled deployment through environments:

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

Supported registries include Nexus, Harbor, and any repository configured in tsm-project.yaml or CLI settings.

Installing from an artifact

Install uses the same tsm package install command with the --file flag:

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

Only the items in the artifact are applied. The server creates an Installed Package record for traceability.

Artifact lifecycle in CI/CD

A typical pipeline:

Example pipeline

stages:
  - build
  - publish
  - deploy-test
  - deploy-prod

build-artifact:
  stage: build
  script:
    - tsm package artifact AllConfig --target-env test
  artifacts:
    paths:
      - build/

publish-artifact:
  stage: publish
  script:
    - tsm package publish build/AllConfig-*.zip --repository nexus

deploy-test:
  stage: deploy-test
  script:
    - tsm package install --file build/AllConfig-*.zip --target-env test
      --notes "CI pipeline $CI_PIPELINE_ID"

deploy-prod:
  stage: deploy-prod
  when: manual
  script:
    - tsm package install --file build/AllConfig-*.zip --target-env prod
      --notes "CI pipeline $CI_PIPELINE_ID — deployed to prod"

When to use which mode

Scenario	Mode	Command
First deployment or full environment reset	Full	`tsm package artifact AllConfig --target-env prod`
Regular full release	Full	`tsm package artifact AllConfig --target-env prod`
Incremental update to a known environment	Incremental (diff)	`tsm package artifact AllConfig --target-env prod --diff`
CI/CD pipeline with branch-based releases	Incremental (Git)	`tsm package artifact AllConfig --branch-diff main..feature/X --target-env test`
Story-level release with Change Sets	Incremental (files)	`tsm package artifact AllConfig --target-env prod --files release-items.txt`
Quick development-time test	Direct install	`tsm package install AllConfig --target-env dev` (no artifact)

For detailed deployment strategies, see Deployment Process.

Summary

A deployment artifact is a self-contained ZIP archive — either full or incremental.
Full artifacts contain all package content; on install the target environment converges to the package state.
Incremental artifacts contain only selected items; everything else in the target environment is left untouched.
Incremental scope is determined by: --diff (diff to target), --branch-diff (Git range), or --files (explicit list).
Artifacts live in a non-versioned directory (build/) — never commit them to Git.
Created with tsm package artifact, published with tsm package publish, installed with tsm package install --file.
Artifacts are immutable, reviewable, and publishable — ideal for controlled release pipelines.
The --notes flag should always describe the release context for traceability.

Why artifacts?​

Where artifacts live​

Creating an artifact​

Full artifact (default)​

Incremental artifact​

Diff to target​

Git diff​

Explicit file list​

Further narrowing​

What an artifact contains​

Publishing an artifact​

Installing from an artifact​

Artifact lifecycle in CI/CD​

Example pipeline​

When to use which mode​

Summary​