Artifact & Image Management
Relevant source files
The following files were used as context for generating this wiki page:
- api/v2.0/swagger.yaml
- tests/apitests/python/library/artifact.py
- src/server/middleware/artifactinfo/artifact_info.go
- src/portal/src/app/base/project/repository/artifact/artifact-list-page/artifact-list/artifact-list-tab/artifact-list-tab.component.ts
- src/server/middleware/quota/copy_artifact.go
- src/server/middleware/subject/subject_test.go
Artifact & Image Management is the core functional module of Harbor Next responsible for the lifecycle of container images and OCI-compliant artifacts. It encompasses the storage, identification, scanning, and metadata enrichment of artifacts within projects and repositories. The system supports various artifact types beyond standard Docker images, including Helm charts, CNAB, and WASM modules.
The module provides robust APIs and UI components for listing, copying, tagging, and deleting artifacts. It integrates tightly with security services for vulnerability scanning and SBOM (Software Bill of Materials) generation, ensuring that every artifact is verifiable and secure before deployment.
Artifact Data Model and Identification
Artifacts in Harbor are identified by their project, repository, and a reference (either a tag or a digest). The system treats artifacts as high-level entities that can contain multiple tags and accessories.
Core Data Structure
The Artifact definition includes properties for size, media type, push/pull times, and associated metadata like labels and scan overviews.
| Field | Type | Description |
|---|---|---|
id | integer | Internal unique identifier for the artifact |
type | string | Artifact category (e.g., IMAGE, CHART, CNAB, WASM) |
digest | string | Content-addressable sha256 identifier |
media_type | string | The MIME type of the artifact content |
size | integer | Total size of the artifact in bytes |
push_time | string | Timestamp when the artifact was uploaded |
Sources: api/v2.0/swagger.yaml:1894-1960, src/portal/src/app/base/project/repository/artifact/artifact-list-page/artifact-list/artifact-list-tab/artifact-list-tab.component.ts:740-746
Identification Logic
The server uses middleware to extract artifact information from request URLs. This logic parses repository names and determines if a reference is a digest or a tag.
The parsing logic uses regular expressions to identify sub-expressions like lib.RepositorySubexp and lib.ReferenceSubexp.
Sources: src/server/middleware/artifactinfo/artifact_info.go:48-125
Artifact Operations
Harbor supports a range of operations to manage the artifact lifecycle, accessible via REST APIs or the management portal.
Copying Artifacts
Copying artifacts between repositories involves checking project quotas and walking the artifact tree to ensure all associated blobs are accounted for.
Tagging and Deletion
Tags provide human-readable aliases for digests. Deleting an artifact typically removes the underlying digest and all associated tags.
- Create Tag: Associates a new name with an existing artifact reference.
- Delete Artifact: Removes the artifact specified by reference. If a digest is deleted, all referencing tags are also removed.
- List Tags: Retrieves tags for a specific artifact, including their immutable status.
Sources: api/v2.0/swagger.yaml:705-780, tests/apitests/python/library/artifact.py:84-106
Security and Interrogation Services
Artifacts are enriched with security data through interrogation services, specifically vulnerability scanning and SBOM generation.
Scanning Workflow
The scanning process is asynchronous. Users trigger a scan, and the system updates the scan_overview once complete.
| Component | Function |
|---|---|
ScanOverview | Contains NativeReportSummary with severity levels and vulnerability counts |
SBOMOverview | Tracks the status and digest of the generated SBOM accessory |
Accessory | Specialized artifacts (like signatures or SBOMs) linked to a subject artifact |
Sources: api/v2.0/swagger.yaml:1949-1959, 2038-2082, src/portal/src/app/base/project/repository/artifact/artifact-list-page/artifact-list/artifact-list-tab/artifact-list-tab.component.ts:600-650
Artifact Accessories and Signatures
Accessories are OCI artifacts that "belong" to a subject artifact. These include:
- Cosign/Notary Signatures: Verification data for content trust.
- SBOMs: List of packages and dependencies.
- Subjects: Links established via the OCI
subjectfield in manifests.
Project Quotas and Resource Control
Every artifact operation that adds storage (like copying or pushing) is intercepted by the Quota Middleware.
- Count Quota: Limits the number of artifacts per project.
- Storage Quota: Limits the total byte size of non-foreign layers in a project.
- Validation: If an operation (e.g.,
CopyArtifact) exceeds these limits, the system returns a412 Precondition Failederror and triggers aResourcesExceededevent.
Sources: src/server/middleware/quota/copy_artifact.go:45-53, api/v2.0/swagger.yaml:1385-1440
Conclusion
Artifact & Image Management provides the foundational infrastructure for OCI artifact storage in Harbor Next. By combining content-addressable identification with flexible metadata (tags, labels) and security interrogation (Scanning, SBOM), the system ensures that artifacts are both discoverable and trustworthy. The architecture maintains strict control over resources through quota middleware while supporting complex relationships via the artifact accessory model.