refactor: streamline kustomization build process for alpha overlays

- Replaced inline kustomization build script in the GitHub Actions workflow with a dedicated bash script for better maintainability.
- Updated documentation to clarify the use of a publish placeholder in kustomization files and the substitution of commit SHA during builds.
- Introduced a new script to handle the rendering of alpha overlays, improving the overall workflow and ensuring accurate builds with the correct references.

Author: mitchdowney

.github/workflows/metaboost-infra-alpha-contracts.yml

@@ -24,11 +24,6 @@ jobs:
           kustomize version
 
       - name: Render infra/k8s/alpha overlays
-        run: |
-          set -euo pipefail
-          for overlay in infra/k8s/alpha/*; do
-            if [ -d "$overlay" ] && [ -f "$overlay/kustomization.yaml" ]; then
-              echo "=== kustomize build $overlay ==="
-              kustomize build --load-restrictor LoadRestrictionsNone "$overlay" >/dev/null
-            fi
-          done
+        env:
+          KUSTOMIZE_REF: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: bash scripts/k8s/kustomize-build-metaboost-alpha-overlays.sh

infra/k8s/alpha/INFRA-K8S-ALPHA.md

@@ -8,5 +8,7 @@ This directory is the in-repo alpha app-of-apps source.
 
 `ops/kustomization.yaml` references remote `infra/k8s/base/ops?ref=...` (base ops ConfigMaps stay `metaboost-ops-*`).
 
+Committed overlay `kustomization.yaml` files use publish placeholder **`X.Y.Z-staging.N`** on remote `?ref=` URLs (and matching image tags where applicable). Replace that value with the immutable staging tag after **Publish (staging)**. PR CI (`.github/workflows/metaboost-infra-alpha-contracts.yml`) and [`scripts/k8s/kustomize-build-metaboost-alpha-overlays.sh`](../../scripts/k8s/kustomize-build-metaboost-alpha-overlays.sh) substitute the commit SHA when rendering so overlays validate before a publish tag exists.
+
 External GitOps repositories can still consume this model by syncing this repository revision and
 tracking the in-repo alpha root and child app manifests.

scripts/k8s/kustomize-build-metaboost-alpha-overlays.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Renders every infra/k8s/alpha/<component> overlay (no cluster apply).
+# Committed kustomizations pin remote bases with publish placeholder X.Y.Z-staging.N;
+# this script substitutes KUSTOMIZE_REF (commit SHA or staging tag) before kustomize build.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT"
+
+PUBLISH_REF_PLACEHOLDER='X.Y.Z-staging.N'
+KUSTOMIZE_REF="${KUSTOMIZE_REF:-${1:-${GITHUB_SHA:-}}}"
+if [ -z "$KUSTOMIZE_REF" ]; then
+  KUSTOMIZE_REF="$(git rev-parse HEAD)"
+fi
+
+run_kustomize_build() {
+  local dir="$1"
+  if command -v kustomize >/dev/null 2>&1; then
+    kustomize build --load-restrictor LoadRestrictionsNone "$dir"
+  else
+    kubectl kustomize "$dir" --load-restrictor LoadRestrictionsNone
+  fi
+}
+
+FAIL=0
+for overlay in infra/k8s/alpha/*/; do
+  if [ ! -f "${overlay}kustomization.yaml" ]; then
+    continue
+  fi
+  overlay_name="${overlay%/}"
+  tmp="$(mktemp -d)"
+  cp -R "${overlay}"* "$tmp/"
+  sed "s/${PUBLISH_REF_PLACEHOLDER}/${KUSTOMIZE_REF}/g" "$tmp/kustomization.yaml" >"$tmp/kustomization.yaml.sub"
+  mv "$tmp/kustomization.yaml.sub" "$tmp/kustomization.yaml"
+  echo "=== kustomize build $overlay_name (ref=$KUSTOMIZE_REF) ==="
+  if run_kustomize_build "$tmp" >/dev/null; then
+    echo "ok $overlay_name"
+  else
+    echo "FAIL $overlay_name" >&2
+    FAIL=1
+  fi
+  rm -rf "$tmp"
+done
+exit "$FAIL"