Skip to content

[docs-scanner] Tag deletion docs don't mention immutable tags restriction #25997

Description

@docker-agent

Files:

  • content/manuals/docker-hub/repos/manage/hub-images/tags.md
  • content/manuals/docker-hub/repos/manage/hub-images/manage.md
  • content/manuals/docker-hub/repos/manage/hub-images/immutable-tags.md

Issue

The documentation has a cross-document contradiction about tag deletion. The immutable-tags.md file states:

Immutable tags are image tags that, once pushed to Docker Hub, cannot be overwritten or deleted.

However, both tags.md and manage.md provide instructions for deleting tags without mentioning immutable tags or any restrictions:

  • tags.md has a section "Delete repository tags" (lines 51-67) that explains how to delete tags with no mention of immutable tags
  • manage.md has deletion instructions (lines 29-56) that also don't mention immutable tags

Why this matters

A reader who has enabled immutable tags for their repository would follow the deletion instructions in tags.md or manage.md and be confused when:

  1. The deletion fails or is prevented
  2. They can't delete specific tags that are marked as immutable
  3. They don't understand why some tags can be deleted and others cannot

The deletion documentation should acknowledge that immutable tags cannot be deleted and either:

  • Link to the immutable tags documentation
  • Explain that deletion only works for mutable tags
  • Note that users need to check their repository's tag mutability settings

Suggested fix

Add a note or caveat to both tags.md and manage.md before the deletion instructions:

In tags.md, before "Delete repository tags" section:

> [!NOTE]
> If your repository has [immutable tags](./immutable-tags.md) enabled, those tags cannot be deleted. Only mutable tags can be deleted.

In manage.md, before the deletion steps:

> [!NOTE]
> Immutable tags cannot be deleted. If your repository uses [immutable tags](./immutable-tags.md), only mutable tags will appear in the deletion interface.

Found by nightly documentation quality scanner

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions