option: support layer-level annotations via --annotation flag by BRGOVIND · Pull Request #2083 · oras-project/oras

BRGOVIND · 2026-06-14T23:48:03Z

Closes #2031 — extends --annotation to accept layer-level annotations directly, without needing a temporary --annotation-file.

Problem

oras push --annotation currently only supports manifest-level annotations.
To set layer-level annotations users must create a temporary JSON file and pass it with --annotation-file:

{
  "": {"org.opencontainers.image.title": "demo"},
  "myfile.tar": {"com.example.layer": "data"}
}

This is cumbersome in CI/CD pipelines and scripting.

Solution

Extend the --annotation flag to accept an optional file prefix:

Syntax	Effect
`--annotation "key=value"`	Manifest-level (existing behavior, unchanged)
`--annotation "filename.tar:key=value"`	Layer-level, bound to that filename

When the key part (before =) contains a colon, everything before the colon is treated as the file reference and everything after as the annotation key. OCI annotation keys use reverse-DNS with dots (not colons), so :) is safe as a separator.

Duplicate key detection is applied per target (manifest or per-file). The resulting Annotations map mirrors the --annotation-file JSON format exactly, so no changes are needed downstream in the push path.

Example

oras push localhost:5000/demo \
  --annotation "org.opencontainers.image.title=demo" \
  --annotation "myfile.tar:com.example.layer=data"

oras push --annotation currently only supports manifest-level annotations. Users who need layer-level annotations must generate a temporary JSON file and pass it with --annotation-file, which is cumbersome in CI/CD pipelines. This change extends the --annotation flag to accept an optional file prefix: --annotation "key=value" (existing behavior, manifest-level) --annotation "filename.tar:key=value" (new, layer-level bound to filename) When a colon appears in the key part (before the first =), everything before the colon is treated as the file reference and everything after as the annotation key. Duplicate key detection is applied per-target. The resulting Annotations map mirrors the annotation-file JSON format, so no downstream changes are needed in the push path. Closes oras-project#2031 Signed-off-by: B R GOVIND <brgovind2005@gmail.com>

TerryHowe

Seems reasonable to me although I'm curious what other maintainers think.

It will need some tests though unit and ideally an e2e

Cover manifest-level, layer-level, mixed, duplicate key errors, missing '=' format error, empty key after file prefix, and values containing '=' characters. Signed-off-by: B R GOVIND <brgovind2005@gmail.com>

BRGOVIND · 2026-06-19T10:26:19Z

Thanks for the review @TerryHowe! I've pushed unit tests for the layer-level annotation parsing (cmd/oras/internal/option/annotation_test.go) covering manifest-level, layer-level, mixed, multiple annotations per layer, empty input, values containing =, format errors, and duplicate-key cases.

Happy to add an e2e case as well — since you mentioned wanting other maintainers' input on the approach, I held off on the heavier e2e suite until the design direction is confirmed. Just let me know and I'll add it. Re-requesting review when you get a chance.

TerryHowe

Good base here, as well as the other comments, can you update the push and attach help text for this? Thanks!

Address review feedback on layer-level --annotation support: - Reject an empty target before the colon (e.g. ":key=value") so the intent is explicit, with guidance to use "key=value" or "target:key=value". - Treat the colon prefix as a generic target, allowing the special "$config" and "$manifest" scopes in addition to filenames. This also fixes a bug where "$manifest:key=value" overwrote bare "key=value" manifest annotations instead of merging, and now applies duplicate-key detection across both forms. - Validate that every layer (file) annotation target refers to a file in the command, so typos surface as an error instead of being silently dropped by loadFiles. Validation runs only for the --annotation flag path, which is mutually exclusive with --annotation-file, so existing annotation-file behavior is unchanged. - Update the --annotation flag help and add push/attach examples covering layer and config annotations. Extend unit tests for empty-target errors, the $config/$manifest targets, cross-form manifest duplicates, and file-target validation. Signed-off-by: B R GOVIND <brgovind2005@gmail.com>

TerryHowe

Thanks, few more things

TerryHowe · 2026-06-27T11:41:21Z

+//
+// Accepted formats:
+//   - "key=value"           → manifest-level annotation
+//   - "target:key=value"    → annotation scoped to an explicit target:


This feature would technically be a breaking change for keys that had a : in them previously it should be noted.

This breaking change here is still an issue

Any innovative ways to get around the breaking nature of this change?

github-actions · 2026-08-12T02:15:12Z

This PR is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 30 days.

jmorla · 2026-08-14T13:48:57Z

Hi @BRGOVIND,
If you're busy or stuck on any part of this, I'd be happy to help out or push a commit directly to get this ready for review. Just let me know how I can best support you!

BRGOVIND · 2026-08-14T17:34:37Z

Hi @BRGOVIND, If you're busy or stuck on any part of this, I'd be happy to help out or push a commit directly to get this ready for review. Just let me know how I can best support you!

that'd be great
I'm in the middle of my exams 😭

Signed-off-by: Jorge Morla <jorgemorlapro@gmail.com>

jmorla · 2026-08-17T19:32:47Z

@BRGOVIND I created this Pull Request which is pointing to your PR to resolve @TerryHowe's comments. please let me know what you think

test(e2e): cover targeted annotations for push and attach

BRGOVIND · 2026-08-17T19:41:25Z

@BRGOVIND I created this Pull Request which is pointing to your PR to resolve @TerryHowe's comments. please let me know what you think

Awesome, thanks Morla! I’ve merged the PR into my branch. appreciate you jumping in and handling the push updates and E2E coverage

TerryHowe · 2026-08-21T13:24:01Z

+// It only runs for the `--annotation` flag path; the `--annotation-file` path
+// is mutually exclusive with it (see parseAnnotations) and is left untouched
+// to preserve backward compatibility.
+func (opts *Packer) validateAnnotationTargets() error {


This validate method, doesn't it seem like it is a natural fit in annotation.go maybe called in Parse?

Good point.
I considered moving this into annotation.go/Parse, but this validation is specifically concerned with whether the parsed target is valid for the packer’s current context, rather than parsing the annotation syntax itself. Keeping it here also leaves the existing ones behavior unchanged for backward compatibility. I’m happy to move it if you think that separation would be clearer.

TerryHowe · 2026-08-21T13:25:09Z

+//
+// Accepted formats:
+//   - "key=value"           → manifest-level annotation
+//   - "target:key=value"    → annotation scoped to an explicit target:


Any innovative ways to get around the breaking nature of this change?

BRGOVIND requested review from TerryHowe, Wwwsylvia, sabre1041, sajayantony and shizhMSFT as code owners June 14, 2026 23:48

TerryHowe requested changes Jun 17, 2026

View reviewed changes

test(option): add unit tests for annotation flag layer-level support

bcaf246

Cover manifest-level, layer-level, mixed, duplicate key errors, missing '=' format error, empty key after file prefix, and values containing '=' characters. Signed-off-by: B R GOVIND <brgovind2005@gmail.com>

TerryHowe requested changes Jun 26, 2026

View reviewed changes

Comment thread cmd/oras/internal/option/annotation.go Outdated

Comment thread cmd/oras/internal/option/annotation.go Outdated

Comment thread cmd/oras/internal/option/annotation_test.go

TerryHowe requested changes Jun 27, 2026

View reviewed changes

github-actions Bot added the stale Inactive issues or pull requests label Aug 12, 2026

test(e2e): cover targeted annotations for push and attach

8779b3e

Signed-off-by: Jorge Morla <jorgemorlapro@gmail.com>

github-actions Bot removed the stale Inactive issues or pull requests label Aug 15, 2026

Merge pull request #2 from jmorla/pr-2083-help-e2e

9595bdd

test(e2e): cover targeted annotations for push and attach

TerryHowe reviewed Aug 27, 2026

View reviewed changes

Uh oh!

Conversation

BRGOVIND commented Jun 14, 2026

Problem

Solution

Example

Uh oh!

TerryHowe left a comment

Choose a reason for hiding this comment

Uh oh!

BRGOVIND commented Jun 19, 2026

Uh oh!

TerryHowe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TerryHowe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

TerryHowe Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

TerryHowe Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

TerryHowe Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Aug 12, 2026

Uh oh!

jmorla commented Aug 14, 2026

Uh oh!

BRGOVIND commented Aug 14, 2026

Uh oh!

jmorla commented Aug 17, 2026

Uh oh!

BRGOVIND commented Aug 17, 2026

Uh oh!

TerryHowe Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

BRGOVIND Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

TerryHowe Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants