GRM-172: docs: document pre-pull image usage guidelines

Co-authored-by: emo <emo@oblachno.com>

ansible/roles/gitea_runner/tasks/pre_pull_images.yml

@@ -8,6 +8,15 @@
 #
 # Set gitea_runner_pre_pull_images to a list of image refs to pull, or
 # empty list to skip pre-pulling.
+#
+# IMPORTANT: Do NOT use this mechanism for:
+#   - CI runner container images (e.g. ci-full) — these are already
+#     cached by the runner setup task and pulling them here is redundant.
+#   - Images that molecule tests pull themselves — molecule prepare/converge
+#     steps handle their own image pulls; pre-pulling them here wastes time
+#     and disk space.
+# This mechanism is intended only for images that are needed by the runner
+# itself but not pulled by any molecule scenario or runner setup step.
 
 - name: Pre-pull Docker images for CI runner
   ansible.builtin.command: "docker pull {{ item }}"

docs/specs/GRM-172.md

@@ -0,0 +1,38 @@
+# GRM-172: Audit and document pre-pull image usage guidelines
+
+## Problem
+The grm repo contains a runner-level `pre_pull_images.yml` task file that
+pre-pulls Docker images to avoid repeated pulls on every CI run. However,
+there was no audit confirming that molecule `prepare.yml` files are not
+also redundantly pre-pulling images that the runner setup already caches.
+Wasteful pre-pulling wastes CI time and disk space.
+
+## Approach
+Audit all molecule `prepare.yml` files in the grm repo for pre-pull tasks.
+The audit found NO molecule prepare.yml files contain pre-pull tasks, so no
+code removal is needed. Document the audit findings in a spec and add a
+comment to the runner-level `pre_pull_images.yml` task file clarifying that
+it should not be used for images that molecule tests pull themselves (to
+avoid redundant pulls).
+
+REQ-1: Audit all molecule prepare.yml files for pre-pull tasks and confirm none exist
+REQ-2: Add documentation comment to pre_pull_images.yml stating it should not be used for CI runner container images (already cached by runner setup) or images molecule tests pull themselves
+REQ-3: Confirm gitea_runner_pre_pull_images default remains empty ([]) which is correct
+
+## Test Plan
+- Grep all molecule prepare.yml files for pre-pull patterns confirms zero matches
+- Verify pre_pull_images.yml comment is present and accurate
+- Verify gitea_runner_pre_pull_images default is [] in defaults/main.yml
+- Run make lint-ci to confirm no lint regressions
+
+## Deploy Plan
+- Merge to master via auto-merge workflow
+- No runtime changes; documentation-only
+
+## Rollback Plan
+- Revert the merge commit; comments are removed, no functional impact
+
+## Acceptance Criteria
+- [x] REQ-1: No molecule prepare.yml files in the grm repo contain pre-pull tasks (audit confirmed via grep)
+- [x] REQ-2: pre_pull_images.yml contains a comment documenting it should not be used for CI runner container images or images molecule tests pull themselves
+- [x] REQ-3: gitea_runner_pre_pull_images default remains empty ([]) in defaults/main.yml