feat(xpkg): add --annotation flag to xpkg build and xpkg push

[chaitanyapantheor]

Description of your changes

Adds a repeatable --annotation/-a KEY=VALUE flag to crossplane xpkg build
and crossplane xpkg push, allowing users to attach OCI manifest annotations
to packages at build or push time.

# Build with a static annotation
crossplane xpkg build -a org.opencontainers.image.source=https://github.com/org/repo

# Push with a dynamic (CI-injected) annotation
crossplane xpkg push -f pkg.xpkg \
  -a org.opencontainers.image.revision=$(git rev-parse HEAD) \
  xpkg.example.io/org/pkg:v1.0.0

Annotations are applied to the OCI image manifest. Malformed annotations
(missing =) return an error before any write or push occurs. Reading
annotations from crossplane.yaml is intentionally out of scope to avoid
silently propagating internal Crossplane annotations to the OCI registry.

Covered by unit tests in cmd/crossplane/xpkg/annotations_test.go.

Fixes crossplane/crossplane#7282

I have:

• Read and followed Crossplane's [contribution process].
• Run ./nix.sh flake check to ensure this PR is ready for review.
• Added or updated unit tests.
• Linked a PR or a [docs tracking issue] to [document this change].
• Added backport release-x.y labels to auto-backport this PR.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1a052aa1-a7f0-4123-b980-78e64fe35972

📥 Commits

Reviewing files that changed from the base of the PR and between 6e3542b and 4476efa.

📒 Files selected for processing (5)

• cmd/crossplane/xpkg/annotations.go
• cmd/crossplane/xpkg/annotations_test.go
• cmd/crossplane/xpkg/batch.go
• cmd/crossplane/xpkg/build.go
• cmd/crossplane/xpkg/push.go

---

📝 Walkthrough

Walkthrough

This PR adds support for setting OCI image annotations via --annotation/-a CLI flags on both crossplane xpkg build and crossplane xpkg push commands. Users supply annotations as key=value pairs, which are parsed, validated, and applied to the OCI image manifest before the image is finalized or pushed.

Changes

OCI Annotation CLI Support

Layer / File(s)	Summary
Annotation parsing and image application helpers cmd/crossplane/xpkg/annotations.go, cmd/crossplane/xpkg/annotations_test.go	Introduces parseAnnotations to convert repeatable key=value CLI arguments into a map with error handling for malformed entries, and annotateImage to apply annotations to OCI manifests. Test suite covers empty inputs, single/multiple entries, values containing =, and missing delimiters.
Build command annotation support cmd/crossplane/xpkg/build.go	Adds --annotation/-a repeatable flag to buildCmd, parses annotations during Run(), handles parse errors with errParseAnnotations, and applies annotations to the built image before digest computation and packaging.
Push command annotation support cmd/crossplane/xpkg/push.go	Adds --annotation/-a repeatable flag to pushCmd, parses annotations and passes them to pushImages. Updates pushImages signature to accept the annotations map and applies annotations to images in both single-package and concurrent multi-package push paths.
Batch retry wiring cmd/crossplane/xpkg/batch.go	Updates the retry loop's pushImages invocation to pass nil for the new annotations parameter.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• crossplane/crossplane#7282: This PR directly implements the requested feature to add OCI annotation support via --annotation/-a flags on crossplane xpkg build and crossplane xpkg push commands, allowing external tooling like Kargo to access custom image metadata.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly and concisely describes the main change: adding --annotation flag support to xpkg build and push commands.
Description check	✅ Passed	Description provides clear context about the feature, usage examples, implementation scope, and references the linked issue #7282.
Linked Issues check	✅ Passed	Changes fully implement the primary objective from issue #7282: adding repeatable --annotation/-a flags to xpkg build and push for OCI manifest annotations [#7282].
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the stated objectives: annotation flag implementation, parsing logic, and supporting infrastructure for both build and push commands.
Breaking Changes	✅ Passed	No exported public APIs are modified. Optional Annotation flags added to private buildCmd/pushCmd types. Private pushImages function signature change is internal and coordinated.
Feature Gate Requirement	✅ Passed	PR adds optional CLI annotation flags with no apis/** changes, not marked experimental, and doesn't significantly affect behavior. Feature gate requirement does not apply.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}