Manueller Einsatz

Diese Anleitung zeigt den vollständigen Ablauf auf dem eigenen Mac: Projekt einrichten, beim Entwickeln prüfen, vor dem Commit prüfen, vor dem Merge Request prüfen.

Voraussetzungen

• CodeGuard ist installiert, die Organisationsrichtlinie ist eingerichtet und codeguard doctor meldet ready: true (siehe Erste Schritte).
• Dein Projekt ist ein Git-Repository, und du arbeitest in dessen Wurzelverzeichnis. check-diff verlangt, dass Projektwurzel und Repository-Wurzel identisch sind.

Schritt 1: Projekt einrichten

1. Wechsle in das Wurzelverzeichnis:

   cd ~/Developer/MeinProjekt

2. Prüfe, was CodeGuard dort findet:

   codeguard doctor

   compile und tests sollten active sein, sobald ein Package.swift oder Xcode-Projekt im Verzeichnis liegt. Unter platform.* und simulator.* siehst du, welche Plattformen du bauen und testen kannst.

3. Lege bei Bedarf eine .codeguard.yml an. Beispiele je Plattform stehen unter Konfigurationsbeispiele. Prüfe sie:

   codeguard config validate

4. Optional: Lege eine .swift-format ins Wurzelverzeichnis, wenn dein Projekt einen anderen Stil als die swift-format-Standards nutzt (siehe Prüfungen und Regeln).

5. Erteile Vertrauen, damit CodeGuard bauen und testen darf:

   codeguard trust grant --duration 8h

   Prüfe die angezeigten Ausführungsoberflächen, bevor du yes eingibst.

6. Committe .codeguard.yml und .swift-format, damit dein Team und die CI dieselbe Konfiguration nutzen.

vorsicht

Jede Änderung an .codeguard.yml macht dein Trust-Ticket ungültig. Führe danach codeguard trust grant erneut aus.

Schritt 2: Beim Entwickeln einzelne Dateien prüfen

check-file ist der schnellste Lauf. Er baut und testet nie und braucht kein Trust-Ticket.

codeguard check-file Sources/App/Session.swift

Echtes Ergebnis für eine Datei mit try!, as!, fatalError und einem geloggten Passwort:

CODEGUARD_FAILED

6 blocking violations found in 1 changed files.
Validation: file (complete)
Exit: 1 (validation_failed)
Requested: format, security, swiftlint
Completed: format, security, swiftlint
Skipped: 
Tool: swift-format main [tool_swift_format] completed, 9ms, truncated: false
Tool: swiftlint 0.65.1 [tool_swiftlint] completed, 53ms, truncated: false
Run: cg_0ab81208-c7d2-4d65-9e63-3fb0ac640112

1. CRITICAL Sources/SwiftPMClean/Session.swift:8:9
   Rule: sensitive-data-in-log
   Possible password is written to a log.
   Do not log credentials or secrets; log a non-sensitive identifier or omit the value.

2. ERROR Sources/SwiftPMClean/Session.swift:7:22
   Rule: forbidden-force-try
   `try!` can crash the application.
   Handle the error explicitly with `do`/`catch`, or propagate it with `try`.

3. ERROR Sources/SwiftPMClean/Session.swift:7:22
   Rule: swiftlint.force_try
   [force_try] Force tries should be avoided

4. ERROR Sources/SwiftPMClean/Session.swift:9:23
   Rule: forbidden-force-cast
   A forced cast can terminate the process.
   Use a conditional cast (`as?`) and handle the failure case.

5. ERROR Sources/SwiftPMClean/Session.swift:9:23
   Rule: swiftlint.force_cast
   [force_cast] Force casts should be avoided

6. ERROR Sources/SwiftPMClean/Session.swift:13:74
   Rule: forbidden-fatal-error
   `fatalError` terminates the process.
   Throw an error or return a failure result instead of terminating the process.

Next action: Fix the reported violations and run `codeguard check-diff` again.

Behebe die Funde von oben nach unten. Jede Zeile Datei:Zeile:Spalte führt dich zur Stelle.

Schritt 3: Vor dem Commit

Prüfe, was du committen willst:

git add Sources/App/Session.swift
codeguard check-diff --staged

Aufruf	Welche Dateien gelten als geändert
check-diff --staged	gestagte Änderungen (Index gegenüber HEAD)
check-diff	nicht gestagte Änderungen (Arbeitsverzeichnis gegenüber Index)
check-diff --base HEAD --include-untracked	alles seit dem letzten Commit, inklusive neuer, noch nicht hinzugefügter Dateien

Gelesen wird immer das Arbeitsverzeichnis

Git liefert nur die Liste der geänderten Dateien und Zeilen. Den Inhalt liest CodeGuard aus dem Arbeitsverzeichnis, und auch Build und Tests nutzen das Arbeitsverzeichnis. Hast du nach git add weiter editiert, prüft --staged den aktuellen Dateiinhalt.

check-diff baut und testet (Standardkonfiguration). Ein Lauf mit Simulator-Tests dauert deutlich länger als check-file.

Schritt 4: Vor dem Push oder Merge Request

Prüfe alle Änderungen deines Branches gegenüber dem Ziel-Branch, inklusive neuer Dateien:

git fetch origin
codeguard check-diff --base origin/main --include-untracked

• --base vergleicht den genannten Stand mit dem Arbeitsverzeichnis.
• Fehlt die Referenz lokal, endet der Lauf mit Exit 2 (missingBase). Ein Commit-SHA, dessen Objekt fehlt, ist Exit 3.
• Ist ein Name mehrdeutig (gleichnamiger Branch und Tag), ist das Exit 2. Nutze dann den vollen Namen, z. B. refs/remotes/origin/main.

Ein grüner Lauf mit Build und Tests eines Swift Packages:

CODEGUARD_PASSED

0 blocking violations found in 1 changed files.
Validation: file (complete)
Exit: 0 (completed)
Requested: compile, format, security, swiftlint, swiftlint_metrics, tests
Completed: compile, format, security, swiftlint, swiftlint_metrics, tests
Skipped: 
Konfiguration: .codeguard.yml (auto, sha256 5967f32a…)
Tool: swift-format main [tool_swift_format] completed, 9ms, truncated: false
Tool: swiftlint 0.65.1 [tool_swiftlint] completed, 74ms, truncated: false
Tool: swiftlint 0.65.1 [tool_swiftlint_metrics] completed, 74ms, truncated: false
Tool: swift-package-manager 6.4.0-dev [tool_swiftpm_build] completed, 2611ms, truncated: false
Tool: swift-package-manager 6.4.0-dev [tool_swiftpm_test] completed, 3871ms, truncated: false
Run: cg_f5fb110f-22c5-4df5-9dd3-c302dffe4f4b

Achte auf Completed: Erst wenn compile und tests dort stehen, wurde wirklich gebaut und getestet.

Schritt 5: Ganzes Projekt prüfen

codeguard check-project

check-project prüft alle Dateien in paths.include, baut alle Plattformen und testet. Das eignet sich für einen Lauf vor einem Release oder nachts.

Berichte als Datei speichern

mkdir -p build
codeguard --format json  --output build/codeguard.json  check-diff --base origin/main
codeguard --format sarif --output build/codeguard.sarif check-diff --base origin/main

• Mit --output bleibt die Konsole leer. Der Exit-Code ist derselbe wie ohne --output.

• Jeder Aufruf ist ein vollständiger Lauf. Zwei Formate bedeuten zwei Läufe, inklusive Build und Tests.

• Für eigene Auswertungen mit jq:

  jq -r '.violations[] | "\(.severity) \(.file // "-"):\(.line // "-") \(.rule)"' build/codeguard.json

Häufige Situationen

Meldung	Ursache und Lösung
Exit: 6 (security_policy) mit codeguard-build-execution-denied	Kein oder ungültiges Trust-Ticket. codeguard trust status prüfen, dann codeguard trust grant.
Exit: 6 (scope_violation) mit path-outside-allowed-scope	Datei liegt außerhalb von paths.include oder in paths.exclude. Pfad prüfen oder paths.include erweitern.
Exit: 6 (protected_file) mit protected-file-change	Der Diff ändert eine geschützte Datei, z. B. Package.swift. Das ist beabsichtigt und braucht menschliche Prüfung.
Exit: 3 mit codeguard-simulator-selection-failed	Keine Simulator-Runtime für die Plattform. Runtime installieren oder tests per scopes: [] herausnehmen.
Exit: 3 mit codeguard-dependency-unavailable	Werkzeug fehlt, oder das Paket hat Remote-Abhängigkeiten, die offline nicht ladbar sind.
Konfiguration: Standardwerte (--no-project-config)	Du hast die Projektkonfiguration bewusst abgeschaltet. Lass --no-project-config weg.

Mehr unter Häufige Fragen.

Siehe auch

• Kommandos und Parameter
• Berichte lesen
• Trust und Sicherheit