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: 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:

​
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:
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:

​
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)
2. Deploy to staging
3. Promote to production
4. Deploy a new version (v1.0.0 is automatically superseded)
5. Check what’s running
6. Review deployment history

​
Next Steps