Skip to content

Update spec language to support pushing multiple tags at once #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jcarter3 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update spec language to support pushing multiple tags at once #600

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f271626
Update spec language to support issue #591, pushing multiple tags at …
jcarter3 Feb 24, 2026
99b8df6
Update spec.md
jcarter3 Feb 25, 2026
8fe2fe8
Update spec.md
jcarter3 Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,12 @@ The `<location>` is a pullable manifest URL.
The Docker-Content-Digest header returns the canonical digest of the uploaded blob, and MUST be equal to the client provided digest.
Clients MAY ignore the value but if it is used, the client SHOULD verify the value against the uploaded blob data.

When pushing a manifest by digest, the registry MAY support the pushing of tags specified by addition of `tag` query parameters.
If a registry supports this, it MUST:

1. Not limit the number of tags that can be pushed at once.
Copy link
Contributor

@sudo-bmitch sudo-bmitch Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My personal preference is to allow a registry to respond with an error if a limit is exceeded and have the spec identify a minimum that registries are expected to support, similar to how large manifests are handled.

Copy link
Author

@jcarter3 jcarter3 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue I see here is that if a client passes 100, but the registry only supports 25, then the client has no way of knowing if the other 75 failed for error, or if there was a limit. We could set this as something reasonably high enough (100?) so that it would rarely happen in practice. Or also add an OCI-Tag-Limit response header to indicate the max so that the client could intelligently batch. But the thinking here is that this can make both the registry and the client much more efficient with validations and network calls, so as long as it's a valid URL length, it should work.

Copy link
Contributor

@sudo-bmitch sudo-bmitch Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so as long as it's a valid URL length

What's an invalid URL length?

Copy link
Author

@jcarter3 jcarter3 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems a bit tricky to nail down as it's all over the place. Browsers seem to support a lot, like in the 65,000-100,000 character range. (>500 tags at max tag length). Some security recommendations say to limit it to 1k-2k on webservers to prevent some kinds of attacks, which is more like a max of 10 tags at a time at max tag length.

Maybe it should be updated to say it MUST support a minimum of 10, SHOULD not set an upper limit.

Copy link
Contributor

@sudo-bmitch sudo-bmitch Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'm not finding a limit in the http RFCs. In Go, the limit defaults to 1MB for net/http Server.MaxHeaderBytes which includes all headers and the request, but that is configurable. I'd say registries SHOULD support at least 10 tags per request. If a registry rejects the request for exceeding a tag limit, it MUST return a 414 Request-URI Too Long, and clients MAY retry with fewer tags.

If they hit the Go limit, that throws a 431 Request Header Fields Too Large, which we should document as another possible error.

I hesitate to respond with an OCI-Tag-Limit header because the 414/431 could be from different causes, including a proxy or the internal Go http server, and it may be from other headers, the overall URI length, or a fixed limit on the number of tags enforced by the registry implementation.

In practice, I think most users would rarely exceed 5 tags per manifest (3 tags for semver + a fixed/latest tag or two), so I don't think a failure or split+retry is going to impact folks doing normal things.

1. For each tag that was successfully pushed, include an `OCI-Tag` response header in accordance with [RFC 2616 (section 4.2)](https://datatracker.ietf.org/doc/html/rfc2616#section-4.2) semantics.

An attempt to pull a nonexistent repository MUST return response code `404 Not Found`.

A registry SHOULD enforce some limit on the maximum manifest size that it can accept.
Expand Down
Loading