oras repo tags table output with option to sort by tag creation date

[tommyjcarpenter]

This was moved here by request: #1547 (comment)

What is the version of your ORAS CLI

1.2.3+Homebrew

What would you like to be added?

I'd like an option for oras repo tags to output a table, and more importantly a flag to sort by tag push date. E.g. something like

oras repo tags --sort-by time --order desc --N 100

to give me the last 100 tags (by creation date) sorted by the most recently created tag.

Why is this needed for ORAS?

We have repos with thousands of tags, and we often want to get "the latest" where latest isn't alphabetical, but by push date.

Even piping to less currently is not of much help, because the "latest" tag could be a hash smack in the middle of the alphabetical sorting - Ie oras repo tags | less doesnt help if the last tag pushed has hash 5000 out of 1...100000 etc.

Are you willing to submit PRs to contribute to this feature?

• Yes, I am willing to implement it.

[FeynmanZhou]

This sounds like a valid feature request to me.

@oras-project/oras-cli I am wondering if we are able to get the creation time of each tag?

[Wwwsylvia]

This feature is technically possible but a bit tricky. Basically, it requires the registry to return creation time information along with the tag list.

The standard tag listing API defined in the distribution spec does not include tag creation time, updated time, etc. However, some registries provide non-standard APIs that include this metadata.

For example, the standard tag listing API endpoint for Docker Hub is: https: //registry-1.docker.io/v2/library/hello-world/tags/list, and the response is simply:

{
    "name": "library/hello-world",
    "tags": [
        "latest",
        "linux",
        "nanoserver",
        "nanoserver-1709",
        "nanoserver-1803",
        "nanoserver-1809",
        "nanoserver-ltsc2022",
        "nanoserver-ltsc2025",
        "nanoserver-sac2016",
        "nanoserver1709"
    ]
}

A different Docker Hub API endpoint https://hub.docker.com/v2/repositories/library/hello-world/tags returns more detailed information:

{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [
        {
            "creator": 7,
            "id": 24937,
            "images": [...<omitted>
            ],
            "last_updated": "2025-05-30T22:41:11.483176Z",
            "last_updater": 1156886,
            "last_updater_username": "doijanky",
            "name": "latest",
            "repository": 31760,
            "full_size": 2436,
            "v2": true,
            "tag_status": "active",
            "tag_last_pulled": "2025-06-04T14:15:11.546998682Z",
            "tag_last_pushed": "2025-05-30T22:41:11.483176Z",
            "media_type": "application/vnd.oci.image.index.v1+json",
            "content_type": "image",
            "digest": "sha256:0b6a027b5cf322f09f6706c754e086a232ec1ddba835c8a15c6cb74ef0d43c29"
        },
    ...<omitted>
    ]
}

As far as I know, Azure Container Registry (ACR) also provides a non-standard API that returns additional metadata for tag listing.

Just brainstorming - @shizhMSFT once suggested introducing a flag (perhaps --vendor-optmized) to access vendor-specific APIs.

We could start by displaying the raw JSON output from the registry and then consider supporting sorting.

This would require contributors to add supports for different registries.

The UX could be something like:

$ oras repo tags docker.io/library/hello-world --vendor-optimized --format json

{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [
        {
            "creator": 7,
            "id": 24937,
            "images": [...<omitted>],
            "last_updated": "2025-05-30T22:41:11.483176Z",
            "last_updater": 1156886,
            "last_updater_username": "doijanky",
            "name": "latest",
            "repository": 31760,
            "full_size": 2436,
            "v2": true,
            "tag_status": "active",
            "tag_last_pulled": "2025-06-04T14:15:11.546998682Z",
            "tag_last_pushed": "2025-05-30T22:41:11.483176Z",
            "media_type": "application/vnd.oci.image.index.v1+json",
            "content_type": "image",
            "digest": "sha256:0b6a027b5cf322f09f6706c754e086a232ec1ddba835c8a15c6cb74ef0d43c29"
        },
    ...<omitted>
    ]
}

[FeynmanZhou]

@Wwwsylvia Thanks for calling out the limitation of the OCI tag listing API.

This raises the question: should ORAS support vendor-specific APIs to enable such functionality? or should we propose this feature request to the upstream OCI tag listing API?

As a CNCF project, ORAS is expected to remain vendor-neutral while supporting a wide range of OCI registries. The challenge is to handl the complexity of integrating multiple vendor-specific APIs and ensuring their long-term maintenance within ORAS.

@oras-project/oras-owners @oras-project/oras-cli I would appreciate if more maintainers could help share their opinions on this question.

[tommyjcarpenter]

When I created this ticket, I did not know that this type of metadata wasn't in the "official" spec and was only supplied as an extension by various vendors. As such, I'm OK if this gets closed without support. That said, depending on the tagging scheme used, this is still a problem, but perhaps one not best solved here.

I've seen a lot of tagging schemes where the git commit hash that led to the image is part of the tag. Maybe this issue is a great argument against using any sort of prefix that isn't "naturally sorted by creation time", such as hash-date or hash-version. The first part of the tagging scheme should always be naturally sorted, like semver-hash or date-hash etc. However we do not always have control over the tagging schemes other teams/companies use.

[Wwwsylvia]

Related PR on distribution-spec: opencontainers/distribution-spec#579