CI: Make helm-docs.sh portable

.buildkite/pipeline.yaml

@@ -20,10 +20,7 @@ steps:
     agents: { queue: standard }
 
   - label: ":book: Verify helm-docs is up-to-date"
-    commands:
-      - "./scripts/helm-docs.sh"
-      - "echo \"checking for uncommitted changes\""
-      - "[[ -z $(git status -s) ]]"
+    command: "./scripts/helm-docs.sh --check"
     agents: { queue: standard }
 
   - label: "(internal) Release: test"

AGENTS.md

@@ -2,10 +2,10 @@
 
 ## After Making Changes
 
-After making changes to any `values.yaml` file, regenerate the helm docs and verify there are no uncommitted changes:
+After making changes to any `values.yaml` file, regenerate the helm docs; this fails and lists any README it had to rewrite:
 
 ```sh
-./scripts/helm-docs.sh && [[ -z $(git status -s) ]]
+./scripts/helm-docs.sh --check
 ```
 
 If the README was updated, stage and commit the changes alongside your other modifications.

scripts/helm-docs.sh

@@ -1,39 +1,87 @@
-#!/usr/bin/env bash
-# Copy from https://github.com/linkerd/linkerd2/blob/main/bin/helm-docs
+#!/bin/sh
+# Downloads the pinned helm-docs release into target/bin (gitignored) on first
+# use, then runs it with any arguments passed to this script. Prints the path
+# of every README.md it rewrote, one per line, on stdout
+#
+# Usage:
+#   ./scripts/helm-docs.sh                Regenerate charts/**/README.md after changing a values.yaml file
+#   ./scripts/helm-docs.sh --check        CI check: regenerate, and exit 1 if any changed
+#   ./scripts/helm-docs.sh [args]         Run the helm-docs CLI with args
+#   ./scripts/helm-docs.sh --check [args] CI check with helm-docs CLI args
+#
+# POSIX compliant, so it runs the same anywhere: on developer machines, 
+# in Buildkite, and in the release worker's busybox image
+#
+# Adapted from https://github.com/linkerd/linkerd2/blob/main/bin/helm-docs
 
-set -euf -o pipefail
+# Pinned version of helm-docs
+helmdocsversion=1.14.2
 
-helmdocsv=1.14.2
-bindir=$( cd "${0%/*}" && pwd ) # Change to script dir and set bin dir to this
-targetbin=$( cd "$bindir"/.. && pwd )/target/bin
-helmdocsbin=$targetbin/helm-docs-$helmdocsv
+set -euf
 
+# Eat the --check positional arg
+check=false
+if [ "${1:-}" = --check ]; then
+    check=true
+    shift
+fi
+
+# Run from the repository root regardless of the caller's cwd: helm-docs
+# scans the cwd for charts, and it reads .helmdocsignore from there too.
+cd "$(dirname "$0")/.."
+
+targetbin=$PWD/target/bin
+helmdocsbin=$targetbin/helm-docs-$helmdocsversion
+
+# Download helm-docs if it doesn't already exist
 if [ ! -f "$helmdocsbin" ]; then
     # Release assets are named helm-docs_<version>_<OS>_<arch>.tar.gz,
     # e.g. Darwin_arm64, Linux_x86_64, Windows_x86_64
     case $(uname -s) in
         Darwin) os=Darwin ;;
         Linux) os=Linux ;;
         MSYS*|MINGW*|CYGWIN*) os=Windows ;;
-        *) echo "Unsupported OS: $(uname -s)"; exit 126 ;;
+        *) echo "Unsupported host OS: $(uname -s)" >&2; exit 126 ;;
     esac
     case $(uname -m) in
         x86_64|amd64) arch=x86_64 ;;
         aarch64|arm64) arch=arm64 ;;
         armv7l) arch=arm7 ;;
         armv6l) arch=arm6 ;;
-        *) echo "Unsupported architecture: $(uname -m)"; exit 126 ;;
+        *) echo "Unsupported host architecture: $(uname -m)" >&2; exit 126 ;;
     esac
-    helmdocscurl="https://github.com/norwoodj/helm-docs/releases/download/v$helmdocsv/helm-docs_${helmdocsv}_${os}_${arch}.tar.gz"
-    tmp=$(mktemp -d -t helm-docs.XXX)
+    helmdocscurl="https://github.com/norwoodj/helm-docs/releases/download/v$helmdocsversion/helm-docs_${helmdocsversion}_${os}_${arch}.tar.gz"
+    tmp=$(mktemp -d "${TMPDIR:-/tmp}/helm-docs.XXXXXX")
     mkdir -p "$targetbin"
     (
         cd "$tmp"
-        curl --proto '=https' --tlsv1.2 -sSfL -o "./helm-docs.tar.gz" "$helmdocscurl"
-        tar zf "./helm-docs.tar.gz" -x "helm-docs"
-        chmod +x "helm-docs"
+        curl --proto '=https' --tlsv1.2 -sSfL -o helm-docs.tar.gz "$helmdocscurl"
+        tar -xzf helm-docs.tar.gz helm-docs
+        chmod +x helm-docs
     )
     mv "$tmp/helm-docs" "$helmdocsbin"
+    rm -rf "$tmp"
 fi
 
-"$helmdocsbin" "$@"
+# Checksum every chart README before and after, to report which ones helm-docs
+# rewrote. Needs no git: the release worker has neither git nor a checkout
+readme_checksums() { find charts -name README.md -exec cksum {} +; }
+before=$(readme_checksums)
+
+# Run helm-docs, with any remaining args. Its own log lines go to stderr
+"$helmdocsbin" "$@"
+
+# Paths whose checksum line isn't in the before snapshot (changed or new)
+rewritten=$(readme_checksums | while read -r line; do
+    printf '%s\n' "$before" | grep -qxF -- "$line" || echo "${line##* }"
+done)
+
+# stdout is only ever this list, one path per line; the release worker
+# commits exactly these files
+if [ -n "$rewritten" ]; then
+    echo "$rewritten"
+    if [ "$check" = true ]; then
+        echo "The chart READMEs listed above are out of date. Run ./scripts/helm-docs.sh and commit them" >&2
+        exit 1
+    fi
+fi