Skip to main content
This is a preview/beta feature. Further changes are expected.
Artifact Deployment Tracking lets you record which artifacts are running in which Environments, building a live view of what’s running where across your organization. Because deployment records are linked to evidence in Chainloop’s evidence store, you can trace any running artifact back to the Workflows that built or tested it, the Projects and Versions it belongs to, and the Attestations that captured its provenance.

​
Key Concepts

​
Deployment Record

A deployment record is the unit of information stored by Chainloop each time you register an artifact as running in an environment. Each record is uniquely identified by combining:
FieldDescription
EnvironmentThe infrastructure target (e.g., my-k8s-cluster)
Logical EnvironmentThe lifecycle stage (e.g., production)
Deployment NameA user-defined name for the deployment (e.g., api-server)
KindThe type of artifact (CONTAINER_IMAGE or HELM_CHART)
The record also captures the artifact reference (e.g., a container image digest), the timestamp, and the current status. Deployment records are immutable — when a new version replaces an existing one, the previous record is kept and marked as superseded, giving you a complete audit trail of what ran where and when.

​
Deployment Status

Each deployment record has one of three statuses:
StatusDescription
deployedThe artifact is currently active
supersededThe artifact was previously deployed but has been replaced by a newer version
decommissionedThe artifact has been explicitly removed

​
Automatic Superseding

When you record a new deployment that matches an existing active record (same environment, logical environment, deployment name, and kind), Chainloop automatically marks the previous record as superseded. This means you always have a clear picture of what’s currently running without manual cleanup.

​
Idempotent Recording

Recording the same artifact to the same deployment record multiple times is safe and idempotent. The deployment timestamp is updated but no duplicate records are created. This makes it safe to call from CI/CD pipelines on every run, effectively acting as a heartbeat for the deployment.

​
Recording a Deployment

Use chainloop deployment record to register that an artifact is running in an environment. You can reference the artifact by OCI image or by digest: 
# Using an OCI reference
chainloop deployment record \
  --env my-k8s-cluster \
  --logical-env production \
  --deployment-name api-server \
  --kind CONTAINER_IMAGE \
  --oci-ref ghcr.io/my-org/api-server:v1.2.0

# Or using a digest directly
chainloop deployment record \
  --env my-k8s-cluster \
  --logical-env production \
  --deployment-name api-server \
  --kind CONTAINER_IMAGE \
  --digest sha256:abc123...
The artifact must already exist in the Chainloop evidence store (i.e., it must have been previously attested). If the OCI image is hosted in a private registry, you can provide credentials explicitly via --registry-server, --registry-username, and --registry-password flags, or the CLI will use your system’s configured credentials.

​
Decommissioning

To mark an artifact as no longer running, use chainloop deployment record with --status decommissioned: 
chainloop deployment record \
  --env my-k8s-cluster \
  --logical-env production \
  --deployment-name api-server \
  --kind CONTAINER_IMAGE \
  --digest sha256:abc123... \
  --status decommissioned

​
Listing Deployments

By default, chainloop deployment list shows only currently active deployments. Use --history to include superseded and decommissioned records. You can filter by --env or --logical-env. See the CLI Reference for the full list of flags and options.

​
Typical Workflow

Here’s an end-to-end example of how deployment tracking fits into a delivery pipeline: 1. Set up environments (one-time) 
# Create environments
chainloop environment create --name k8s-east --description "Kubernetes US-East"
chainloop environment create --name k8s-west --description "Kubernetes US-West"

# Logical environments (development, staging, production) are created automatically
2. Deploy to staging 
chainloop deployment record \
  --env k8s-east \
  --logical-env staging \
  --deployment-name api-server \
  --kind CONTAINER_IMAGE \
  --oci-ref ghcr.io/my-org/api-server:v1.0.0
3. Promote to production 
chainloop deployment record \
  --env k8s-east \
  --logical-env production \
  --deployment-name api-server \
  --kind CONTAINER_IMAGE \
  --oci-ref ghcr.io/my-org/api-server:v1.0.0
4. Deploy a new version (v1.0.0 is automatically superseded) 
chainloop deployment record \
  --env k8s-east \
  --logical-env production \
  --deployment-name api-server \
  --kind CONTAINER_IMAGE \
  --oci-ref ghcr.io/my-org/api-server:v1.1.0
5. Check what’s running 
chainloop deployment list --logical-env production
6. Review deployment history 
chainloop deployment list --env k8s-east --logical-env production --history

​
Next Steps