Delete an artifact
Soft delete or permanently delete an artifact or version, find deleted items on the Deleted view, and restore them before the retention window closes.
Harness Artifacts supports two deletion modes:
Soft delete: Moves the artifact or version to a recoverable Deleted state. The item is no longer downloadable but stays in storage until the retention window expires. You can restore it any time before then.
Permanent delete: Removes the item immediately and cannot be undone.
When soft delete is enabled for your account, Harness defaults to soft delete. You can switch to permanent delete in the confirmation dialog.
Before you begin
Your role must include the Delete Artifact permission on the registry. Go to RBAC and permissions to review permission requirements.
A version that is actively deployed through Harness CD or protected by a retention rule may be blocked from deletion. When this happens, the error message identifies the blocking condition.
Delete an artifact or version
Navigate to the artifact you want to delete. You can reach it from the global Artifacts list or from a registry's Packages tab.
To delete a specific version, open the artifact and go to its version list.
Click the three-dot menu (⋮) next to the artifact or version.
Select Delete.
In the confirmation dialog, type the exact name to confirm.
To permanently delete instead of soft delete, select the Permanently delete checkbox.
Click Delete.
When you soft delete an artifact (the package), all its versions are soft deleted at the same time.
What happens to clients after a soft delete
Soft deleted items are immediately non-downloadable:
A pull of a soft deleted Docker image returns HTTP 404 with
MANIFEST_UNKNOWN.A pull of a soft deleted Maven, Python, or Generic artifact returns HTTP 404.
If the registry has an upstream proxy configured, a pull may still succeed from the upstream source.
Soft deleted items continue to count toward your storage usage until Harness purges them.
Find deleted items
Soft deleted items move to a Deleted view.
From the global Artifacts list
In the left navigation, select Artifacts.
Click the Show menu above the table.
Select Deleted.
Use the Registries and Package Types filters to narrow the results.
From inside an artifact
Open the artifact.
In the version list, look for the Deleted section below the available versions.
If the artifact itself was soft deleted, the artifact header shows a DELETED state while the deleted versions remain visible inside.
Restore a deleted item
From the Deleted view or the deleted section within an artifact, click the three-dot menu (⋮) and select Restore.
Restoring a version also restores the parent artifact if it was soft deleted. You do not need to restore the artifact separately before restoring a version.
Permanently delete a soft deleted item
To remove a soft deleted item before the retention window expires:
Go to the Deleted view.
Click the three-dot menu (⋮) next to the item.
Select Delete.
This is permanent and cannot be undone. Storage usage decreases at the next measurement cycle.
Configure the retention period
Account administrators set how long soft deleted items are kept before Harness purges them.
Go to Account Settings > Default Settings.
Under Artifact Registry, set the Soft Delete Retention Period.
The field accepts a whole number from 1 to 3650 (days). The default is 30 days. One retention period applies to the entire account; it cannot be overridden per organization or project.
Changing the period applies to all existing soft deleted items immediately. If you shorten it, items already in the Deleted view may be purged at the next scheduled purge run if they are older than the new value.
Delete via API
The delete API endpoints require the artifact digest (SHA hash), not the tag name. To retrieve the digest, open the version details page and copy it from the version selector or pull command.
Soft delete: call the delete endpoint with
force=falseor omit the parameter.Permanent delete: call the delete endpoint with
force=true.
Relevant endpoints: deleteregistryv3, deletepackagev3, deleteversionv3. Go to the Harness API documentation for full reference.
Troubleshooting
Next steps
Last updated
Was this helpful?