Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
BETA

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.

This feature is in Beta and requires enablement. View all early access features.

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.

Upstream proxy registries

Artifacts deleted from an upstream proxy registry are removed from the local cache only. To retrieve them again, Harness must re-pull them from the remote source. Go to Create an upstream proxy for details.

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

  1. Navigate to the artifact you want to delete. You can reach it from the global Artifacts list or from a registry's Packages tab.

  2. To delete a specific version, open the artifact and go to its version list.

  3. Click the three-dot menu (⋮) next to the artifact or version.

  4. Select Delete.

  5. In the confirmation dialog, type the exact name to confirm.

  6. To permanently delete instead of soft delete, select the Permanently delete checkbox.

  7. 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

  1. In the left navigation, select Artifacts.

  2. Click the Show menu above the table.

  3. Select Deleted.

Use the Registries and Package Types filters to narrow the results.

From inside an artifact

  1. Open the artifact.

  2. 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:

  1. Go to the Deleted view.

  2. Click the three-dot menu (⋮) next to the item.

  3. 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.

  1. Go to Account Settings > Default Settings.

  2. 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=false or 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

I deleted a tag but the image still appears in the registry

Deleting a tag removes only that label. The image stays in the registry, accessible by its digest, until you delete the version itself. To remove the image, open the artifact's version list and delete the specific version by its digest.

Can I delete an artifact that is quarantined?

Yes. Quarantine blocks pull and download operations but does not block deletion. If a retention rule or an active Harness CD deployment is protecting the version, the delete fails and the error message identifies the blocking condition. To restore pull access without deleting, select Remove from Quarantine instead.

The Delete option does not appear in the menu

Your role may not include the Delete Artifact permission. Contact your account administrator to review your role assignments. Go to RBAC and permissions for the permission list.

Are soft deleted items counted against my storage quota?

Yes. Soft deleted items remain in storage and continue to count toward your storage usage until Harness purges them at the end of the retention window. To free storage immediately, select the item in the Deleted view and permanently delete it.

How do I soft delete or permanently delete via API?

Use the v3 delete API endpoints with the force query parameter. Set force=false (or omit it) for soft delete, or force=true for permanent delete. Endpoints: deleteregistryv3, deletepackagev3, and deleteversionv3. Go to the Harness API documentation for full reference and authentication details.

Next steps

Last updated

Was this helpful?