feat: Universal OCI Tagging Engine for Flexible Image Naming (#746)

[nklowns]

feat: Universal OCI Tagging Engine for Flexible Image Naming

Summary of Technical Impact

This PR introduces a Universal OCI Tagging Engine, a centralized policy-driven system that decouples image tagging logic from individual CI/CD drivers (GitHub, GitLab, Local). It enables non-opinionated, data-driven OCI reference generation directly from the recipe.yml.

Motivation

Currently, BlueBuild drivers implement fixed, opinionated tagging patterns (e.g., automatically appending branch names or OS versions to alt-tags). While convenient for many, this creates significant friction for projects requiring strict OCI naming standards—such as Bazzite or standardized Linux distributions.

Previously, users had to resort to external yq patching or complex shell scripting in their CI pipelines to achieve specific tag formats like stable-41.20241021. This engine eliminates that need by making tagging a first-class feature of the recipe.

Technical Implementation

• Policy Engine: A new module in blue-build-utils that uses regex-based matching to apply custom expansion rules to alt-tags.
• Placeholder Resolution: Supports a rich set of placeholders:
  • {tag}: The original tag being expanded.
  • {os_version}: Extracted from the base image or build metadata.
  • {timestamp}: The build's ISO-style timestamp.
  • {short_sha}: The Git commit hash (where available).
• Schema Updates: Added tags (verbatim tags) and tagging (policy-based expansion) to the Recipe struct.
• Robustness: Enhanced regex evaluation with explicit miette error reporting to provide actionable feedback for invalid patterns.
• Backward Compatibility: Maintains the legacy uBlue tagging logic as a Phase 3 fallback if no policies are defined.

Examples

1. Bazzite-style Versioned Tagging

Expand the stable tag to include the OS version and timestamp:

alt-tags: [stable]
tagging:
  - match: stable
    tags:
      - "{tag}"
      - "{tag}-{os_version}"
      - "{tag}-{os_version}.{timestamp}"

2. Static Tagging

Sometimes you just want an exact list of tags without any logic:

tags:
  - latest
  - stable
  - "41"

Verification Results

• Unit Tests: Comprehensive coverage in utils/src/tagging.rs for placeholder resolution and regex matching.
• Driver Integration: Verified across GitHub, GitLab, and Local driver test suites.
• Safety: Confirmed that invalid regexes provide descriptive errors rather than silent failures.

Closes #746

---

Assisted-by: Antigravity via Claude-3.5-Sonnet

[gmpinder]

Before I even start to review this, I see you used an AI agent to make the changes. I need to see in your own words what this change is doing and that you have gone through the changes yourself and tested it locally. I'm not going to waste my time going back and forth with a bot on fixing up this PR.

[nklowns]

@gmpinder Hello, first of all, thank you for your response. As a hobby, I’m exploring how to use Blue-Build to generate the Bazzite DX image as a declarative mechanism to simplify the maintenance process. Even though I used AI to help me get started, I’ll still test this PR locally.
Regarding the motivation, I noticed that the tags are based on timestamp and short_sha, and they come out in a format quite different from the initial template I used: https://github.com/ublue-os/image-template
The goal is to make it possible to generate more customized or standardized tags.

[gmpinder]

The goal is to make it possible to generate more customized or standardized tags.

I think the idea for this feature is really good, but let's try to discuss how to implement it in the issue first. Because the current implementation, I already see several changes that break existing functionality.