feat: support --version flag in lib/**/init.sh scripts

.devcontainer/01-echoes-lost-in-orbit_beginner/post-create.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 set -e
 
-lib/shared/init.sh
-lib/kubernetes/init.sh
-lib/argocd/init.sh --read-only
+lib/shared/init.sh --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+# kind: https://github.com/kubernetes-sigs/kind/releases | kubectl: https://dl.k8s.io | kubens: https://github.com/ahmetb/kubectx/releases | k9s: https://github.com/derailed/k9s/releases | helm: https://github.com/helm/helm/releases
+lib/kubernetes/init.sh \
+  --kind-version v0.30.0 \
+  --kubectl-version v1.34.1 \
+  --kubens-version v0.9.5 \
+  --k9s-version v0.50.16 \
+  --helm-version v4.0.1
+lib/argocd/init.sh --read-only --version v3.2.0 # https://github.com/argoproj/argo-cd/releases

.devcontainer/01-echoes-lost-in-orbit_expert/post-create.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
 set -e
 
-lib/shared/init.sh
-lib/kubernetes/init.sh
-lib/argocd/init.sh --read-only
-lib/argo-rollouts/init.sh
-lib/prometheus/init.sh
-lib/jaeger/init.sh
+lib/shared/init.sh --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+# kind: https://github.com/kubernetes-sigs/kind/releases | kubectl: https://dl.k8s.io | kubens: https://github.com/ahmetb/kubectx/releases | k9s: https://github.com/derailed/k9s/releases | helm: https://github.com/helm/helm/releases
+lib/kubernetes/init.sh \
+  --kind-version v0.30.0 \
+  --kubectl-version v1.34.1 \
+  --kubens-version v0.9.5 \
+  --k9s-version v0.50.16 \
+  --helm-version v4.0.1
+lib/argocd/init.sh --read-only --version v3.2.0 # https://github.com/argoproj/argo-cd/releases
+lib/argo-rollouts/init.sh --version v1.8.3 # https://github.com/argoproj/argo-rollouts/releases
+lib/prometheus/init.sh --version 29.1.0 # https://artifacthub.io/packages/helm/prometheus-community/prometheus
+lib/jaeger/init.sh --version 4.1.5 # https://artifacthub.io/packages/helm/jaegertracing/jaeger

.devcontainer/01-echoes-lost-in-orbit_intermediate/post-create.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
 set -e
 
-lib/shared/init.sh
-lib/kubernetes/init.sh
-lib/argocd/init.sh --read-only
-lib/argo-rollouts/init.sh
-lib/kube-state-metrics/init.sh
-lib/prometheus/init.sh
+lib/shared/init.sh --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+# kind: https://github.com/kubernetes-sigs/kind/releases | kubectl: https://dl.k8s.io | kubens: https://github.com/ahmetb/kubectx/releases | k9s: https://github.com/derailed/k9s/releases | helm: https://github.com/helm/helm/releases
+lib/kubernetes/init.sh \
+  --kind-version v0.30.0 \
+  --kubectl-version v1.34.1 \
+  --kubens-version v0.9.5 \
+  --k9s-version v0.50.16 \
+  --helm-version v4.0.1
+lib/argocd/init.sh --read-only --version v3.2.0 # https://github.com/argoproj/argo-cd/releases
+lib/argo-rollouts/init.sh --version v1.8.3 # https://github.com/argoproj/argo-rollouts/releases
+lib/kube-state-metrics/init.sh --version 7.0.0 # https://artifacthub.io/packages/helm/prometheus-community/kube-state-metrics
+lib/prometheus/init.sh --version 29.1.0 # https://artifacthub.io/packages/helm/prometheus-community/prometheus

.devcontainer/02-building-cloudhaven_01-beginner/post-create.sh

@@ -8,7 +8,7 @@ source "$REPO_ROOT/lib/scripts/tracker.sh"
 set_tracking_context "02-building-cloudhaven" "beginner"
 track_codespace_created
 
-"$REPO_ROOT/lib/shared/init.sh"
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
 
-"$REPO_ROOT/lib/open-tofu/init.sh"
-"$REPO_ROOT/lib/gcp-api-mock/init.sh"
+"$REPO_ROOT/lib/open-tofu/init.sh" --version v1.11.2 # https://github.com/opentofu/opentofu/releases
+"$REPO_ROOT/lib/gcp-api-mock/init.sh" --version v1.1.4 # https://github.com/KatharinaSick/gcp-api-mock/releases

.devcontainer/02-building-cloudhaven_02-intermediate/post-create.sh

@@ -8,7 +8,7 @@ source "$REPO_ROOT/lib/scripts/tracker.sh"
 set_tracking_context "02-building-cloudhaven" "intermediate"
 track_codespace_created
 
-"$REPO_ROOT/lib/shared/init.sh"
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
 
-"$REPO_ROOT/lib/open-tofu/init.sh"
-"$REPO_ROOT/lib/gcp-api-mock/init.sh"
+"$REPO_ROOT/lib/open-tofu/init.sh" --version v1.11.2 # https://github.com/opentofu/opentofu/releases
+"$REPO_ROOT/lib/gcp-api-mock/init.sh" --version v1.1.4 # https://github.com/KatharinaSick/gcp-api-mock/releases

.devcontainer/02-building-cloudhaven_03-expert/post-create.sh

@@ -8,8 +8,8 @@ source "$REPO_ROOT/lib/scripts/tracker.sh"
 set_tracking_context "02-building-cloudhaven" "expert"
 track_codespace_created
 
-"$REPO_ROOT/lib/shared/init.sh"
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
 
-"$REPO_ROOT/lib/github-cli/init.sh"
-"$REPO_ROOT/lib/open-tofu/init.sh"
-"$REPO_ROOT/lib/gcp-api-mock/init.sh"
+"$REPO_ROOT/lib/github-cli/init.sh" --version v2.86.0 # https://github.com/cli/cli/releases
+"$REPO_ROOT/lib/open-tofu/init.sh" --version v1.11.2 # https://github.com/opentofu/opentofu/releases
+"$REPO_ROOT/lib/gcp-api-mock/init.sh" --version v1.1.4 # https://github.com/KatharinaSick/gcp-api-mock/releases

.devcontainer/03-the-ai-observatory_01-beginner/post-create.sh

@@ -8,8 +8,14 @@ source "$REPO_ROOT/lib/scripts/tracker.sh"
 set_tracking_context "03-the-ai-observatory" "beginner"
 track_codespace_created
 
-"$REPO_ROOT/lib/shared/init.sh"
-"$REPO_ROOT/lib/kubernetes/init.sh"
-"$REPO_ROOT/lib/jaeger/init.sh"
-"$REPO_ROOT/lib/otel-collector/init.sh"
-"$REPO_ROOT/lib/ollama/init.sh"
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+# kind: https://github.com/kubernetes-sigs/kind/releases | kubectl: https://dl.k8s.io | kubens: https://github.com/ahmetb/kubectx/releases | k9s: https://github.com/derailed/k9s/releases | helm: https://github.com/helm/helm/releases
+"$REPO_ROOT/lib/kubernetes/init.sh" \
+  --kind-version v0.30.0 \
+  --kubectl-version v1.34.1 \
+  --kubens-version v0.9.5 \
+  --k9s-version v0.50.16 \
+  --helm-version v4.0.1
+"$REPO_ROOT/lib/jaeger/init.sh" --version 4.1.5 # https://artifacthub.io/packages/helm/jaegertracing/jaeger
+"$REPO_ROOT/lib/otel-collector/init.sh" --version 0.148.0 # https://github.com/open-telemetry/opentelemetry-collector-releases/releases
+"$REPO_ROOT/lib/ollama/init.sh" --version 1.40.0 # https://artifacthub.io/packages/helm/otwld/ollama

.devcontainer/03-the-ai-observatory_02-intermediate/post-create.sh

@@ -8,11 +8,17 @@ source "$REPO_ROOT/lib/scripts/tracker.sh"
 set_tracking_context "03-the-ai-observatory" "intermediate"
 track_codespace_created
 
-"$REPO_ROOT/lib/shared/init.sh"
-"$REPO_ROOT/lib/kubernetes/init.sh"
-"$REPO_ROOT/lib/jaeger/init.sh"
-"$REPO_ROOT/lib/otel-collector/init.sh"
-"$REPO_ROOT/lib/prometheus/init.sh" --operator
-"$REPO_ROOT/lib/ollama/init.sh"
-"$REPO_ROOT/lib/qdrant/init.sh"
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+# kind: https://github.com/kubernetes-sigs/kind/releases | kubectl: https://dl.k8s.io | kubens: https://github.com/ahmetb/kubectx/releases | k9s: https://github.com/derailed/k9s/releases | helm: https://github.com/helm/helm/releases
+"$REPO_ROOT/lib/kubernetes/init.sh" \
+  --kind-version v0.30.0 \
+  --kubectl-version v1.34.1 \
+  --kubens-version v0.9.5 \
+  --k9s-version v0.50.16 \
+  --helm-version v4.0.1
+"$REPO_ROOT/lib/jaeger/init.sh" --version 4.1.5 # https://artifacthub.io/packages/helm/jaegertracing/jaeger
+"$REPO_ROOT/lib/otel-collector/init.sh" --version 0.148.0 # https://github.com/open-telemetry/opentelemetry-collector-releases/releases
+"$REPO_ROOT/lib/prometheus/init.sh" --operator --version 82.1.1 # https://artifacthub.io/packages/helm/prometheus-community/kube-prometheus-stack
+"$REPO_ROOT/lib/ollama/init.sh" --version 1.40.0 # https://artifacthub.io/packages/helm/otwld/ollama
+"$REPO_ROOT/lib/qdrant/init.sh" --version 1.16.3 # https://artifacthub.io/packages/helm/qdrant/qdrant
 

.devcontainer/03-the-ai-observatory_03-expert/post-create.sh

@@ -8,9 +8,15 @@ source "$REPO_ROOT/lib/scripts/tracker.sh"
 set_tracking_context "03-the-ai-observatory" "expert"
 track_codespace_created
 
-"$REPO_ROOT/lib/shared/init.sh"
-"$REPO_ROOT/lib/kubernetes/init.sh"
-"$REPO_ROOT/lib/jaeger/init.sh"
-"$REPO_ROOT/lib/otel-collector/init.sh"
-"$REPO_ROOT/lib/ollama/init.sh"
-"$REPO_ROOT/lib/qdrant/init.sh"
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+# kind: https://github.com/kubernetes-sigs/kind/releases | kubectl: https://dl.k8s.io | kubens: https://github.com/ahmetb/kubectx/releases | k9s: https://github.com/derailed/k9s/releases | helm: https://github.com/helm/helm/releases
+"$REPO_ROOT/lib/kubernetes/init.sh" \
+  --kind-version v0.30.0 \
+  --kubectl-version v1.34.1 \
+  --kubens-version v0.9.5 \
+  --k9s-version v0.50.16 \
+  --helm-version v4.0.1
+"$REPO_ROOT/lib/jaeger/init.sh" --version 4.1.5 # https://artifacthub.io/packages/helm/jaegertracing/jaeger
+"$REPO_ROOT/lib/otel-collector/init.sh" --version 0.148.0 # https://github.com/open-telemetry/opentelemetry-collector-releases/releases
+"$REPO_ROOT/lib/ollama/init.sh" --version 1.40.0 # https://artifacthub.io/packages/helm/otwld/ollama
+"$REPO_ROOT/lib/qdrant/init.sh" --version 1.16.3 # https://artifacthub.io/packages/helm/qdrant/qdrant

.devcontainer/post-create.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-lib/shared/init.sh
+lib/shared/init.sh --version v0.17.0 # https://github.com/charmbracelet/gum/releases
 
 echo "→ Installing mkdocs-material..."
 pip install --quiet mkdocs-material mkdocs-monorepo-plugin

.github/workflows/lint-init-versions.yaml

@@ -0,0 +1,51 @@
+# This check exists to catch missing --version flags at PR time rather than when a
+# contributor's Codespace silently fails to start. Failing fast here gives a much
+# better experience than debugging a broken environment after the fact.
+name: Lint init script versions
+
+on:
+  pull_request:
+    paths:
+      - '.devcontainer/**/post-create.sh'
+      - 'lib/**/init.sh'
+
+jobs:
+  check-versions-pinned:
+    name: All init.sh calls have pinned versions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check that every init.sh call has a version flag
+        run: |
+          set -euo pipefail
+
+          failed=0
+
+          while IFS= read -r file; do
+            while IFS= read -r line; do
+              # Skip blank lines, comments, and lines that don't reference an init script
+              [[ "$line" =~ ^[[:space:]]*# ]] && continue
+              [[ "$line" =~ init\.sh ]] || continue
+
+
+              # Skip continuation lines (they carry the version flags for kubernetes/init.sh)
+              [[ "$line" == *\\ ]] && continue
+              [[ "$line" =~ ^[[:space:]]+-- ]] && continue
+
+              # The line calls an init script — check it carries a version flag
+              if ! grep -qE '(--version|--kind-version|--kubectl-version|--kubens-version|--k9s-version|--helm-version)' <<< "$line"; then
+                echo "ERROR: $file: missing version flag on: $line"
+                failed=1
+              fi
+            done < "$file"
+          done < <(find .devcontainer -name 'post-create.sh')
+
+          if [[ $failed -eq 1 ]]; then
+            echo ""
+            echo "Every lib/**/init.sh call must pass a pinned --version flag."
+            echo "Run the script with --help to see available flags."
+            exit 1
+          fi
+
+          echo "✅ All init.sh calls have pinned version flags."

docs/contributing/adventures.md

@@ -77,10 +77,18 @@ Open the generated `.devcontainer/00-adventure-name_NN-level/` files and fill in
 For Kubernetes-based adventures, [Adventure 01](../../adventures/01-echoes-lost-in-orbit/) is a good reference for what features and setup scripts to use.
 
 **post-create.sh** runs once when the container is created:
-- Install CLI tools using setup scripts from `lib/`
+- Install CLI tools using setup scripts from `lib/` — every script accepts a `--version` flag to pin a specific version. Run any script with `--help` to see available flags and defaults.
 - Pull container images
 - Set up one-time configurations
 
+Example calls in `post-create.sh`:
+```bash
+"$REPO_ROOT/lib/kubernetes/init.sh"                                            # use default versions
+"$REPO_ROOT/lib/argocd/init.sh" --version v3.5.0                              # pin a version
+"$REPO_ROOT/lib/argocd/init.sh" --read-only --version v3.5.0                  # combine flags
+"$REPO_ROOT/lib/kubernetes/init.sh" --kubectl-version v1.35.0 --helm-version v4.1.0  # per-tool versions
+```
+
 **post-start.sh** runs every time the container starts:
 - Start services (databases, clusters, etc.)
 - Apply initial state

lib/argo-rollouts/init.sh

@@ -1,15 +1,51 @@
 #!/usr/bin/env bash
 set -e
 
+help() {
+  echo "Usage: $0 [OPTIONS]"
+  echo "Options:"
+  echo " --help             Display this help message"
+  echo " --version <ver>    Argo Rollouts version to install (required)"
+}
+
+# Parse flags
+version=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help)
+      help
+      exit 0
+      ;;
+    --version)
+      if [[ -z "${2-}" ]]; then
+        echo "Error: --version requires a value" >&2
+        exit 1
+      fi
+      version="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$version" ]]; then
+  echo "Error: --version is required" >&2
+  exit 1
+fi
+
 echo "✨ Installing Argo Rollouts"
 kubectl create namespace argo-rollouts
-kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/download/v1.8.3/install.yaml
+kubectl apply -n argo-rollouts -f "https://github.com/argoproj/argo-rollouts/releases/download/${version}/install.yaml"
 
 echo "✨ Waiting for Argo Rollouts controller to be ready"
 kubectl rollout status deployment/argo-rollouts -n argo-rollouts --timeout=300s
 
 echo "✨ Installing Argo Rollouts Kubectl plugin"
-curl -LO https://github.com/argoproj/argo-rollouts/releases/download/v1.8.3/kubectl-argo-rollouts-linux-amd64
+curl -LO "https://github.com/argoproj/argo-rollouts/releases/download/${version}/kubectl-argo-rollouts-linux-amd64"
 chmod +x ./kubectl-argo-rollouts-linux-amd64
 sudo mv ./kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rollouts
 

lib/argocd/init.sh

@@ -6,35 +6,57 @@ SCRIPT_DIR="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
 help() {
   echo "Usage: $0 [OPTIONS]"
   echo "Options:"
-  echo " --help         Display this help message"
-  echo " --read-only    Disables the ArgoCD admin user and only provides read-only access"
+  echo " --help             Display this help message"
+  echo " --read-only        Disables the ArgoCD admin user and only provides read-only access"
+  echo " --version <ver>    Argo CD version to install (required)"
 }
 
 # Parse flags
 read_only=false
+version=""
 
-for arg in "$@"; do
-  case "$arg" in
+while [[ $# -gt 0 ]]; do
+  case "$1" in
     --help)
       help
       exit 0
       ;;
     --read-only)
       read_only=true
+      shift
+      ;;
+    --version)
+      if [[ -z "${2-}" ]]; then
+        echo "Error: --version requires a value" >&2
+        exit 1
+      fi
+      version="$2"
+      shift 2
       ;;
     *)
-      echo "Unknown option: $arg" >&2
+      echo "Unknown option: $1" >&2
       exit 1
       ;;
   esac
 done
 
+if [[ -z "$version" ]]; then
+  echo "Error: --version is required" >&2
+  exit 1
+fi
+
 echo "✨ Installing Argo CD"
 kubectl create namespace argocd
-kubectl apply -k "$SCRIPT_DIR/manifests"
+
+manifests_tmp="$(mktemp -d)"
+trap 'rm -rf "${manifests_tmp}"' EXIT
+cp -r "$SCRIPT_DIR/manifests/." "${manifests_tmp}/"
+sed -i "s|argoproj/argo-cd/[^/]*/manifests/install.yaml|argoproj/argo-cd/${version}/manifests/install.yaml|" \
+  "${manifests_tmp}/kustomization.yaml"
+kubectl apply -k "${manifests_tmp}"
 
 echo "✨ Installing Argo CD CLI"
-curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/download/v3.2.0/argocd-linux-amd64
+curl -sSL -o argocd-linux-amd64 "https://github.com/argoproj/argo-cd/releases/download/${version}/argocd-linux-amd64"
 sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
 rm argocd-linux-amd64
 
@@ -49,7 +71,7 @@ if [ "$read_only" = true ]; then
   argocd login localhost:30100 --username admin --password "$admin_password" --plaintext
   argocd account update-password \
     --account readonly \
-    --current-password $admin_password \
+    --current-password "$admin_password" \
     --new-password a-super-secure-password
 
   echo "✨ Disabling admin user for read-only mode"

lib/argocd/manifests/kustomization.yaml

@@ -3,8 +3,11 @@ kind: Kustomization
 
 namespace: argocd
 
+# ARGOCD_VERSION is a placeholder substituted by init.sh at deploy time via sed.
+# Applying this kustomization directly without going through init.sh will fail
+# intentionally, because kubectl cannot resolve the literal placeholder as a URL.
 resources:
-  - https://raw.githubusercontent.com/argoproj/argo-cd/v3.2.0/manifests/install.yaml
+  - https://raw.githubusercontent.com/argoproj/argo-cd/ARGOCD_VERSION/manifests/install.yaml
 
 patches:
   - path: overlays/argocd-server-service.yaml