runner-portability

name	runner-portability
description	Use when writing or reviewing addon test runner shell scripts that may run on macOS, Linux, host-k8s Jobs, CI images, or mixed bash/sh environments. Catches portability traps around bash 3.2, set -euo pipefail, seq behavior, arrays, local assignment, quoting, and kubeconfig/context state.
allowed-tools	Bash(shellcheck *) Bash(bash *) Bash(rg *) Read

Runner Portability

Hard Rules

1. Know the shell that will run the script. macOS /bin/bash is often 3.2; busybox containers may only have /bin/sh.
2. set -euo pipefail changes harmless-looking code. Review empty arrays, unset variables, pipelines, and command substitution carefully.
3. Do not rely on GNU-only behavior. seq, date, readlink, sed, and grep may differ across macOS and Linux.
4. Pin kube context explicitly. Portability includes client state: use --context or KUBECONFIG, not ambient current-context.
5. Separate assignment from command status. local x=$(cmd) hides failure in some shells.
6. Quote engine SQL / shell metacharacters. $, >, *, and backslashes should not be interpreted by the wrong shell layer.
7. Test zero-count loops. BSD seq behavior can make a loop run when Linux would skip it.

When To Invoke

Use this skill when:

• Writing or reviewing smoke / chaos runner scripts.
• Moving a script from Mac to CI, k3d, host-k8s Job, or vcluster runner.
• Seeing a script pass locally but fail in another runner image.
• Using bash arrays, set -u, seq, local, pipelines, heredocs, or SQL strings.
• Debugging a test failure where the product looks fine but the runner output is strange.

Pre-Commit Checklist

Before merging runner script changes:

1. Print shell version in logs:

   echo "shell=$SHELL bash=$(bash --version 2>/dev/null | head -1 || true)"
   

2. Avoid bash-only features if script declares #!/bin/sh.
3. For bash scripts, state the minimum bash version.
4. Replace local x=$(cmd) with:

   local x
   x=$(cmd)
   

5. Guard unset variables:

   : "${CTX:?CTX required}"
   

6. Avoid seq 1 0; use arithmetic loops when zero is possible.
7. Pin Kubernetes access:

   kubectl --context "$CTX" get ns
   # or
   KUBECONFIG="$KUBECONFIG_FILE" kubectl get ns
   

8. Run a local shell parse check:

   bash -n path/to/script.sh
   

Common Traps

Trap	Symptom	Fix
Empty array + set -u	unbound variable on macOS bash	Guard length or avoid arrays
local x=$(cmd)	command failure hidden	Split declaration and assignment
seq 1 0	macOS runs loop unexpectedly	Use arithmetic guard
SQL uses $	shell expands it before client sees it	Quote heredoc or escape $
Ambient kube context	Script writes to wrong cluster	Pass --context / KUBECONFIG
#!/bin/bash in busybox	OCI ENOENT	Use /bin/sh or ship bash

Failure Triage

If a runner fails in one environment but not another:

1. Record shell version, OS, image, kubectl version, and current context.
2. Re-run only the failing command with set -x.
3. Check whether the output differs because of shell/tool behavior, not product behavior.
4. Classify as runner-layer until the same operation fails with a pinned context and known shell.

Related Docs

• docs/addon-test-runner-portability-guide.md
• docs/addon-test-script-preflight-guide.md
• docs/cases/mariadb/roleprobe-bash-shebang-on-busybox-kbagent-case.md
• docs/cases/methodology/run7-context-inheritance-2026-05-04-case.md