Artifact Management Guide

Manage your artifacts in Harness Artifact Registry using the CLI for pushing, pulling, listing, and organizing packages.

Overview

The Harness CLI provides comprehensive artifact management capabilities:

Push artifacts from your local machine
Pull artifacts to your development environment
List and search artifacts across registries
Manage metadata for organization and tracking
Copy artifacts between registries
Delete artifacts when no longer needed

Supported Package Types

Generic

Maven

NPM

Go

Python

NuGet

Conda

Composer

Cargo

Dart

RPM

Quick Start

Set Package URL

Configure your package registry endpoint:

export PKG_URL="https://pkg.harness.io"

Push Your First Artifact

Upload a generic file:

hc artifact push generic my-registry ./myfile.zip \
  --name my-package \
  --version 1.0.0 \
  --pkg-url $PKG_URL

List Artifacts

View uploaded artifacts:

hc artifact list --registry my-registry

Add Metadata

Tag your artifact:

hc artifact metadata set \
  --registry my-registry \
  --package my-package \
  --version 1.0.0 \
  --metadata "env:production,owner:team-a"

Pushing Artifacts

Generic Artifacts

Upload any file type to the registry:

hc artifact push generic <registry> <file_path> \
  --name <package_name> \
  --version <version> \
  --pkg-url <pkg_url>

registry

string

required

Target registry identifier

file_path

string

required

Path to file to upload (supports glob patterns like *.zip)

--name, -n

string

required

Package name

--version

string

default:"1.0.0"

Version for the artifact

--filename

string

Custom filename (defaults to actual filename)

--path

string

File path within the package (defaults to filename)

--pkg-url

string

required

Base URL for the Packages service

Example:

hc artifact push generic my-registry ./dist/app-1.0.0.zip \
  --name my-app \
  --version 1.0.0 \
  --filename application.zip \
  --pkg-url https://pkg.harness.io

Maven Artifacts

Upload Maven JAR or WAR files with POM:

hc artifact push maven <registry> <file_path> \
  --pom-file <pom_path> \
  --pkg-url <pkg_url>

Maven push requires both the artifact file (.jar/.war) and POM file (.xml/.pom). The CLI validates that both files reference the same Maven coordinates.

Validation steps:

Validates file extensions (.jar, .war, .pom, .xml)
Extracts Maven coordinates from POM file
Extracts Maven coordinates from JAR/WAR artifact
Compares groupId, artifactId, and version
Generates MD5 and SHA1 checksums
Uploads artifact, POM, and checksums
Updates maven-metadata.xml

Example:

hc artifact push maven my-registry ./target/myapp-1.0.0.jar \
  --pom-file ./pom.xml \
  --pkg-url https://pkg.harness.io

Maven Upload Process

The Maven push workflow:

Validate inputs: Check file extensions and existence
Parse POM file: Extract groupId, artifactId, version
Parse artifact: Read metadata from JAR/WAR
Compare coordinates: Ensure POM and artifact match
Check SNAPSHOT: Reject SNAPSHOT versions (not yet supported)
Generate checksums: Create MD5 and SHA1 for artifact and POM
Upload artifact: Push JAR/WAR file
Upload POM: Push POM file
Upload checksums: Push all checksum files
Update metadata: Download, update, and re-upload maven-metadata.xml

SNAPSHOT versions are not currently supported via CLI. Use release versions only.

NPM Packages

Upload NPM packages from .tgz tarballs:

hc artifact push npm <registry> <tgz_path> \
  --pkg-url <pkg_url>

The CLI:

Extracts package.json from the tarball
Builds the NPM upload payload
Validates name and version
Uploads using NPM API format

Example:

# Create package tarball
npm pack

# Upload to registry
hc artifact push npm my-registry ./my-package-1.0.0.tgz \
  --pkg-url https://pkg.harness.io

NPM Upload Process

The NPM push workflow:

Validate input: Check .tgz file exists
Extract package.json: Read from tarball
Parse metadata: Get name, version, dependencies
Build payload: Create NPM-compatible upload JSON
Stream upload: Upload with progress tracking
Verify: Check successful upload

Python Packages

hc artifact push python <registry> <wheel_or_sdist> \
  --pkg-url <pkg_url>

Go Modules

hc artifact push go <registry> <module_zip> \
  --pkg-url <pkg_url>

Other Package Types

hc artifact push nuget my-registry ./MyPackage.1.0.0.nupkg \
  --pkg-url https://pkg.harness.io

Pulling Artifacts

Download artifacts from the registry:

hc artifact pull generic <registry> <package> \
  --version <version> \
  --output <path> \
  --pkg-url <pkg_url>

Example:

hc artifact pull generic my-registry my-app \
  --version 1.0.0 \
  --output ./downloads/ \
  --pkg-url https://pkg.harness.io

Listing Artifacts

List all artifacts across registries or filter by registry:

hc artifact list [options]

--registry

string

Filter by registry identifier

--page-size

integer

default:"10"

Number of items per page

--page

integer

default:"0"

Page number (zero-indexed)

Examples:

hc artifact list

Output:

Artifact         Version    Package Type    Registry       Download Count
my-app          1.0.0      GENERIC         my-registry    42
nginx           1.21.0     DOCKER          docker-prod    156
spring-boot     2.5.0      MAVEN           maven-releases 89
react-app       17.0.2     NPM             npm-registry   234

Managing Metadata

Attach key-value metadata to packages and versions for organization, searching, and tracking.

Set Metadata

Add or update metadata:

hc artifact metadata set \
  --registry <registry> \
  --package <package> \
  [--version <version>] \
  --metadata <key:value,key:value>

Without --version: Sets package-level metadata
With --version: Sets version-specific metadata

Examples:

hc artifact metadata set \
  --registry my-registry \
  --package my-app \
  --metadata "owner:team-platform,project:backend"

Get Metadata

Retrieve metadata from packages or versions:

hc artifact metadata get \
  --registry <registry> \
  --package <package> \
  [--version <version>]

Examples:

hc artifact metadata get \
  --registry my-registry \
  --package my-app

Output:

Key         Value
owner       team-platform
project     backend
approved    true
tested      2024-01-15
stage       production

Delete Metadata

Remove specific metadata keys:

hc artifact metadata delete \
  --registry <registry> \
  --package <package> \
  [--version <version>] \
  --key <key>

Example:

hc artifact metadata delete \
  --registry my-registry \
  --package my-app \
  --version 1.0.0 \
  --key approved

Working with Artifacts

Get Artifact Details

Retrieve detailed information about an artifact:

hc artifact get <artifact_id>

Copy Artifacts

Copy artifacts between registries:

hc artifact copy \
  --source-registry <source> \
  --source-package <package> \
  --source-version <version> \
  --dest-registry <destination>

Example:

hc artifact copy \
  --source-registry dev-registry \
  --source-package my-app \
  --source-version 1.0.0 \
  --dest-registry prod-registry

Delete Artifacts

Remove artifacts from registry:

hc artifact delete <artifact_id>

Deletion is permanent. Ensure you have backups or can rebuild artifacts before deleting.

Common Workflows

CI/CD Pipeline Integration

Build and Push in CI

Integrate artifact push into your CI pipeline:

.github/workflows/build.yml

name: Build and Push
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Build artifact
        run: |
          ./gradlew build
      
      - name: Install Harness CLI
        run: |
          curl -sSfL https://get.harness.io/cli | sh
      
      - name: Push to Harness
        env:
          PKG_URL: https://pkg.harness.io
          HARNESS_API_KEY: ${{ secrets.HARNESS_API_KEY }}
        run: |
          hc artifact push generic production-registry \
            ./build/libs/app.jar \
            --name my-app \
            --version ${{ github.sha }} \
            --pkg-url $PKG_URL

Tag Production Releases

Mark production-ready versions with metadata:

# After testing passes
hc artifact metadata set \
  --registry my-registry \
  --package my-app \
  --version 1.2.0 \
  --metadata "stage:production,tested:true,promoted:$(date +%Y-%m-%d)"

Promote Artifacts Between Environments

Copy artifacts from dev to staging to production:

# Dev to Staging
hc artifact copy \
  --source-registry dev-registry \
  --source-package my-app \
  --source-version 1.2.0 \
  --dest-registry staging-registry

# Add staging metadata
hc artifact metadata set \
  --registry staging-registry \
  --package my-app \
  --version 1.2.0 \
  --metadata "env:staging,promoted-from:dev"

# After validation, to production
hc artifact copy \
  --source-registry staging-registry \
  --source-package my-app \
  --source-version 1.2.0 \
  --dest-registry prod-registry

Maven Project Workflow

Build Maven Project

mvn clean package

Verify Artifacts

ls -lh target/
# myapp-1.0.0.jar
# myapp-1.0.0.war

Upload to Registry

hc artifact push maven my-registry \
  ./target/myapp-1.0.0.jar \
  --pom-file ./pom.xml \
  --pkg-url https://pkg.harness.io

Verify Upload

hc artifact list --registry my-registry

NPM Package Workflow

Build NPM Package

npm run build
npm pack

Upload Package

hc artifact push npm my-registry \
  ./my-package-1.0.0.tgz \
  --pkg-url https://pkg.harness.io

Tag Version

hc artifact metadata set \
  --registry my-registry \
  --package my-package \
  --version 1.0.0 \
  --metadata "npm-tag:latest,release-notes:https://..."

Troubleshooting

Upload Failures

Symptom: Upload fails with network errorsSolutions:

Check --pkg-url is correct
Verify network connectivity: curl -I $PKG_URL
Ensure authentication is configured
Check firewall allows outbound HTTPS
Try uploading smaller file to test

Maven Coordinate Mismatch

Error: groupId mismatch: package="com.example", pom="com.other"Solutions:

Ensure POM file matches the artifact
Rebuild with correct coordinates
Verify no manual changes to JAR/WAR
Check parent POM inheritance

File Not Found

Error: failed to access package fileSolutions:

Verify file path is correct
Check file permissions
Use absolute paths if relative paths fail
For globs, ensure pattern matches files

Authentication Issues

Error: 401 UnauthorizedSolutions:

Verify API key is valid
Check account/org/project IDs
Ensure service account has permissions
Regenerate authentication tokens

Metadata Operations Fail

Error: not found: package or version not foundSolutions:

Verify package and version exist: hc artifact list
Check registry identifier is correct
Ensure version string matches exactly
Wait for upload to complete before setting metadata

Best Practices

Version Consistently

Use semantic versioning (e.g., 1.2.3)
Include build metadata for CI builds
Never reuse version numbers
Document versioning scheme in README

Use Metadata Liberally

Tag artifacts with environment (dev/staging/prod)
Record build/test information
Link to release notes or tickets
Track ownership and approvals

Organize Registries

Separate registries by environment
Use consistent naming conventions
Create registries per team or project
Document registry purposes

Automate in CI/CD

Push artifacts in every build
Tag with git commit SHA
Set metadata with build info
Fail builds on upload errors

Next Steps

Registry Migration

Migrate artifacts from JFrog or Nexus

Artifact Commands

Complete artifact command reference

Get Started

Core Concepts

Guides

​Overview

​Supported Package Types

Generic

Maven

NPM

Go

Python

NuGet

Conda

Composer

Cargo

Dart

RPM

​Quick Start

​Pushing Artifacts

​Generic Artifacts

​Maven Artifacts

​NPM Packages

​Python Packages

​Go Modules

​Other Package Types

​Pulling Artifacts

​Listing Artifacts

​Managing Metadata

​Set Metadata

​Get Metadata

​Delete Metadata

​Working with Artifacts

​Get Artifact Details

​Copy Artifacts

​Delete Artifacts

​Common Workflows

​CI/CD Pipeline Integration

​Maven Project Workflow

​NPM Package Workflow

​Troubleshooting

​Best Practices

Version Consistently

Use Metadata Liberally

Organize Registries

Automate in CI/CD

​Next Steps

Registry Migration

Artifact Commands

Build docs developers (and LLMs) love

Overview

Supported Package Types

Quick Start

Pushing Artifacts

Generic Artifacts

Maven Artifacts

NPM Packages

Python Packages

Go Modules

Other Package Types

Pulling Artifacts

Listing Artifacts

Managing Metadata

Set Metadata

Get Metadata

Delete Metadata

Working with Artifacts

Get Artifact Details

Copy Artifacts

Delete Artifacts

Common Workflows

CI/CD Pipeline Integration

Maven Project Workflow

NPM Package Workflow

Troubleshooting

Best Practices

Next Steps