> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/concepts/artifact-identity.md).

# Artifact identity

Understand how artifacts are identified by name, version, tag, and digest, and why mutable and immutable references matter for security.

When you pull a container image or install a package, you are making an identity claim: "I want this specific thing." But "this specific thing" means different things depending on whether you use a tag or a digest, and that distinction determines whether your builds and deployments are reproducible.

## The four identity concepts

### Artifact

An **artifact** is the named package, the thing itself. For a Docker image, the artifact is the image name, such as `my-org/payment-service`. For an npm package, it is the package name, such as `@my-org/auth-client`. The artifact groups all versions of that thing together.

### Version

A **version** is one specific release of an artifact. It is what gets pushed to a registry, scanned for vulnerabilities, and deployed. For Docker images, a version is identified by a tag or a digest. For package ecosystems like Maven or npm, a version follows a semantic versioning string such as `2.4.1` or `1.0.0-SNAPSHOT`.

### Tag

A **tag** is a mutable, human-readable label that points to a version. Tags are convenient; `latest`, `stable`, `1.25.2` are human-readable labels. However, tags can be moved. Someone can push a new image to `latest` tomorrow and the label silently points to different content. A build that used `latest` on Monday may get a different image on Friday.

### Digest

A **digest** is an immutable cryptographic fingerprint of the content. It takes the form `sha256:a3c4b2…`. Unlike a tag, a digest cannot be changed. Once computed, it permanently identifies exactly those bytes and no others. If you reference an image by digest and it pulls successfully, you are certain you got the same bytes every time.

## Mutable and immutable references

The following table shows the practical difference:

| Reference type       | Example                          | Can be changed?     | Use for                              |
| -------------------- | -------------------------------- | ------------------- | ------------------------------------ |
| Tag                  | `payment-service:latest`         | Yes                 | Development, convenience             |
| Tag (pinned version) | `payment-service:2.4.1`          | Yes (by re-tagging) | Most production use                  |
| Digest               | `payment-service@sha256:a3c4b2…` | No                  | High-security production, compliance |

For most workloads, a pinned semantic version tag provides a good balance. For regulated environments, or when you need to guarantee bit-for-bit reproducibility across deployments, reference by digest.

{% hint style="info" %}
**Reproducibility in Harness Artifacts**

The artifact details page shows both the tag and the digest for every Docker image version. Copy the digest from there to use in Kubernetes manifests or deployment configurations.
{% endhint %}

## PURL: cross-ecosystem artifact identity

Different package ecosystems use different identity schemes. Docker uses `registry/name:tag`, npm uses `@scope/name@version`, Maven uses `groupId:artifactId:version`. This fragmentation makes it hard to talk about an artifact in a tool-agnostic way.

**Package URL (PURL)** is an open standard that unifies artifact identity across ecosystems. The format is:

```
pkg:<type>/<namespace>/<name>@<version>
```

Examples:

| Ecosystem | PURL                                             |
| --------- | ------------------------------------------------ |
| npm       | `pkg:npm/%40my-org/auth-client@1.0.0`            |
| Maven     | `pkg:maven/com.example/payment-service@2.4.1`    |
| Docker    | `pkg:docker/my-org/payment-service@sha256:a3c4…` |
| PyPI      | `pkg:pypi/requests@2.31.0`                       |

PURLs appear in the Dependency Firewall evaluation details and in SBOM reports. Vulnerability databases such as Open Source Vulnerabilities (OSV) and National Vulnerability Database (NVD) also use PURLs to identify affected packages. When an SBOM lists a component by PURL, any tool that understands PURLs can immediately look up known vulnerabilities, without knowing anything specific about the registry it came from.

## Multi-arch images

A single Docker tag can point to an **index manifest**, a manifest of manifests, that lists images for multiple CPU architectures such as `linux/amd64`, `linux/arm64`, and `linux/arm/v7`. When you pull the tag on an ARM machine, Docker automatically fetches the ARM image. When you pull on x86, you get the x86 image.

The top-level digest identifies the index manifest. Each architecture has its own digest. Harness Artifacts displays both in the artifact details view, so you can pin to the exact architecture image when necessary.

## Custom metadata

You can attach custom key-value pairs to any artifact version. This is useful for traceability that goes beyond the artifact content itself:

* `git-sha: 3f4a9b2`, the commit that produced this version
* `build-id: ci-1204`, the CI run
* `approved-by: platform-team`, a sign-off recorded in the registry

Custom metadata does not affect resolution or security evaluation. It is a lightweight mechanism for attaching context that your governance or audit processes depend on.

Go to [Artifact version details](https://developer.harness.io/artifact-registry/3.0/artifacts/artifact-version-details.md) to view tags, digests, and metadata for a specific version.

## Use cases

### Pinning production Kubernetes deployments

A Kubernetes deployment that uses `payment-service:latest` will silently roll out whatever content was last pushed with that tag. Use the digest instead:

```yaml
image: pkg.harness.io/my-account/prod-docker/payment-service@sha256:a3c4b2…
```

The exact image that passed security scanning and staging validation is the exact image deployed to production.

### Floating tags in development

During development, `latest` is a practical choice. Developers always get the most recent build without updating their local configuration. The risk is acceptable in a non-production context where reproducibility is less critical.

### PURL as canonical identity in vulnerability management

When your security team tracks a CVE that affects `requests@2.28.0`, they can query your SBOM reports using the PURL `pkg:pypi/requests@2.28.0` to find every artifact that includes the affected version, regardless of which registry or CI system produced it.

{% @harness-feedback/feedback %}
