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: 8bba7570-7512-4063-91ba-83aeec134594

📥 Commits

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

📒 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

🚧 Files skipped from review as they are similar to previous changes (5)

• cmd/crossplane/xpkg/batch.go
• cmd/crossplane/xpkg/annotations.go
• cmd/crossplane/xpkg/annotations_test.go
• cmd/crossplane/xpkg/push.go
• cmd/crossplane/xpkg/build.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

• Setting OCI Annotations on artifacts produced from crossplane xkpg build/push commands crossplane#7282: Implements the requested feature to add OCI annotation support via --annotation/-a flags on crossplane xpkg build and crossplane xpkg push, exposing custom image metadata on the image manifest.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding an --annotation flag to xpkg build and push commands, meeting the 72-character requirement.
Description check	✅ Passed	The description is comprehensive, providing context, usage examples, scope boundaries, and test coverage, all directly related to the changeset.
Linked Issues check	✅ Passed	The PR implements the primary objective from #7282 by adding a repeatable --annotation/-a flag to both xpkg build and xpkg push commands, enabling users to attach OCI annotations.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the --annotation flag feature; no extraneous modifications to unrelated functionality are present.
Breaking Changes	✅ Passed	All changes are to unexported types and functions in cmd/crossplane/xpkg. No exported public APIs were removed, renamed, or have required fields added. No breaking changes detected.
Feature Gate Requirement	✅ Passed	PR adds --annotation CLI flag to xpkg build/push. No apis/** changes, not experimental, purely additive. Feature gate requirement doesn't 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.}