From cbd0462f423f7ee0a0460c6117097803eb25ae69 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Tue, 18 Aug 2026 18:42:31 +0000
Subject: [PATCH] docs(#3502): add UBI base image bump guidance to AGENTS.md

Document the UBI base image update workflow and multi-branch
strategy so the review agent understands that release-v*
branches intentionally update only production Dockerfiles.

Add a new "UBI Base Image Updates" section covering:
- The three coordinated Dockerfiles and the bump script
- Multi-branch strategy: main updates all three files,
  release branches may update only production files
- Review guidance: do not flag missing acceptance.Dockerfile
  updates on release branches as stale references

Note: pre-commit could not run (sandbox network restriction
blocked git fetch for hook environment setup). Manual
verification of pre-commit hooks is required.

Closes #3502
---
 AGENTS.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1d1cbbd6a..3a1f91213 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,6 +74,29 @@ Read these before modifying the corresponding areas:
 - [internal/validate/vsa/DESIGN.md](internal/validate/vsa/DESIGN.md) — VSA: storage backends, DSSE signing rationale, expiration model
 - [acceptance/README.md](acceptance/README.md) — acceptance test framework, Testcontainers, WireMock, snapshot testing
 
+## UBI Base Image Updates
+
+The project pins UBI9 ubi-minimal base image digests in three Dockerfiles:
+- `Dockerfile` (production)
+- `Dockerfile.dist` (distribution)
+- `acceptance/kubernetes/kind/acceptance.Dockerfile` (acceptance tests)
+
+The script `hack/ubi-base-image-bump.sh` updates all three files and regenerates `rpms.lock.yaml`
+via `hack/update-rpm-lock.sh`.
+
+### Multi-branch strategy
+
+On `main`, all three Dockerfiles are updated together. On `release-v*` branches, bump PRs may
+intentionally update only production Dockerfiles (`Dockerfile`, `Dockerfile.dist`) since acceptance
+test infrastructure is typically not backported to release branches. A narrower scope on release
+branches is expected, not a bug.
+
+### Review guidance
+
+When reviewing UBI bump PRs on `release-v*` branches, do not flag missing updates to
+`acceptance/kubernetes/kind/acceptance.Dockerfile` as stale references. The coordinated update set
+defined in `hack/ubi-base-image-bump.sh` applies to `main` branch bumps only.
+
 ## Troubleshooting
 
 System-level issues that surface in acceptance tests: