CI Pipeline Guide

Kennst du das? Du pushst deinen Code und wartest ewig auf das Feedback der CI, nur um am Ende festzustellen, dass ein kleiner Formatierungsfehler oder ein vergessener Link alles aufgehalten hat. Es ist frustrierend, wenn teure Tests laufen, obwohl die Basics noch nicht stimmen.

Unsere CI Pipeline ist so aufgebaut, dass du schnellstmöglich Rückmeldung bekommst. Sie nutzt smartes Scoping, um unnötige Jobs zu überspringen, wenn du zum Beispiel nur die Docs bearbeitest.

Voraussetzungen

• Zugriff auf den main Branch oder einen Pull Request
• Installiertes pnpm für lokale Checks

Schnellstart

Die CI startet automatisch bei jedem Push auf main oder in einem Pull Request. Um Zeit und Ressourcen zu sparen, folgen die Jobs einer Fail-Fast-Logik in drei Stufen:

1. Schnelle Checks: Zuerst laufen docs-scope, code-analysis und check parallel. Das dauert etwa 1 bis 2 Minuten.
2. Build: Wenn die ersten Checks erfolgreich sind, wird der Job build-artifacts gestartet.
3. Spezifische Tests: Erst danach laufen die Tests für Node, Windows, macOS und Android.

Lokal kannst du die wichtigsten Checks so ausführen:

pnpm check          # types + lint + format
pnpm test           # vitest tests
pnpm check:docs     # docs format + lint + broken links
pnpm release:check  # validate npm pack

Job Overview

Hier siehst du, welcher Job was genau macht:

Job	Zweck	Wann er läuft
docs-scope	Erkennt reine Dokumentationsänderungen	Immer
changed-scope	Erkennt geänderte Bereiche (node/macos/android)	PRs (außer reine Docs)
check	TypeScript types, lint, format	Änderungen (außer Docs)
check-docs	Markdown lint + Broken Link Check	Wenn Docs geändert wurden
code-analysis	LOC Threshold Check (1000 Zeilen)	Nur in PRs
secrets	Findet geleakte Secrets	Immer
build-artifacts	Baut dist einmalig für andere Jobs	Node-Änderungen
release-check	Validiert npm pack Inhalte	Nach dem Build
checks	Node/Bun Tests + Protocol Check	Node-Änderungen
checks-windows	Windows-spezifische Tests	Node-Änderungen
macos	Swift lint/build/test + TS Tests	PRs mit macOS Änderungen
android	Gradle Build + Tests	Android-Änderungen

Code Analysis

Der Job code-analysis nutzt das Script scripts/analyze_code_files.py in PRs, um die Codequalität zu sichern:

• LOC Threshold: Dateien, die über 1000 Zeilen wachsen, lassen den Build fehlschlagen.
• Delta-only: Es werden nur Dateien geprüft, die du im PR geändert hast, nicht die gesamte Codebase.
• Push to main: Hier wird der Job übersprungen, damit Merges nicht blockiert werden.

Wenn --strict aktiviert ist, blockieren Verstöße alle nachfolgenden Jobs. So werden aufgeblähte Dateien abgefangen, bevor teure Tests starten.

Folgende Verzeichnisse werden ignoriert: node_modules, dist, vendor, .git, coverage, Swabble, skills, .pi.

Runners

Wir nutzen verschiedene Runner für die Jobs:

Runner	Jobs
blacksmith-4vcpu-ubuntu-2404	Die meisten Linux Jobs
blacksmith-4vcpu-windows-2025	checks-windows
macos-latest	macos, ios
ubuntu-latest	Scope Detection (leichtgewichtig)

Fehlerbehebung

Hier sind Lösungen für häufige Probleme in der CI:

• Problem: Der Build schlägt wegen des LOC-Thresholds fehl. Lösung: Verkleinere die Datei auf unter 1000 Zeilen, indem du Code in kleinere Module auslagerst.
• Problem: check-docs meldet Fehler. Lösung: Führe pnpm check:docs lokal aus, um kaputte Links oder Formatierungsfehler im Markdown zu finden und zu fixen.

Hast du Fragen zum Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Testing Guide
• Deployment Workflow