fix: slim ubuntu-latest default; install shellcheck in ci.yml (#144)

Option B (andres ruling): keep act-22.04 for ubuntu-latest so box-class
ci tenants can hold the image; workflows supply tools the slim image
lacks. Opt-in ubuntu-latest-full for operators who need GH parity.
Plain converge warns when recorded labels lag the current default map.

Refs #144

.github/workflows/ci.yml

@@ -26,7 +26,21 @@ jobs:
         # The file list is printed so under-coverage shows up in the log, and
         # the comm below turns under-coverage into a failure rather than a
         # thing someone has to notice: every tracked `.sh` must be in the set.
+        #
+        # Install shellcheck when missing (#144). rig's default Forgejo label
+        # maps ubuntu-latest to catthehacker's act-22.04 (slim), which does not
+        # ship shellcheck; GitHub-hosted ubuntu-latest does. The conditional
+        # keeps each forge from paying for the other.
+        #
+        # sudo: load-bearing on GitHub (job runs as `runner` with passwordless
+        # sudo) and a no-op on act-22.04 (jobs run as uid 0; the image has no
+        # `runner` account). Do not delete it as "dead weight" — that breaks
+        # the GitHub half the day that image stops preinstalling shellcheck.
         run: |
+          if ! command -v shellcheck >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y shellcheck
+          fi
           shopt -s globstar dotglob
           files=(bin/* **/*.sh)
           printf 'shellcheck: %s\n' "${files[@]}"

changelog.d/144.md

@@ -0,0 +1,3 @@
+### Fixed
+
+- Forgejo runners keep the slim `act-22.04` image for `ubuntu-latest` (full is ~54.5 GB and does not fit a box-class ci tenant); `ci.yml` installs `shellcheck` when missing, and the default map offers opt-in `ubuntu-latest-full` (#144)

commands/forgejo-runner-install.sh

@@ -31,7 +31,17 @@ die()  { printf 'rig-forgejo-runner: ERROR: %s\n' "$1" >&2; exit "${2:-1}"; }
 # on the box itself. No docker-in-docker: the guide this came from stacks a
 # privileged dind sidecar with a plaintext tcp://…:2375 daemon to isolate jobs
 # from a shared CI server, and inside a box that boundary is already paid for.
-DEFAULT_LABELS='ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04,docker:docker://node:22-bookworm'
+#
+# WHY act-22.04 (slim) for ubuntu-latest, not full-22.04 — measured 2026-08-01
+# against ghcr manifests (#144):
+#   act-22.04:  ~0.55 GB compressed / ~2.2 GB on disk — no shellcheck
+#   full-22.04: ~18.67 GB compressed / ~54.5 GB on disk — has shellcheck 0.8.0
+# A normal box-class ci tenant cannot hold 54.5 GB (typical free space ~34 GB).
+# So ubuntu-latest stays slim, and workflows must not assume GitHub-image tools
+# (rig's own ci.yml installs shellcheck when missing). Operators who need the
+# full tool surface opt in with runs-on: ubuntu-latest-full — that label is
+# inert until matched, so boxes that never ask pay nothing.
+DEFAULT_LABELS='ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04,ubuntu-latest-full:docker://ghcr.io/catthehacker/ubuntu:full-22.04,docker:docker://node:22-bookworm'
 
 # fetch_and_verify_sha256 <asset-url> <file> <sumfile> <label>
 #
@@ -93,8 +103,10 @@ usage: rig forgejo-runner install --instance <url> [options]
                         time). Pin it for a deterministic, auditable install.
   --name <name>         runner name (default: this host's hostname)
   --labels <csv>        runner labels; replaces the default. The default maps
-                        ubuntu-latest and docker onto container images, so a
-                        workflow written for GitHub runs unchanged.
+                        ubuntu-latest (slim act image), ubuntu-latest-full
+                        (opt-in parity image), and docker onto containers so
+                        a workflow written for GitHub runs; full tools need
+                        runs-on: ubuntu-latest-full or an install step.
   --user <name>         unprivileged service user (default: the tenant user
                         `ci` when it exists, else forgejo-runner; created if
                         absent; never root)
@@ -408,14 +420,26 @@ install -d -m 0755 -o "$RUNNER_USER" -g "$RUNNER_GROUP" "$USER_HOME/.cache"
 if [ -e "$RUNNER_DIR/.runner" ]; then
   log "already registered; skipping registration"
   # Registration was skipped, so the labels on the instance are the ones it was
-  # registered with — NOT whatever this invocation was passed. Say so when the
-  # operator explicitly asked for different ones, rather than letting the
-  # request evaporate. Only when EXPLICIT: comparing the default against a
-  # runner registered with custom labels would warn on every plain converge.
-  if [ "$LABELS_EXPLICIT" -eq 1 ] && [ -r "$RUNNER_DIR/.rig-labels" ]; then
+  # registered with — NOT whatever this invocation was passed. Forgejo owns
+  # labels from registration time; a re-run never rewrites them.
+  #
+  # Two warn paths (#144):
+  #   EXPLICIT --labels that differs → operator asked and it was not applied.
+  #   Plain converge whose recorded labels differ from the current default →
+  #   rig's default map moved (e.g. a new opt-in label). Without this warn the
+  #   operator re-runs install, sees "already registered", and believes they
+  #   have the new default while Forgejo still holds the old set.
+  # Custom --labels that match what was registered stay quiet. Jobs matching
+  # labels this runner already has are unaffected either way — re-register
+  # only to pick up labels that are missing from the recorded set.
+  if [ -r "$RUNNER_DIR/.rig-labels" ]; then
     RECORDED="$(cat "$RUNNER_DIR/.rig-labels")"
     if [ "$RECORDED" != "$LABELS" ]; then
-      warn "--labels was not applied: this runner is already registered, and Forgejo owns its labels from registration time. It still has: ${RECORDED}. Labels are what 'runs-on' matches, so changing them means re-registering: 'rig forgejo-runner remove' then install again with the labels you want."
+      if [ "$LABELS_EXPLICIT" -eq 1 ]; then
+        warn "--labels was not applied: this runner is already registered, and Forgejo owns its labels from registration time. It still has: ${RECORDED}. Labels are what 'runs-on' matches, so changing them means re-registering: 'rig forgejo-runner remove' then install again with the labels you want."
+      else
+        warn "this runner's labels differ from rig's current default (recorded: ${RECORDED}). Forgejo owns labels from registration time — a plain re-run does not change them. Re-register ('rig forgejo-runner remove' then install) only if you need labels the recorded set is missing (e.g. a newly added default). Jobs matching labels this runner already has are unaffected."
+      fi
     fi
   fi
 else

test/cli.sh

@@ -3704,6 +3704,26 @@ check "forgejo-runner: an explicit --labels on a rerun warns it was not applied"
   grep -o -- "--labels was not applied" "$FR"
 check "forgejo-runner: that warning is gated on --labels being EXPLICIT" 0 "LABELS_EXPLICIT" \
   grep -o "LABELS_EXPLICIT" "$FR"
+# #144 option B: plain converge must notice when rig's default map moved since
+# registration (e.g. a newly added ubuntu-latest-full), without implying that
+# every re-run rewrites Forgejo-side labels or that existing matching jobs fail.
+check "forgejo-runner: plain converge warns when recorded labels differ from current default" 0 "differ from rig's current default" \
+  grep -o "differ from rig's current default" "$FR"
+check "forgejo-runner: that plain-converge warn says re-register only for missing labels" 0 "only if you need labels the recorded set is missing" \
+  grep -o "only if you need labels the recorded set is missing" "$FR"
+# Default map: slim ubuntu-latest (act), opt-in full, docker — pin the three
+# so a silent drop of the full rider or a flip back to full-as-default fails.
+check "forgejo-runner: DEFAULT_LABELS maps ubuntu-latest to act-22.04 (slim)" 0 "ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04" \
+  grep -o "ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04" "$FR"
+check "forgejo-runner: DEFAULT_LABELS offers ubuntu-latest-full as opt-in" 0 "ubuntu-latest-full:docker://ghcr.io/catthehacker/ubuntu:full-22.04" \
+  grep -o "ubuntu-latest-full:docker://ghcr.io/catthehacker/ubuntu:full-22.04" "$FR"
+check "forgejo-runner: DEFAULT_LABELS comment records the slim/full size measurement" 0 "54.5 GB" \
+  grep -o "54.5 GB" "$FR"
+# ci.yml must install shellcheck when the image lacks it (#144 option B).
+check "ci.yml: shellcheck step installs the tool when missing" 0 "command -v shellcheck" \
+  grep -o "command -v shellcheck" "$ROOT/.github/workflows/ci.yml"
+check "ci.yml: shellcheck install uses sudo (GitHub path; no-op on act as root)" 0 "sudo apt-get install -y shellcheck" \
+  grep -o "sudo apt-get install -y shellcheck" "$ROOT/.github/workflows/ci.yml"
 # The GitHub sibling is the precedent this restores — pin that it still scopes
 # its own write, so the two cannot drift apart again.
 gh_labels_write_is_scoped() {