Support layer-level annotations via --annotation flag in oras push

[jmorla]

What is the version of your ORAS CLI

1.3.0

What would you like to be added?

Extend --annotation to support an optional file prefix that binds the annotation to a specific layer descriptor, using a clearly documented syntax. For example:

# manifest-level (existing behavior)
--annotation "key=value"

# layer-level (proposed)
--annotation "filename.ex5:key=value"

Why is this needed for ORAS?

The --annotation flag only supports manifest-level annotations:

Flags:
  -a, --annotation stringArray                               manifest annotations

There is no inline CLI syntax to bind an annotation to a specific layer. The official docs show only this usage for manifest annotations:

oras push --annotation "key=val" localhost:5000/hello:v1

Layer-level annotations are exclusively supported via --annotation-file, which requires generating a temporary JSON file

Problem

In scripting and CI/CD scenarios where layer annotations need to be set dynamically per file, users are forced to generate, manage, and clean up temporary annotation files — just to bind a single annotation to a layer. This is cumbersome and error-prone, especially in batch push loops.
Additionally, the lack of a CLI-native syntax invites users to attempt --annotation ":=" intuitively, which silently produces incorrect results: instead of binding to the layer it dumps a literal key : into the manifest annotations, making it very hard to diagnose.

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

• Yes, I am willing to implement it.

[TerryHowe]

Feasibility Analysis

The internal data model already fully supports this — Annotations is map[string]map[string]string where the outer key can be "$manifest", "$config", or a file path. Only the parsing step in annotation.go is hardcoded to always route to "$manifest". The core change is ~30 lines in one function.

Parsing approach

The proposed : separator works cleanly if applied to the key-side only (before the =):

filename:key=value
  → split on "=" first → key-side="filename:key", value="value"
  → split key-side on first ":" → target="filename", key="key"

This correctly handles values containing :// (e.g., URL values) without ambiguity. The change is fully backward compatible — --annotation "key=value" (no : in the key-side) still routes to $manifest exactly as before.

Affected files

• cmd/oras/internal/option/annotation.go — parsing logic (primary change)
• cmd/oras/internal/option/packer.go — mutual-exclusivity check, flag description
• cmd/oras/root/push.go, cmd/oras/root/attach.go — usage examples in help text
• cmd/oras/internal/option/packer_test.go — tests

loadFiles() in cmd/oras/root/file.go already reads from the file-keyed scope of Annotations with no changes needed.

Suggested implementation steps

1. Update Annotation.Parse() in annotation.go:48-67:

   • After strings.Cut(anno, "=") to get the key-side and value, check if the key-side contains :
   • If yes: strings.Cut(keySide, ":") → (target, key); validate target is non-empty
   • If no: target = AnnotationManifest (existing behavior)
   • Route the key=value pair into opts.Annotations[target]
   • Add duplicate-key check per target scope (currently only checks $manifest)

2. Update flag description in annotation.go:44 from "manifest annotations" to e.g. "manifest and layer annotations; use 'filename:key=value' to target a specific layer"

3. Keep mutual exclusivity between --annotation and --annotation-file for now — --annotation-file remains the option for complex multi-layer scenarios.

4. Add tests covering:

   • Layer annotation: "file.txt:key=val" → Annotations["file.txt"]["key"] = "val"
   • $config scope: "$config:key=val" → Annotations["$config"]["key"] = "val"
   • Duplicate key within same layer scope → error
   • Same key in different scopes → allowed
   • Empty target ":key=val" → error
   • URL value "file.txt:key=https://example.com" → parses correctly

Risk assessment

• Backward compatible — no existing behavior changes
• One edge case to document: file paths containing : (rare on Linux/Mac, problematic on Windows with drive letters like C:\); recommend --annotation-file for those cases
• Effort: Medium — small logic change, but needs careful edge-case handling, tests, and doc updates

[TerryHowe]

Seems reasonable to me, but like to know what other maintainers think.

[BRGOVIND]

Hi! I'd like to take a shot at this. The proposed syntax (filename:key=value) is intuitive and consistent with how annotation files work. My plan is to extend the annotation flag parser in cmd/ to detect the colon-prefix form and route those entries to the layer descriptor map rather than the manifest annotations map. I'll make sure the error message for the currently-silent wrong behavior is also improved. Would you accept a PR for this?