From 8b19fa53399cdeb18b1cdd41276ecac5a4f659b0 Mon Sep 17 00:00:00 2001
From: Bruce Ashfield <bruce.ashfield@gmail.com>
Date: Mon, 12 Jan 2026 20:15:39 +0000
Subject: image-oci: add build-time metadata labels for traceability

Automatically embed source and build information into OCI images using
standard OCI annotations (opencontainers.org image-spec):

- org.opencontainers.image.revision: git commit SHA
- org.opencontainers.image.ref.name: git branch name
- org.opencontainers.image.created: ISO 8601 build timestamp
- org.opencontainers.image.version: PV (if meaningful)

New variables:
- OCI_IMAGE_REVISION: explicit SHA override (auto-detects from TOPDIR)
- OCI_IMAGE_BRANCH: explicit branch override (auto-detects from TOPDIR)
- OCI_IMAGE_BUILD_DATE: explicit timestamp override (auto-generated)
- OCI_IMAGE_APP_RECIPE: hook for future cross-recipe extraction

Set any variable to "none" to disable that specific label.

This enables 1:1 traceability between container images and source code,
following industry best practices for CI/CD and release management.

Signed-off-by: Bruce Ashfield <bruce.ashfield@gmail.com>
---
 classes/image-oci.bbclass | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

(limited to 'classes/image-oci.bbclass')

diff --git a/classes/image-oci.bbclass b/classes/image-oci.bbclass
index 0ec5c487..70f32bf1 100644
--- a/classes/image-oci.bbclass
+++ b/classes/image-oci.bbclass
@@ -65,11 +65,53 @@ OCI_IMAGE_STOPSIGNAL ?= ""
 #     format: <port>/tcp, <port>/udp, or <port> (same as <port>/tcp).
 OCI_IMAGE_PORTS ?= ""
 
-# key=value list of labels
+# key=value list of labels (user-defined)
 OCI_IMAGE_LABELS ?= ""
 # key=value list of environment variables
 OCI_IMAGE_ENV_VARS ?= ""
 
+# =============================================================================
+# Build-time metadata for traceability
+# =============================================================================
+#
+# These variables embed source info into OCI image labels for traceability.
+# Standard OCI annotations are used: https://github.com/opencontainers/image-spec/blob/main/annotations.md
+#
+# OCI_IMAGE_APP_RECIPE: Recipe name for the "main application" in the container.
+#   If set, future versions may auto-extract SRCREV/branch from this recipe.
+#   For now, it's documentation and a hook point.
+#
+# OCI_IMAGE_REVISION: Git commit SHA (short or full).
+#   - If set: uses this value
+#   - If empty: auto-detects from TOPDIR git repo
+#   - Set to "none" to disable
+#
+# OCI_IMAGE_BRANCH: Git branch name.
+#   - If set: uses this value
+#   - If empty: auto-detects from TOPDIR git repo
+#   - Set to "none" to disable
+#
+# OCI_IMAGE_BUILD_DATE: ISO 8601 timestamp.
+#   - Auto-generated at build time
+#
+# These become standard OCI labels:
+#   org.opencontainers.image.revision = OCI_IMAGE_REVISION
+#   org.opencontainers.image.ref.name = OCI_IMAGE_BRANCH
+#   org.opencontainers.image.created = OCI_IMAGE_BUILD_DATE
+#   org.opencontainers.image.version = PV (if meaningful)
+
+# Application recipe for traceability (documentation/future use)
+OCI_IMAGE_APP_RECIPE ?= ""
+
+# Explicit overrides - if set, these are used instead of auto-detection
+# Set to "none" to disable a specific label
+OCI_IMAGE_REVISION ?= ""
+OCI_IMAGE_BRANCH ?= ""
+OCI_IMAGE_BUILD_DATE ?= ""
+
+# Enable/disable auto-detection of git metadata (set to "0" to disable)
+OCI_IMAGE_AUTO_LABELS ?= "1"
+
 # whether the oci image dir should be left as a directory, or
 # bundled into a tarball.
 OCI_IMAGE_TAR_OUTPUT ?= "true"
-- 
cgit v1.2.3-54-g00ecf