docs(runners): document runner requirements — apt-get + sudo assumptions not universally safe #357

New issue

Closed

opened 2026-07-03 23:42:49 +02:00 by bosun · 0 comments

bosun commented

2026-07-03 23:42:49 +02:00

Owner

Empirical finding (external cold-read round 2)

External reviewer: "The workflow installs dependencies with apt-get/sudo. That is not universally safe on self-hosted Forgejo runners."

Some self-hosted Forgejo runners:

Run without sudo access
Run on non-Debian OSes (Alpine, RHEL, etc.)
Have pre-baked dependencies (jq/yq/curl/bats already installed)
Are ephemeral / rootless

Blocking rationale

Adopters with these runner configurations will hit surprising failures. v1.0.0 signals broad-adoption readiness, so runner requirements must be honest.

Fix path

Options (choose one):

Option A (docs): document explicit runner requirements — Debian/Ubuntu-like OS + sudo access + apt package availability. Adopters bring their own runner or opt out.

Option B (make it configurable): env-var-tunable dependency install commands. Default: apt-get. Adopters override for non-Debian.

Option C (make it optional): check for jq/yq/bats/curl availability first; only install if missing.

My lean: A for v1.0.0 (docs-honest), B or C as v1.1.0 improvements.

Verification AC

Runner requirements documented in integration.md + README quick-start
External cold-read round 3 finds no runner-assumption surprise

Anchor

External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

## Empirical finding (external cold-read round 2) External reviewer: "The workflow installs dependencies with `apt-get`/`sudo`. That is not universally safe on self-hosted Forgejo runners." Some self-hosted Forgejo runners: - Run without sudo access - Run on non-Debian OSes (Alpine, RHEL, etc.) - Have pre-baked dependencies (jq/yq/curl/bats already installed) - Are ephemeral / rootless ## Blocking rationale Adopters with these runner configurations will hit surprising failures. v1.0.0 signals broad-adoption readiness, so runner requirements must be honest. ## Fix path Options (choose one): **Option A (docs)**: document explicit runner requirements — Debian/Ubuntu-like OS + sudo access + apt package availability. Adopters bring their own runner or opt out. **Option B (make it configurable)**: env-var-tunable dependency install commands. Default: apt-get. Adopters override for non-Debian. **Option C (make it optional)**: check for jq/yq/bats/curl availability first; only install if missing. My lean: A for v1.0.0 (docs-honest), B or C as v1.1.0 improvements. ## Verification AC - Runner requirements documented in integration.md + README quick-start - External cold-read round 3 finds no runner-assumption surprise ## Anchor External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

bosun added the

priority/medium

size/S

kind/docs

labels

2026-07-03 23:42:49 +02:00