ci(docker): publish a sortable main-<commit UTC>-<sha7> relay tag

[TheSentinel454]

Summary

Each push to main adds one more tag to the relay image manifest that docker.yml already publishes:

• :main-<YYYYMMDDHHmmss>-<sha7> (UTC commit time)
• :debug-main-<YYYYMMDDHHmmss>-<sha7> on the debug manifest

:main, :sha-<7>, and the release tags don't change.

Why: :sha-<7> has no ordering, so a deploy tool that wants "the newest main build" has to fetch metadata for every tag before it can sort. Our staging promotion warehouse (Kargo, NewestBuild) does that on every discovery cycle, against about 1,700 sha-* tags (4,800 total) in ghcr.io/block/buzz. That's slow, it hits registry rate limits, and one failed fetch aborts the whole cycle. The timestamp prefix makes the tag sort lexically in build order. A Lexical selector with ^main-\d{14}-[0-9a-f]{7}$ can then pick the newest build from the tag list alone and fetch only the tags it keeps.

Details, checked against the pinned docker/metadata-action v6.1.0 (80c7e94d):

• {{sha}} is the 7-char short sha (defaultShortShaLength = 7), the same value as :sha-<7>.
• {{commit_date}} formats in UTC by default. On a push it uses the event's commits[].timestamp, so rerunning a commit produces the same tag.
• type=raw inherits the flavor prefix, so the merge job's debug leg emits debug-main-…. That's the same mechanism that produces debug-main today.
• enable= limits the tag to push on refs/heads/main. Release tags, rescue dispatches, and PRs never get it.

On main's last 40 commits, author time and committer time are the same instant, and both increase monotonically. A commit pushed with a backdated timestamp would sort below newer builds and just wouldn't be auto-picked; the next push supersedes it.

What got simpler: this adds one tag line in each of the two places that already mirror the tag matrix, plus header docs. In return, downstream tooling no longer needs per-tag metadata fetches to find the newest build.

Related issue

N/A (staging rollout tooling). The downstream warehouse and tag-guard changes land separately and don't switch over until this tag has been published.

Testing

• scripts/test-relay-image-eligibility-workflow.sh and scripts/test-release-ref-contract.sh pass at 9ba1d8b7f.
• PR runs don't push images (push: false), so the first real tag appears on the first main push after merge. I'll check the registry for main-<14 digits>-<sha7> and debug-main-… on that manifest.

[github-actions]

🔐 Codex Security Review

Note: This is an automated, security-focused review generated by Codex.
Use it as a supplement to human review; false positives are possible.

Scope

• Exact PR diff: 30873ba46b5e08602ae61a2a0592ecedd37f7289...a89210a4ec63a31fba8ae2b9b7ad1070723253fe
• Model: gpt-6.1-sol

💡 Click "edited" above to see earlier reviews for this PR.

---

Review Summary

Overall Risk: NONE

No concrete security, correctness, or reliability findings in the authorized PR range. The new image tags preserve the existing publication and CI qualification gates.

Findings

No concrete security, correctness, or reliability findings were identified.

Notes

• Review was limited to read-only inspection. Workflows and tests were not executed, and external Kargo configuration was unavailable.

---

_{Generated by Codex Security Review |
Requested by: @TheSentinel454 |
Workflow run}

[wpfleger96]

🤖 Thanks for this. Checked against the pinned docker/metadata-action v6.1.0 source:

• type=raw values go through the same handlebars pass as everything else, so {{commit_date}} and {{sha}} resolve. commit_date defaults to tz=UTC, and {{sha}} is the 7-char short sha, same as :sha-<7>.
• On a push, the commit date comes from the event payload (commits[].timestamp / head_commit), so reruns re-push the same tag.
• The merge job's prefix=${{ matrix.tag_prefix }} flavor yields debug-main-…, and the anchored ^main- regex excludes it.
• The last 300 commits on main have author time equal to committer time, and both increase monotonically. Lexical order matches build order.

Nit, optional: the README edit leaves one long line inside an otherwise wrapped paragraph. It renders the same either way.