> 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/get-started/key-concepts.md).

# Key concepts

A short introduction to the core concepts in Harness Artifacts, covering what each one is, why it matters, and where to learn more.

Harness Artifacts is built around a small set of concepts that work together. A registry stores artifacts. An upstream proxy caches artifacts from outside your organization. Policies govern what can enter and what can leave. Rules determine how long artifacts are kept. Understanding these concepts once makes every other part of the product easier to use.

This page gives you the one-paragraph version of each concept. Every section links to the full concept page when you are ready to go deeper.

***

## The storage layer

### Registry

A **registry** is a named, typed store for one artifact format. Every artifact you push goes into a registry. Every artifact your pipelines or developers pull comes from one. Registries live at a scope: account, organization, or project. The scope controls who can see them. A registry at the account scope is available to your whole organization; one at the project scope is visible only within that project.

Go to [Registries and upstream proxies](https://developer.harness.io/artifact-registry/3.0/concepts/registries-and-upstream-proxies.md) to understand the difference between local registries and upstream proxies, and how they work together.

### Artifact

An **artifact** is what gets stored: a container image, a package, a chart, a library, or a file. Each artifact has a name, one or more versions, and optionally one or more tags. A tag is a mutable label like `latest` or `2.4.1`. A digest is an immutable cryptographic fingerprint of the exact content. For production deployments where you need to guarantee exactly which bytes you are running, a digest is more reliable than a tag.

Go to [Artifact identity](https://developer.harness.io/artifact-registry/3.0/concepts/artifact-identity.md) to understand the difference between tags and digests, what a PURL is, and how multi-architecture images work.

### Upstream proxy

An **upstream proxy** is a caching layer between your team and an external registry such as Docker Hub, Maven Central, npm, or PyPI. When a developer or pipeline requests a package through an upstream proxy, Harness checks its local cache first. On a cache hit, the package is served instantly without a network call to the internet. On a miss, Harness fetches from the upstream source, caches the result, and returns it. After the first pull, your builds no longer depend on the availability of the external registry.

Go to [Registries and upstream proxies](https://developer.harness.io/artifact-registry/3.0/concepts/registries-and-upstream-proxies.md) for how resolution order works when a local registry has upstream proxies attached.

***

## Access and identity

### Authentication and identity tokens

Every private registry operation requires a token. Harness issues two token types: **Personal Access Tokens (PATs)** for human users, and **service account tokens** for pipelines and automation. Both use HTTP basic auth: the token is the password. Service account tokens are the right choice for CI/CD pipelines because they are not tied to a person and keep working regardless of team changes. Pipelines running on a schedule or triggered by a webhook run as a service account identity, not as the person who set them up.

Go to [Authentication and identity tokens](https://developer.harness.io/artifact-registry/3.0/concepts/authentication-and-identity-tokens.md) to understand token types, the Setup Client flow, and why scheduled pipelines sometimes fail with 403 errors when manual runs succeed.

### Registry visibility

Every registry is either **private** or **public**. Private is the default: all operations require authentication and the appropriate RBAC permission. Public allows unauthenticated pulls from anyone with the URL, which is appropriate for distributing software to external users or the community. Pushing always requires authentication, regardless of visibility. Most registries in most organizations should remain private.

Go to [Registry visibility](https://developer.harness.io/artifact-registry/3.0/concepts/registry-visibility.md) for when public visibility is appropriate and the account settings required to enable it.

***

## Security and compliance

### Dependency Firewall

**Dependency Firewall** evaluates open-source packages at the upstream proxy boundary, before they are cached in your registry. When a developer requests a package from an upstream proxy with Dependency Firewall enabled, Harness evaluates the package against your configured policies before serving it. A package can be blocked entirely, allowed through, or allowed through with a warning. Five built-in policy templates cover the most common supply chain risks: CVSS vulnerability threshold, license compliance, package age, open-source software (OSS) health score, and malicious package detection.

Go to [Dependency Firewall](https://developer.harness.io/artifact-registry/3.0/concepts/dependency-firewall.md) to understand evaluation verdicts, the first-pull window, and the five built-in policy templates.

### Security scanning

**Security scanning** automatically scans every container image pushed to a Docker or Helm registry that has scanning enabled. Harness creates and runs the **HARNESS ARTIFACT SCAN PIPELINE** on every push; you do not configure or manage this pipeline. The scanner (Aqua Trivy or Grype, selected per registry) checks the image's OS packages and application dependencies against vulnerability databases and reports findings by severity. If you attach a Security Tests policy set to the registry, images that violate the policy are automatically **quarantined**: blocked from being pulled until reviewed and released.

Go to [Security scanning](https://developer.harness.io/artifact-registry/3.0/concepts/security-scanning.md) to understand how quarantine works, the async scanning window, and how security scanning integrates with Security Testing Orchestration (STO) and Supply Chain Security (SCS).

### SBOM and software supply chain

A **Software Bill of Materials (SBOM)** is a machine-readable inventory of every component inside an artifact. When security scanning runs on a container image, Harness generates an SBOM alongside the vulnerability scan. The SBOM records every package, its version, its supplier, its license, and its relationship to other components. You can view the SBOM and download it in CycloneDX or Software Package Data Exchange (SPDX) format directly from the artifact detail page. This is the foundation for license audits, compliance submissions, and blast-radius analysis when a CVE affects a commonly used component.

Go to [SBOM and software supply chain](https://developer.harness.io/artifact-registry/3.0/concepts/sbom-and-supply-chain.md) to understand SBOM formats, scoring, SLSA provenance, and regulatory requirements.

***

## Lifecycle management

### Lifecycle rules

**Lifecycle rules** automate artifact cleanup so registries do not accumulate thousands of versions that are never used again. A **cleanup rule** defines the criteria for deletion (for example, delete any version older than 90 days that has not been downloaded in 30 days) and runs on a cron schedule. A **retention rule** permanently protects matching versions from any cleanup rule. Both rule types work together: the retention rule is always evaluated first and always wins. Deleted versions go through a soft-delete recovery window before permanent removal, so a misconfigured rule does not cause immediate, irreversible data loss.

Go to [Lifecycle rules](https://developer.harness.io/artifact-registry/3.0/concepts/lifecycle-rules.md) to understand cleanup criteria, retention rules, deployment-aware protection for Docker, and how to run a dry run before activating a new rule.

***

## Frequently asked questions

<details>

<summary>What is the difference between a registry and an upstream proxy?</summary>

A registry stores artifacts you push yourself. An upstream proxy caches artifacts from an external source such as Docker Hub or npm. A local registry can have one or more upstream proxies attached, so a single pull endpoint can serve both your own artifacts and cached external ones.

</details>

<details>

<summary>Do I need a different token for every registry?</summary>

No. A Personal Access Token or service account token authenticates against any registry your identity has access to. You generate the token once through **Setup Client** and reuse it across registries, subject to RBAC permissions and the token's expiry.

</details>

<details>

<summary>Is Dependency Firewall the same as security scanning?</summary>

No. Dependency Firewall evaluates open-source packages at the upstream proxy boundary, before they are cached, and can block them from entering your registry. Security scanning runs after a Docker or Helm image is already pushed to a registry and quarantines it if it violates a policy. The two features protect different points in the artifact lifecycle.

</details>

## Next steps

* To push your first artifact, go to [Quickstart: push your first artifact](https://developer.harness.io/artifact-registry/3.0/get-started/quickstart.md).
* To understand how all the formats Artifacts supports work, go to [Supported formats](https://developer.harness.io/artifact-registry/3.0/get-started/supported-formats.md).
* To see how Artifacts fits into a broader CI/CD and security workflow, go to [How Artifacts fits your workflow](https://developer.harness.io/artifact-registry/3.0/get-started/how-ar-fits-your-workflow.md).
* To look up a specific term, go to [Glossary](https://developer.harness.io/artifact-registry/3.0/concepts/glossary.md).

{% @harness-feedback/feedback %}
