Artifact Registry
Harness Artifact Registry is a universal package store that hosts, proxies, and secures your build artifacts. The CLI (har module) lets you manage registries, push and pull packages in any supported format, inspect artifact versions, and trigger on-demand security scans without leaving your terminal.
This page covers every Artifact Registry resource and action available in the CLI.
What you will learn in this topic
By the end of this page, you will know how to:
- List and create registries for different package types.
- Configure a local package-manager client to use a Harness registry.
- Push artifacts to a registry in any of the 18 supported package formats.
- Pull artifacts back to your local machine.
- Resolve dependencies from a Harness registry with the package-manager install helpers.
- Inspect artifact metadata, versions, and files.
- Delete artifacts individually or in bulk by name pattern.
- Trigger firewall scans and copy artifacts between registries.
- Migrate external registries into Harness Artifact Registry.
Before you begin
- Harness CLI installed and authenticated: For setup steps, see Install and upgrade and Authenticate.
- Project scope configured: Artifact Registry resources require
--organd--project. Set them in your profile or pass them on each command. - Registry exists: Most push and pull commands require a registry identifier. Create one first or use an existing registry.
Registries
A registry is a named container that stores artifacts of a specific type (Docker, Helm, npm, Maven, Go, Python, or generic). Each registry belongs to a project and defines upstream proxies, cleanup policies, and access rules. You manage registries to organize artifacts by package format and control who can read or write packages.
List registries
View all registries in your current project scope to find the one you need for push or pull operations.
harness list registry
harness list registry --all --format json
harness list registry --search "<registry_name>"
Get registry details
Retrieve the full configuration of a specific registry, including its upstream sources, allowed actions, and cleanup rules.
harness get registry <registry>
harness get registry <registry> --format json
Create a registry
Create a new registry to start storing a specific package type. Each registry targets one format and supports either virtual (aggregation) or upstream (proxy) modes.
harness create registry \
--set identifier=<registry_identifier> \
--set name="<registry_name>" \
--set packageType=<package_type> \
--set type=<registry_type>
Delete a registry
Remove a registry and all artifacts stored within it. This action is irreversible.
harness delete registry <registry>
Configure a package-manager client
Point a local package-manager client at a Harness registry. The command writes the registry endpoint and credentials into the client configuration file for the registry's format, such as .npmrc for npm or pip.conf for Python.
harness configure registry <registry>
Registry metadata
Registry metadata stores extended properties like descriptions, labels, and upstream proxy configurations. Update metadata to change how the registry behaves without recreating it.
harness get registry_metadata <registry>
harness update registry_metadata <registry> --set description="<description>"
harness update registry_metadata <registry> --del <key>
Push artifacts
The push action uploads a local artifact to a registry. Each package format has its own subcommand (artifact:docker, artifact:helm, artifact:npm, and so on) that handles format-specific upload logic. Use push commands to publish build outputs from CI pipelines or local development.
Supported push formats
The CLI supports 18 push formats. Each command targets a registry of the matching package type.
| Command | Uploads |
|---|---|
harness push artifact:generic | One or more generic artifacts |
harness push artifact:maven | A Maven artifact (.jar or .war) |
harness push artifact:npm | An npm package (.tgz) |
harness push artifact:python | A Python package (.whl) |
harness push artifact:nuget | A NuGet package (.nupkg) |
harness push artifact:rpm | An RPM package |
harness push artifact:cargo | A Cargo crate (.crate) |
harness push artifact:go | A Go module |
harness push artifact:conda | A Conda package |
harness push artifact:dart | A Dart package |
harness push artifact:composer | A Composer package (.zip) |
harness push artifact:ruby | A Ruby gem |
harness push artifact:swift | A Swift package |
harness push artifact:puppet | A Puppet module (.tar.gz) |
harness push artifact:debian | A Debian package (.deb or .dsc) |
harness push artifact:conan | A Conan package |
harness push artifact:helm | A Helm chart |
harness push artifact:docker | A Docker image |
Every push command follows the same shape: the first argument is <registry>/<artifact_name> and the second is the local path or image reference.
harness push artifact:<format> <registry>/<artifact_name> <path_to_file>
Push a Docker image
Upload a tagged Docker image to a Docker-type registry. The first argument is <registry>/<image_name> and the second is the local image reference.
harness push artifact:docker <registry>/<image_name> <local_image>:<tag>
Push a Helm chart
Upload a packaged Helm chart archive to a Helm-type registry.
harness push artifact:helm <registry>/<chart_name> <path_to_chart>.tgz
Push a generic file
Upload any file type to a generic registry. Use this for build artifacts, binaries, or archives that do not fit a specific package format.
harness push artifact:generic <registry>/<artifact_name> <path_to_file>
Push a Maven artifact
Upload a JAR or POM file with Maven coordinates to a Maven-type registry.
harness push artifact:maven <registry>/<artifact_name> <path_to_jar>
Push an npm package
Upload a packed npm tarball to an npm-type registry.
harness push artifact:npm <registry>/<package_name> <path_to_tarball>.tgz
Push a Python package
Upload a source distribution or wheel to a Python-type registry.
harness push artifact:python <registry>/<package_name> <path_to_dist>
Push a Debian package
Upload a .deb or .dsc file to a Debian-type registry. Debian pushes require --distribution and --component, because the registry indexes packages by both values.
harness push artifact:debian <registry>/<package_name> <path_to_package>.deb \
--distribution <distribution> \
--component <component>
Resolve dependencies from a registry
The install helpers run your package manager against a Harness registry, so a build resolves dependencies from Harness without you editing the client configuration by hand.
harness execute artifact:npm_install
harness execute artifact:npm_ci
harness execute artifact:pip_install
harness execute artifact:mvn_install
harness execute artifact:dotnet_restore
artifact:npm_install: Runsnpm installagainst a Harness npm registry.artifact:npm_ci: Runsnpm ciagainst a Harness npm registry.artifact:pip_install: Runspip installagainst a Harness PyPI registry.artifact:mvn_install: Runs Maven dependency resolution against a Harness Maven registry.artifact:dotnet_restore: Runsdotnet restoreagainst a Harness NuGet registry.
Pull artifacts
The pull action downloads an artifact from a registry to your local machine. Use this to retrieve specific versions for debugging, deployment, or local testing. Pass the full path as <registry>/<artifact_name>/<version>.
harness pull artifact <registry>/<artifact_name>/<version>
harness pull artifact <registry>/<artifact_name>/<version> -o <output_directory>
Artifacts
An artifact represents a stored package within a registry. It groups all versions of a single logical package under one name. Use artifact commands to browse what exists in a registry, check metadata, or remove outdated packages.
List artifacts in a registry
View all artifacts stored in a specific registry. Pass the registry identifier as a positional argument.
harness list artifact <registry>
harness list artifact <registry> --all --format json
harness list artifact <registry> --search "<artifact_name>"
Get artifact details
Retrieve the full metadata for a specific artifact using the <registry>/<artifact_name> format.
harness get artifact <registry>/<artifact_name>
harness get artifact <registry>/<artifact_name> --format json
Delete an artifact
Remove an artifact and all its versions from the registry. This action is irreversible and frees the associated storage.
harness delete artifact <registry>/<artifact_name>
Delete artifacts in bulk
Delete every artifact whose name matches a pattern. --registry is required. Narrow the match with --version, preview the result with --dry-run, and skip the confirmation prompt with --force.
harness delete artifact:bulk <pattern> --registry <registry> --dry-run
harness delete artifact:bulk <pattern> --registry <registry> --version <version>
harness delete artifact:bulk <pattern> --registry <registry> --force
Run a bulk delete with --dry-run first. The command removes every matching artifact and all of its versions, and the deletion cannot be undone.
Artifact metadata
Artifact metadata stores labels, annotations, and custom properties. Update metadata to tag artifacts for tracking, filtering, or policy enforcement without modifying the artifact content.
harness get artifact_metadata <registry>/<artifact_name>
harness update artifact_metadata <registry>/<artifact_name> --set labels.team=platform
Artifact versions
Each push to an artifact creates a new version. Versions are immutable records that track the exact content, digest, and upload timestamp. You use version commands to audit what was published, compare changes across releases, or clean up old builds.
List versions
View all versions of a specific artifact to see the full release history. Pass the path as <registry>/<artifact_name>.
harness list artifact_version <registry>/<artifact_name>
harness list artifact_version <registry>/<artifact_name> --format json
Get version details
Retrieve the full metadata for a specific version, including its content digest, size, and upload time.
harness get artifact_version <registry>/<artifact_name>/<version>
harness get artifact_version <registry>/<artifact_name>/<version> --format json
Delete a version
Remove a specific version from an artifact. Other versions remain intact.
harness delete artifact_version <registry>/<artifact_name>/<version>
Version metadata
Version metadata stores per-version labels and annotations. Use it to mark versions as verified, approved, or flagged for review without altering the immutable content.
harness get artifact_version_metadata <registry>/<artifact_name>/<version>
harness update artifact_version_metadata <registry>/<artifact_name>/<version> \
--set labels.verified=true
Copy an artifact version
Copy a specific version from one registry to another without re-uploading from your local machine. Use this to promote artifacts between staging and production registries.
harness execute artifact_version:copy <registry>/<artifact_name>/<version> \
--set targetRegistry=<target_registry>
List artifact files
View the individual files that make up an artifact version (layers for Docker, files for generic archives). Use this to inspect what a version contains without downloading the full artifact.
harness list artifact_file <registry>/<artifact_name>/<version>
Security scans
Harness Artifact Registry includes a built-in firewall that scans artifacts for known vulnerabilities. Use on-demand scans to check packages before promoting them to production or after a new CVE is disclosed.
Scan all artifacts in a registry
Trigger a full scan across every artifact and version in a registry.
harness execute registry:firewall_scan <registry>
Scan a specific version
Trigger a targeted scan on a single artifact version when you need results fast.
harness execute artifact_version:firewall_scan <version> \
--registry <registry> --artifact <artifact_name>
Migrate a registry
Import artifacts from an external registry (Docker Hub, ECR, GCR, Artifactory) into Harness Artifact Registry. Use migration to consolidate scattered package stores into a single managed location. Describe the source registry in a config file and pass it with -f.
harness execute registry:migrate <registry> -f <migration_config>.yaml
Related articles
- Continuous Delivery: Manage pipelines and deployment resources.
- Infrastructure as Code Management: Manage Terraform and OpenTofu workspaces.
- Code Repository: Manage repositories and pull requests.