Add cleanup_repos to revert build_only overrides

Repos marked build_only: true are backed up before handle_repos()
overwrites them and restored at the end of each image build, so CI
mirror URLs are not baked into the final image.

The cleanup RUN was injected into every Dockerfile, not just images
that called handle_repos() for those repos. Child images with no
backup fell through to "rm -f", deleting the inherited repo file
(e.g. debian.sources in bifrost-base, breaking cpio install).

Fix by adding a {repo}.enabled sentinel that handle_repos creates
when it processes a build_only repo, making the cleanup conditional
on that sentinel.

Change-Id: Ie5b9970a4575b6258dc238059d3f33ddfe155789
Signed-off-by: Michal Nasiadka <mnasiadka@gmail.com>

1 files changed, 46 insertions, 0 deletions

diff --git a/doc/source/admin/image-building.rst b/doc/source/admin/image-building.rst
index 3a40f5f6e..82ea693ec 100644
--- a/doc/source/admin/image-building.rst
+++ b/doc/source/admin/image-building.rst
@@ -783,6 +783,52 @@ Kolla validates this at build time and raises an error listing the missing
 overrides. For Rocky Linux this means overriding ``baseos`` or ``appstream``
 requires also overriding ``crb``.
 
+Build-time-only repositories
+""""""""""""""""""""""""""""
+
+Repositories that point to CI mirrors or other infrastructure-internal URLs
+should not be baked into the final image — they may be unreachable at runtime
+and would expose internal infrastructure details. Mark such repositories with
+``build_only: true`` to have kolla automatically restore or remove the
+repository file at the end of each image build.
+
+When ``build_only: true`` is set on a repository:
+
+* **Before** writing the mirror configuration, kolla backs up the existing
+  repository file (if any) to ``/tmp/kolla-repos-backup/``.
+* The repository file is written normally so all package installations in that
+  image can use the mirror.
+* **After** all package installations, kolla injects a cleanup step into every
+  rendered Dockerfile that restores the original file from the backup, or
+  removes the file entirely if no original existed.
+
+This means the repository files in the final image contain the upstream URLs
+(or are absent, leaving the distro defaults in place) rather than mirror URLs.
+
+Example — Debian with a CI mirror marked build-time-only:
+
+.. code-block:: yaml
+
+   debian:
+     debian:
+       build_only: true
+       component: "main"
+       gpg_key: "/usr/share/keyrings/debian-archive-keyring.gpg"
+       suite: "trixie trixie-updates trixie-backports"
+       url: "http://ci-mirror.internal/debian"
+     debian-security:
+       build_only: true
+       component: "main"
+       gpg_key: "/usr/share/keyrings/debian-archive-keyring.gpg"
+       suite: "trixie-security"
+       url: "http://ci-mirror.internal/debian-security"
+
+.. note::
+
+   ``build_only: true`` is only effective for non-distro repository entries
+   (those that write a ``.repo`` or ``.sources`` file). Repositories with
+   ``distro: True`` are a no-op in ``handle_repos()`` and require no cleanup.
+
 Red Hat
 ^^^^^^^