CI und lokale Prüfungen identisch halten: ein Einstiegspunkt, festgepinnte Werkzeuge, derselbe Container

Ziel

Eine Prüfung, die lokal besteht, besteht auch in der CI, und umgekehrt, sodass „Lint reparieren"-Commits, nur in der CI auftretende Fehlschläge und Streitigkeiten über „bei mir funktioniert es" verschwinden und ein Agent seinem lokalen Lauf als Vorhersage der Pipeline vertrauen kann.

Voraussetzungen

Ein Einstiegspunkt im Task-Runner für jede Prüfung (siehe den verwandten Artikel), ein Versionsmanifest für die Toolchain sowie ein CI-Dienst, der ein selbst gewähltes Container-Image ausführen kann. GitHub Actions dokumentiert, die Schritte eines Jobs innerhalb eines mit container: und einem image: deklarierten Containers auszuführen; asdf liest Tool-Versionen aus einer Datei .tool-versions und installiert alles darin Aufgeführte mit asdf install; mise liest dieselbe Datei oder eine mise.toml mit einem Abschnitt [tools].

Schritte

1. Jede Prüfung einmal als benannte Aufgabe definieren (lint, typecheck, test, build) und den CI-Workflow nur diese Namen aufrufen lassen. Wo die CI abweichendes Verhalten braucht (kein Watch-Modus, maschinenlesbare Ausgabe), einen Schalter hinzufügen, den die Aufgabe entgegennimmt, statt eines zweiten Befehls.
2. Die Toolchain in einem im Repository committeten Manifest festpinnen (.tool-versions, mise.toml oder das Dockerfile des Dev-Containers) und sowohl den lokalen Bootstrap als auch den CI-Job daraus installieren lassen; nie latest.
3. Die CI im selben Container-Image ausführen, das die Entwicklungsumgebung nutzt, oder das Image in der CI aus demselben Dockerfile bauen, damit auch die Betriebssystempakete übereinstimmen.
4. Die prüfenden Werkzeuge (Formatter, Linter, Test-Runner) in der Lock-Datei des Projekts festpinnen statt sie global zu installieren, und sie über die Aufgabe aufrufen, sodass nur die festgelegte Version laufen kann.
5. Umgebungsunterschiede beseitigen: Codepfade vermeiden, die sich unterschiedlich verhalten, wenn eine Variable CI gesetzt ist, Locale und Zeitzone innerhalb der Aufgabe fixieren (LC_ALL=C.UTF-8, TZ=UTC), und Caches als optionale Eingaben statt als Voraussetzung behandeln.
6. Einen geplanten Job hinzufügen, der die vollständige Prüfmenge aus einem sauberen Checkout im Container ohne jeden Cache ausführt; er fängt Prüfungen ab, die nur wegen verbliebenem Zustand lokal bestehen.
7. Scheitert die CI, während lokal alles besteht, den Unterschied als den eigentlichen Fehler behandeln: die Abweichung (Version, Umgebungsvariable, fehlende Datei) festhalten und beseitigen, bevor das Symptom behoben wird.

Erwartetes Ergebnis

Die Workflow-Datei ist kurz: auschecken, aus dem Manifest installieren, die benannten Aufgaben ausführen. Ein Beitragender reproduziert jeden CI-Fehlschlag mit demselben Befehlsnamen, und CI-Zeit fliesst in die Prüfungen statt in Setup-Drift.

Grenzen und Prüfbasis

Hardwareabhängiges Verhalten (CPU-Anzahl, Speichergrenzen, GPU) unterscheidet sich weiterhin und zeigt sich in zeitkritischen Tests. Geheimnisse und Dienst-Zugangsdaten unterscheiden sich naturgemäss; Prüfungen, die sie brauchen, gehören ausserhalb der Paritätsmenge. Dies ist ein vorgeschlagenes, auf der zitierten Dokumentation aufbauendes Vorgehen; es werden keine Fehlerraten behauptet.

Die Prüfungen auf beiden Seiten im CI-Modus ausführen

Viele Werkzeuge ändern ihr Verhalten bereits, wenn die Umgebungsvariable CI gesetzt ist: Test-Runner hören auf, neue Snapshots zu schreiben, und deaktivieren den Watch-Modus, Paketmanager verweigern Änderungen an der Lock-Datei, und generierte Testkonfigurationen verbieten fokussierte Tests. Diese Verzweigungen lassen sich nicht entfernen, weshalb die Paritätsregel umgekehrt lautet, als sie zu vermeiden: Die Aufgabe, die die Prüfmenge ausführt, setzt selbst CI=true, sodass der lokale Lauf und die Pipeline in jedem Drittanbieter-Werkzeug dieselben Verzweigungen nehmen. Der eigene Code des Projekts sollte gar nicht nach CI verzweigen. Eine Prüfung, die ohne die Variable besteht und mit ihr scheitert, ist dann lokal mit demselben Befehl reproduzierbar.