Installation Artifacts

An installation artifact is the deployable output of the packaging build process — a self-contained ZIP archive containing exactly the configuration items to be installed, with the diff against the target environment pre-computed at creation time.

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

See also:

• Configuration Packages
• Installation Process — strategies for using artifacts
• tSM CLI
• Configuration Reference

---

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 install
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. The command reads the local package directory, computes the diff against the target environment, and writes a ZIP archive containing only the changed items.

tsm package artifact AllConfig --target-env prod

Output:

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)

Naming convention

Default: build/<packageId>-<version>-<env>.zip

The name encodes the package identity, version, and the target environment the diff was computed against.

Scoping

You can narrow the artifact to specific areas or entity types:

# 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

Branch-based artifacts

For CI/CD feature releases, compute the diff from a Git branch range instead of the full package content:

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

The CLI determines which configuration files changed between the two branches and includes only those in the artifact.

---

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	Only the items that differ from the target — added, modified, or (when allowDelete: true) removed.
Manifest	Summary of what is included: counts of added, modified, removed, and unchanged items.

Unchanged items are excluded from the artifact. This keeps the archive small and the install fast.

---

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 artifacts

Scenario	Recommendation
First deployment or full environment reset	Direct install (tsm package install without --file)
Incremental update to a known environment	Artifact — review the delta before deploying
CI/CD pipeline with branch-based releases	Artifact with --branch-diff — deploy exactly what changed
Story-level release with Change Sets	Artifact — download changeset items, build artifact, install
Quick development-time test	Direct install — faster feedback loop

For detailed installation strategies, see Installation Process.

---

Summary

• An installation artifact is a self-contained ZIP archive with a pre-computed diff.
• 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.
• Use --area-code and --entity-types to narrow artifact scope.
• Use --branch-diff for CI/CD feature releases based on Git branch differences.
• The --notes flag should always describe the release context for traceability.