docs: describe what is, now that the move is done #26

Merged

jklein merged 1 commits from docs/gitea-is-the-state into main 2026-09-17 17:16:29 +02:00

Conversation 1 Commits 1 Files Changed 2

+60 -26

jlab-bot commented 2026-09-17 17:14:28 +02:00

Member

Copy link

Copy source

Die Dokumentation beschrieb einen Umzug im Gange. Der ist durch — damit führte sie ab jetzt aktiv in die Irre.

Die schlimmste Stelle war im README-Abschnitt „Where this repo lives":

„the install-test cannot run on Gitea at all — see #225."

Vor zwei Tagen richtig, heute das Gegenteil der Wahrheit. Wer darauf aufbaut, baut auf einer Annahme, die wir selbst widerlegt haben.

Was jetzt drinsteht

Nicht die Chronik des Umzugs — wen die interessiert, der liest Gitea #14. Sondern: was gilt, und dort wo eine Eigenheit teuer war, warum.

Der Abschnitt behält seinen Platz, dreht aber das Vorzeichen um: aus „was uns noch blockiert" wird was ein Gitea-Runner anders macht als ein GitHub-Runner, mit den Messwerten. Neu aufgeschrieben, weil es dauerhaft gilt und bisher nirgends sauber stand:

• Die Matrix läuft nebenläufig in einem Job unter einem Status-Kontext. Ein Pflicht-Check pro Chart ist damit unmöglich, und der Kontextname trägt den unaufgelösten Matrix-Ausdruck — die Namen müssen von einem echten Lauf abgelesen werden, nicht von GitHub kopiert. Das ist die Grundlage für jeden Eingriff in den Branch-Schutz und steht jetzt auch in CLAUDE.md.
• Laufzeiten als Erwartungswert, damit eine spätere Abweichung auffällt — Create k3d cluster 19–25 s, zwei Charts nebenläufig 210–216 s bei 6 s Streuung über drei Läufe, freesailarr mit zehn Containern 225 s. Mit der Einordnung, dass der Unterschied zu GitHub strukturell ist (ein Runner für beide Zweige gegen eine VM je Zweig) und nicht Leistung — beim Cluster-Anlegen ist der Runner sogar leicht schneller.
• aquasecurity/setup-trivy ist unbrauchbar und warum: die Action klont aquasecurity/trivy von github.com mit github.token, was hier ein Gitea-Token ist.
• Werkzeuge werden installiert, nicht geerbt — kubectl gepinnt mit Skew-Wächter, envsubst nur bereitgestellt, samt Begründung für den Unterschied (die Version des einen ändert die Bedeutung des Tests, die des anderen nicht).
• Containerisierung wird erkannt, nicht aus der Plattform gefolgert, weil ein selbstgehosteter GitHub-Runner im Container dasselbe Problem hätte.

Die sechs Annahmen, aufgeteilt statt aufgelistet

Fünf sind Umgebungsannahmen (MTU, fs.inotify, fehlendes kubectl und envsubst, kubeconfig auf 0.0.0.0): sie scheitern laut, sagen nichts über unseren Code und werden auf der Knotenseite behoben (cluster-config). Kurz gehalten.

Die sechste steht als eigener Block, weil sie als einzige etwas über unseren Code sagt: der fest verdrahtete Clustername war auch auf GitHub falsch und fiel dort nur nie auf, weil jeder Matrix-Zweig eine eigene VM bekommt. Mit der Lehre, die das trägt:

A generous environment is no friend when you want to know whether something is correct.

Zwei Regeln, als Prüfregel statt als Erzählung

1. Eine Prüfung, die ein kaputtes System besteht, ist schlechter als keine — mit beiden hohlen Formen, die das verursacht haben (kubectl get nodes liefert 0 bei leerer Liste; kubectl wait --for=condition=Ready nodes --all ist bei null Knoten leer erfüllt).
2. Grün heißt nicht geprüft — mit Verweis auf Gitea #24 (Fixture-Images ohne Renovate-Verfolgung) als offenen Fall derselben Art, ausdrücklich nicht als gelöst dargestellt.

Ein Nebenbefund, der mir beim Schreiben aufgefallen ist

Die Dateien sind dicht mit #n durchsetzt, und die Nummern zeigen jetzt ins Leere oder — schlimmer — auf etwas Falsches:

• Die meisten benennen geschlossene GitHub-Issues (#22, #82, #157, #158, #214, #231, #68 …), die nie migriert wurden und nur dort existieren.
• Gitea löst ein blankes #n gegen den eigenen Zähler auf. #22 rendert hier als Link auf einen nicht verwandten Wegwerf-PR — nicht auf das Install-Test-Issue, das der Text meint. Genau die Falle, die der Rumpf von #14 vorhergesagt hat.

Sechzehn Verweise auf Nummern umzuschreiben, die es nicht gibt, wäre falsch. Stattdessen steht es einmal oben im README und in CLAUDE.md: #n meint den GitHub-Tracker, die zum Umzug offenen Issues sind Gitea #5–#21 und #24, die Zuordnung hängt als Kommentar an Gitea #14 — und für neue Verweise gilt die Gitea-Nummer.

Überschneidung mit dem offenen PR #25

Keine. Per git merge-tree gegengeprüft statt geschätzt: die beiden Zweige mergen in beiden Reihenfolgen konfliktfrei. #25 fasst im README die Zeilen 15, 119, 125, 127, 215, 227 und 321 an, dieser PR die Zeilen 5, 56–70, 111, 153, 157 und 161–164. Es gibt keine nötige Reihenfolge.

Eine Abhängigkeit inhaltlicher Art bleibt und ist im Text gekennzeichnet: die Zeile „freesailarr mit zehn Containern, 225 s" ist auf dem Stand von #25 gemessen und trägt diesen Hinweis, damit sie nicht als Verhalten des heutigen main gelesen wird.

Was ungemessen bleibt und auch so dasteht

/dev/fuse und User-Namespaces. Sie standen nie im Weg — das ist nicht dasselbe wie geprüft, und es steht als ungemessen da.

Die Dokumentation beschrieb einen Umzug im Gange. Der ist durch — damit führte sie ab jetzt aktiv in die Irre. Die schlimmste Stelle war im README-Abschnitt „Where this repo lives": > „**the install-test cannot run on Gitea at all** — see #225." Vor zwei Tagen richtig, heute das Gegenteil der Wahrheit. Wer darauf aufbaut, baut auf einer Annahme, die wir selbst widerlegt haben. ## Was jetzt drinsteht **Nicht die Chronik des Umzugs** — wen die interessiert, der liest Gitea #14. Sondern: was gilt, und dort wo eine Eigenheit teuer war, warum. Der Abschnitt behält seinen Platz, dreht aber das Vorzeichen um: aus „was uns noch blockiert" wird **was ein Gitea-Runner anders macht als ein GitHub-Runner**, mit den Messwerten. Neu aufgeschrieben, weil es dauerhaft gilt und bisher nirgends sauber stand: - **Die Matrix läuft nebenläufig in *einem* Job unter *einem* Status-Kontext.** Ein Pflicht-Check pro Chart ist damit unmöglich, und der Kontextname trägt den **unaufgelösten** Matrix-Ausdruck — die Namen müssen von einem echten Lauf abgelesen werden, nicht von GitHub kopiert. Das ist die Grundlage für jeden Eingriff in den Branch-Schutz und steht jetzt auch in `CLAUDE.md`. - **Laufzeiten als Erwartungswert**, damit eine spätere Abweichung auffällt — `Create k3d cluster` 19–25 s, zwei Charts nebenläufig 210–216 s bei 6 s Streuung über drei Läufe, freesailarr mit zehn Containern 225 s. Mit der Einordnung, dass der Unterschied zu GitHub **strukturell** ist (ein Runner für beide Zweige gegen eine VM je Zweig) und **nicht Leistung** — beim Cluster-Anlegen ist der Runner sogar leicht schneller. - **`aquasecurity/setup-trivy` ist unbrauchbar** und warum: die Action klont `aquasecurity/trivy` von github.com mit `github.token`, was hier ein *Gitea*-Token ist. - **Werkzeuge werden installiert, nicht geerbt** — kubectl gepinnt mit Skew-Wächter, `envsubst` nur bereitgestellt, samt Begründung für den Unterschied (die Version des einen ändert die Bedeutung des Tests, die des anderen nicht). - **Containerisierung wird erkannt, nicht aus der Plattform gefolgert**, weil ein selbstgehosteter GitHub-Runner im Container dasselbe Problem hätte. ## Die sechs Annahmen, aufgeteilt statt aufgelistet Fünf sind **Umgebungsannahmen** (MTU, `fs.inotify`, fehlendes kubectl und envsubst, kubeconfig auf `0.0.0.0`): sie scheitern laut, sagen nichts über unseren Code und werden auf der Knotenseite behoben (`cluster-config`). Kurz gehalten. Die sechste steht als eigener Block, weil sie als einzige etwas über **unseren Code** sagt: der fest verdrahtete Clustername war **auch auf GitHub falsch** und fiel dort nur nie auf, weil jeder Matrix-Zweig eine eigene VM bekommt. Mit der Lehre, die das trägt: > **A generous environment is no friend when you want to know whether something is correct.** ## Zwei Regeln, als Prüfregel statt als Erzählung 1. **Eine Prüfung, die ein kaputtes System besteht, ist schlechter als keine** — mit beiden hohlen Formen, die das verursacht haben (`kubectl get nodes` liefert 0 bei leerer Liste; `kubectl wait --for=condition=Ready nodes --all` ist bei null Knoten leer erfüllt). 2. **Grün heißt nicht geprüft** — mit Verweis auf **Gitea #24** (Fixture-Images ohne Renovate-Verfolgung) als offenen Fall derselben Art, ausdrücklich **nicht** als gelöst dargestellt. ## Ein Nebenbefund, der mir beim Schreiben aufgefallen ist Die Dateien sind dicht mit `#n` durchsetzt, und die Nummern zeigen jetzt ins Leere oder — schlimmer — auf etwas Falsches: - Die meisten benennen **geschlossene** GitHub-Issues (#22, #82, #157, #158, #214, #231, #68 …), die nie migriert wurden und nur dort existieren. - **Gitea löst ein blankes `#n` gegen den eigenen Zähler auf.** `#22` rendert hier als Link auf einen **nicht verwandten Wegwerf-PR** — nicht auf das Install-Test-Issue, das der Text meint. Genau die Falle, die der Rumpf von #14 vorhergesagt hat. Sechzehn Verweise auf Nummern umzuschreiben, die es nicht gibt, wäre falsch. Stattdessen steht es **einmal oben im README** und in `CLAUDE.md`: `#n` meint den GitHub-Tracker, die zum Umzug offenen Issues sind Gitea #5–#21 und #24, die Zuordnung hängt als Kommentar an Gitea #14 — und für **neue** Verweise gilt die Gitea-Nummer. ## Überschneidung mit dem offenen PR #25 **Keine.** Per `git merge-tree` gegengeprüft statt geschätzt: die beiden Zweige mergen in beiden Reihenfolgen konfliktfrei. #25 fasst im README die Zeilen 15, 119, 125, 127, 215, 227 und 321 an, dieser PR die Zeilen 5, 56–70, 111, 153, 157 und 161–164. **Es gibt keine nötige Reihenfolge.** Eine Abhängigkeit inhaltlicher Art bleibt und ist im Text gekennzeichnet: die Zeile „freesailarr mit zehn Containern, 225 s" ist auf dem Stand von #25 gemessen und trägt diesen Hinweis, damit sie nicht als Verhalten des heutigen `main` gelesen wird. ## Was ungemessen bleibt und auch so dasteht `/dev/fuse` und User-Namespaces. Sie standen nie im Weg — das ist nicht dasselbe wie geprüft, und es steht als ungemessen da.

jlab-bot added 1 commit 2026-09-17 17:14:29 +02:00

docs: describe what is, now that the move is done ... 60670182ff

The documentation still described a migration in progress, and the worst
line claimed the install-test "cannot run on Gitea at all" - true two
days ago, the opposite of true now, and exactly the sort of sentence
someone builds a wrong assumption on.

README and CLAUDE.md now state what holds: everything runs on Gitea,
github.com is a mirror with Actions and Renovate off, branch protection
with a signature requirement is active, and the tool is tea. The move
itself is not retold - that is Gitea #14.

"Where this repo lives" keeps its place but turns around: it is no
longer a list of what blocks us, it is what a Gitea runner does
differently from a GitHub one, with the measurements. Newly written
down because it holds permanently and stood nowhere: a matrix runs
concurrently in ONE job under ONE status context, so a required check
per chart is impossible and the context name carries the unexpanded
matrix expression; expected runtimes, so a later deviation is visible
as one, with the note that the difference to GitHub is structural - one
runner for both legs against a VM per leg - and not performance.

The six assumptions a GitHub runner had been meeting quietly are split
rather than listed. Five are environment (MTU, fs.inotify, missing
kubectl and envsubst, kubeconfig on 0.0.0.0): they fail loudly, say
nothing about our code, and are fixed on the node side. The sixth gets
its own block because it is the one that does say something about our
code - the hard-coded k3d cluster name was wrong on GitHub too and only
never showed there, because a VM per matrix leg meant two legs never saw
each other. A generous environment is no friend when you want to know
whether something is correct.

Two rules generalised out of this round, as rules rather than as a
story: a check that a broken system passes is worse than no check (with
the two vacuous forms that caused it), and green does not mean checked,
pointing at Gitea #24 as an open case of the same kind - explicitly not
claimed as solved.

Also fixes a hazard the move created: most #n in these files name closed
GitHub issues that were never migrated, while Gitea resolves a bare #n
against its own counter - #22 there is an unrelated throwaway pull
request, not the install-test issue the text means. Stated once at the
top instead of rewriting sixteen references into numbers that do not
exist.

jklein approved these changes 2026-09-17 17:16:23 +02:00

jklein merged commit 60670182ff into main 2026-09-17 17:16:29 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

jklein

Labels

Clear labels

inhouse-chart

Inhouse-Chart aus der JLab-Git-Paketregistry

renovate

Von Renovate angelegt

No labels

Milestone

No items

No Milestone

Assignees

Clear assignees

jklein (Justin Klein) jlab-bot (jlab-git-bot) jlab-renovate-bot (jlab-renovate-bot)

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: jlab-cluster/helm-charts#26