Konfigurationsbeispiele

Hier findest du je Projektart eine passende .codeguard.yml, dazu, wie CodeGuard das Projekt baut und testet und wie ein echter Lauf aussah. Jede Konfiguration auf dieser Seite wurde mit codeguard 0.3.5 config validate geprüft.

Wenig konfigurieren

Viele Projekte brauchen nur version: 1. CodeGuard erkennt Projektart und Plattformen selbst. Konfiguriere vor allem paths, wenn deine Ordner nicht Sources/ und Tests/ heißen, und rules.metrics, wenn du Metriken willst.

Wie CodeGuard Plattformen auswählt

Erkennen: Xcode-Projekte über xcodebuild -showdestinations des Schemes, Swift Packages über platforms: im Manifest (ohne Angabe: nur macOS).
Verfügbarkeit: Das Simulator-SDK muss lokal installiert sein (codeguard doctor zeigt platform.<name>).
Einschränken: Ist project.platforms gesetzt, baut CodeGuard nur die Schnittmenge.
Testen: macOS nativ, alle anderen Plattformen auf Wegwerf-Simulatoren. Dafür muss eine Simulator-Runtime installiert sein (simulator.<name> in doctor).

Plattform	Build-Ziel	Testziel(e) im Bericht	Text im Bericht
`macos`	`platform=macOS,arch=<Host>`	`macos`	macOS
`ios`	`generic/platform=iOS Simulator`	`ios-phone`, bei iPad-fähigen Xcode-Targets zusätzlich `ios-pad`	iOS/iPadOS bzw. iOS/iPhone, iOS/iPad
`watchos`	`generic/platform=watchOS Simulator`	`watchos`	watchOS
`tvos`	`generic/platform=tvOS Simulator`	`tvos`	tvOS
`visionos`	`generic/platform=visionOS Simulator`	`visionos`	visionOS

macOS

Swift Package für macOS

Ein Paket ohne platforms: im Manifest wird als macOS-Paket gebaut (swift build) und getestet (swift test). Diese Konfiguration ergänzt Metriken und eine eigene Regel:

version: 1
rules:
  metrics:
    line_length: { warning: 120, error: 160 }
    function_body_length: { warning: 40, error: 80 }
custom_rules:
  - id: no-debug-print
    engine: regex
    severity: warning
    scopes: [file, diff, project]
    autofix: false
    paths: { include: ["Sources/**"], exclude: [] }
    pattern: "debugPrint\\("
    message: "debugPrint gehört nicht in Produktionscode."
    suggestion: "Logger verwenden."

Echter Lauf mit Trust-Ticket, nach einer sauberen Änderung:

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

macOS-App (Xcode)

version: 1
project:
  kind: xcode
  xcode:
    project: MyMacApp.xcodeproj
    scheme: MyMacApp
    configuration: Debug
  platforms: [macos]
paths:
  include: ["MyMacApp/**", "MyMacAppTests/**"]
  exclude: [".build/**", "DerivedData/**", "Vendor/**", ".git/**"]
rules:
  macos-app-sandbox-missing:
    severity: error
  entitlement-get-task-allow-release:
    severity: error

kind: xcode und die xcode-Angaben sind nötig, wenn das Repository mehrere Projekte oder Schemes hat. Sonst findet CodeGuard Container und geteiltes Scheme selbst.
paths.include deckt die Ordner der App ab. Ohne Anpassung prüfen format, swiftlint und die Inhaltsregeln nur Sources/ und Tests/.
Die beiden Regeln machen fehlende App Sandbox und get-task-allow in Release zu blockierenden Funden. Für Apps außerhalb des App Store ist ein Waiver der vorgesehene Weg.

Echte Plattformfunde aus einer macOS-App ohne Sandbox und mit disable-library-validation (Standard-Schwere warning):

2. WARNING App.entitlements
   Rule: entitlement-weakens-hardened-runtime
   Entitlement com.apple.security.cs.disable-library-validation is true, weakening the hardened runtime.
   Remove com.apple.security.cs.disable-library-validation unless the target has a specific, documented need for it.

3. WARNING App.entitlements
   Rule: macos-app-sandbox-missing
   Target "App" configuration "Debug" does not set com.apple.security.app-sandbox = true.
   Set com.apple.security.app-sandbox to true, or waive this rule for non-App-Store distribution.

4. WARNING App.entitlements
   Rule: macos-app-sandbox-missing
   Target "App" configuration "Release" does not set com.apple.security.app-sandbox = true.
   Set com.apple.security.app-sandbox to true, or waive this rule for non-App-Store distribution.

Mit einem Waiver für den Debug-Fund bleibt der Fund sichtbar, zählt aber als akzeptiertes Risiko (summary.accepted_risk: 1, disposition: accepted_risk). Das Beispiel steht unter Projektkonfiguration.

iOS und iPadOS

version: 1
project:
  kind: xcode
  xcode:
    workspace: MyApp.xcworkspace
    scheme: MyApp
    configuration: Debug
  platforms: [ios]
  test_destinations:
    ios: { device_type: "iPhone 18 Pro", runtime: "27.0" }
    ipad: { runtime: latest }
checks:
  tests: { simulator: true, ipad: true }
paths:
  include: ["MyApp/**", "MyAppTests/**"]
  exclude: [".build/**", "DerivedData/**", "Pods/**", ".git/**"]
rules:
  purpose-string-missing: { severity: critical }
  ats-arbitrary-loads: { severity: error }

iPad-Lauf: Enthält TARGETED_DEVICE_FAMILY eines iOS-Targets den Wert 2, testet CodeGuard zusätzlich auf einem iPad. checks.tests.ipad: false schaltet das ab.
test_destinations: Ohne Angabe wählt CodeGuard die neueste Runtime ≥ Deployment-Target und den ersten passenden Gerätetyp der Präferenzliste. Ein erzwungenes Ziel, das nicht erfüllbar ist, beendet den Lauf mit Exit 3. Die Gerätenamen hängen von deiner Xcode-Version ab, codeguard doctor zeigt den automatisch gewählten iPhone-Typ.
Pods: Pods/** im Exclude nimmt das CocoaPods-Projekt auch aus den Plattform-Checks heraus.

Echter Lauf einer iOS-App mit iPad-Unterstützung ohne Konfiguration, ein Test schlägt fehl:

CODEGUARD_FAILED

1 blocking violations found in 3 changed files.
Validation: project (complete)
Exit: 1 (validation_failed)
Requested: compile, format, platform, security, swiftlint, tests
Completed: compile, format, platform, security, swiftlint, tests
Skipped: 
Plattformen: gebaut iOS/iPadOS
Simulatortests: getestet iOS/iPhone iPhone 18 Pro (Runtime 27.0), iOS/iPad iPad Pro 13-inch (M5) (16GB) (Runtime 27.0)
Tool: xcodebuild 1171.7.0 [tool_simctl_bootstatus] completed, 21870ms, truncated: false
…
Tool: xcodebuild 27.0.0 [tool_xcodebuild_test_ios_phone] completed, 13341ms, truncated: false
…
Run: cg_703370af-9cf1-4109-8175-b687b0c701ce

1. [iOS/iPhone, iOS/iPad] ERROR Tests/AppTests.swift:8:1
   Rule: swift-test-failure
   Expectation failed: 1 == 2

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

Der Lauf dauerte durch das Booten zweier Simulatoren deutlich länger als ein macOS-Lauf (bootstatus rund 21 s je Gerät auf dem Referenzrechner).

tvOS

version: 1
project:
  kind: xcode
  xcode:
    project: MyTVApp.xcodeproj
    scheme: MyTVApp
  platforms: [tvos]
  test_destinations:
    tvos: { runtime: latest }
paths:
  include: ["MyTVApp/**", "MyTVAppTests/**"]
  exclude: [".build/**", "DerivedData/**", "Vendor/**", ".git/**"]

Gebaut wird gegen generic/platform=tvOS Simulator, getestet auf einem Wegwerf-Simulator (Ziel tvos, Gerätetyp nach Präferenzliste: Apple TV 4K).
Voraussetzung ist eine installierte tvOS-Simulator-Runtime. Fehlt sie, wird das Testziel übersprungen. Ist tvOS die einzige gebaute Plattform, endet der Lauf mit Exit 3, wie im watchOS-Beispiel unten gezeigt.

hinweis

Für tvOS und visionOS gibt es in dieser Hilfe keinen echten Testlauf: Auf dem Referenzrechner war keine Runtime dafür installiert, und laut den CodeGuard-Verifikationsunterlagen wurden Simulator-Tests für watchOS, tvOS und visionOS bisher nicht auf einem echten Simulator ausgeführt. Build und Plattformauswahl folgen derselben Logik wie bei iOS.

watchOS

version: 1
project:
  kind: xcode
  xcode:
    project: MyApp.xcodeproj
    scheme: MyWatchApp
  platforms: [watchos]
  test_destinations:
    watchos: { runtime: latest }
paths:
  include: ["MyWatchApp/**", "MyWatchAppTests/**"]
  exclude: [".build/**", "DerivedData/**", "Vendor/**", ".git/**"]

Gebaut wird gegen generic/platform=watchOS Simulator, getestet auf dem Ziel watchos (Gerätetyp: größte Watch der Präferenzliste).
Eine Watch-App hebt das Deployment-Target des iOS-Teils nicht an. CodeGuard wertet das Deployment-Target je Plattform aus.

Echter Lauf einer watchOS-App auf einem Rechner ohne watchOS-Runtime: Der Build gelingt, die Tests können nicht laufen.

CODEGUARD_ERROR

1 blocking violations found in 3 changed files.
Validation: project (partial)
Exit: 3 (dependency_unavailable)
Requested: compile, format, platform, security, swiftlint, tests
Completed: compile, format, platform, security, swiftlint
Skipped: tests
Plattformen: gebaut watchOS
Simulatortests: übersprungen watchOS (simulatorUnavailable)
…
1. ERROR
   Rule: codeguard-simulator-selection-failed
   checks.tests.required is set, but no test target can run on this host; no test ran.
   Install a simulator runtime for a detected platform, or set checks.tests.required: false.

2. WARNING
   Rule: codeguard-simulator-unavailable
   No usable watchOS simulator runtime or device type with deployment target 10.0; its tests were skipped. There are no installed watchOS simulator runtimes.

So löst du das:

Runtime installieren (empfohlen), dann prüft codeguard doctor erneut: simulator.watchos: available.
Oder Tests aus dem Projekt heraus nehmen: checks: { tests: { scopes: [] } }.
Oder, organisationsweit, checks.tests.required: false in der Organisationsrichtlinie sperren. Dann ist das fehlende Ziel nur noch eine Warnung.

Swift Packages

Paket für mehrere Plattformen

version: 1
project:
  kind: swift-package
  package_path: Package.swift
  platforms: [macos, ios]
rules:
  metrics:
    line_length: { warning: 120, error: 160, ignores_urls: true }
    cyclomatic_complexity: { warning: 10, error: 20 }
    function_body_length: { warning: 40, error: 80 }
    nesting: { type_level: { warning: 2 }, function_level: { warning: 3 } }

macOS baut und testet SwiftPM (swift build, swift test).
iOS, watchOS, tvOS, visionOS baut xcodebuild auf einer Kopie des Pakets mit dem Paket-Scheme (<Paketname>-Package, sonst das einzige Scheme, sonst project.xcode.scheme). Gibt es mehrere Schemes und keine Angabe, ist das Exit 2.
Pakete bekommen keinen iPad-Lauf.
project.platforms darf Plattformen nennen, die das Manifest nicht unter platforms: aufführt. Mit [macos, ios] testet CodeGuard ein iOS-Paket zusätzlich nativ auf macOS.

Remote-Abhängigkeiten

swift build läuft offline mit leerem Abhängigkeits-Cache. Hat das Paket Abhängigkeiten von entfernten Repositories, kann SwiftPM sie nicht laden. compile meldet dann codeguard-dependency-unavailable und der Lauf endet mit Exit 3. Die übrigen Prüfungen laufen. Ein Weg, Abhängigkeiten offline bereitzustellen, existiert in 0.3.5 noch nicht. Bis dahin nimmst du compile und tests für solche Pakete mit scopes: [] heraus.

Reines iOS-Paket

Ein Paket mit platforms: [.iOS(.v17)] und ohne Konfiguration baut CodeGuard nur für iOS und testet auf einem iPhone-Simulator. Echter Lauf:

CODEGUARD_FAILED

2 blocking violations found in 3 changed files.
Validation: project (complete)
Exit: 1 (validation_failed)
Requested: compile, format, security, swiftlint, tests
Completed: compile, format, security, swiftlint, tests
Skipped: 
Plattformen: gebaut iOS/iPadOS
Simulatortests: getestet iOS/iPhone iPhone 18 Pro (Runtime 27.0)
…
Tool: swift-package-manager 6.4.0-dev [tool_swiftpm_dump_package] completed, 609ms, truncated: false
Tool: xcodebuild 27.0.0 [tool_xcodebuild_build_ios] completed, 1483ms, truncated: false
Tool: xcodebuild 27.0.0 [tool_xcodebuild_list] completed, 1022ms, truncated: false
…
1. ERROR Sources/IOSPackageTests/IOSPackageTests.swift:1:19
   Rule: swiftlint.identifier_name
   [identifier_name] Variable name 'a' should be between 3 and 40 characters long

2. ERROR Sources/IOSPackageTests/IOSPackageTests.swift:1:29
   Rule: swiftlint.identifier_name
   [identifier_name] Variable name 'b' should be between 3 and 40 characters long

3. WARNING Package.swift:10:85
   Rule: swiftlint.trailing_comma
   [trailing_comma] Collection literals should not have trailing commas

Build und Tests waren grün. Blockiert haben die SwiftLint-Funde mit Schwere error.

Alle Plattformen, automatisch

version: 1
project:
  kind: auto
  platforms: [macos, ios, watchos, tvos, visionos]
  test_destinations:
    ios: { runtime: latest }
    visionos: { runtime: latest }

platforms ist hier eine Obergrenze: Gebaut wird, was das Projekt unterstützt und in der Liste steht. Bei Xcode-Projekten ist eine Plattform, die das Scheme nicht kennt, aber Exit 2. Lass project.platforms dann weg, um alles Erkannte zu bauen.
Jede genannte Plattform braucht ihr SDK, sonst endet der Lauf mit Exit 3.
Ein Eintrag in test_destinations erzwingt das Ziel: Fehlt die Runtime, ist das Exit 3 statt eines übersprungenen Ziels.

Nur statische Prüfungen

Für Projekte, in denen Build und Tests (noch) nicht laufen sollen, etwa wegen Remote-Abhängigkeiten:

version: 1
checks:
  compile: { scopes: [] }
  tests:   { scopes: [] }

Dann laufen security, platform, format, swiftlint und gegebenenfalls swiftlint_metrics. Ein Trust-Ticket ist nicht nötig.

Wie CodeGuard Plattformen auswählt​

macOS​

Swift Package für macOS​

macOS-App (Xcode)​

iOS und iPadOS​

tvOS​

watchOS​

Swift Packages​

Paket für mehrere Plattformen​

Reines iOS-Paket​

Alle Plattformen, automatisch​

Nur statische Prüfungen​

Siehe auch​