> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifact Deployment Tracking

> Track where your artifacts are running across your environments.

<Warning>
  This is a preview/beta feature. Further changes are expected.
</Warning>

Artifact Deployment Tracking lets you record which artifacts are running in which [Environments](/concepts/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](/concepts/workflows) that built or tested it, the [Projects and Versions](/concepts/projects-versions) it belongs to, and the [Attestations](/concepts/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:

| Field                   | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| **Environment**         | The infrastructure target (e.g., `my-k8s-cluster`)          |
| **Logical Environment** | The lifecycle stage (e.g., `production`)                    |
| **Deployment Name**     | A user-defined name for the deployment (e.g., `api-server`) |
| **Kind**                | The 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:

| Status           | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `deployed`       | The artifact is currently active                                              |
| `superseded`     | The artifact was previously deployed but has been replaced by a newer version |
| `decommissioned` | The 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:

```bash theme={"dark"}
# 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...
```

<Note>
  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.
</Note>

## Decommissioning

To mark an artifact as no longer running, use `chainloop deployment record` with `--status decommissioned`:

```bash theme={"dark"}
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](/command-line-reference/cli-ee-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)

```bash theme={"dark"}
# 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**

```bash theme={"dark"}
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**

```bash theme={"dark"}
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)

```bash theme={"dark"}
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**

```bash theme={"dark"}
chainloop deployment list --logical-env production
```

**6. Review deployment history**

```bash theme={"dark"}
chainloop deployment list --env k8s-east --logical-env production --history
```

## Next Steps

* [Environments and Logical Environments](/concepts/environments) — Set up your infrastructure targets and lifecycle stages
* [Attestations](/concepts/attestations) — Learn how evidence is collected and signed
* [Projects and Versions](/concepts/projects-versions) — Organize your software components