CI Integration

SensorChaos is designed to run in CI. The CLI exits with code 1 when assertions fail, reports are machine-readable JSON, and the agent works inside emulators and simulators on standard hosted runners.

Ready-made templates live in the repository under examples/:

examples/
  github-actions/
    sensorchaos-android.yml   # Android emulator on ubuntu-latest
    sensorchaos-ios.yml       # iOS simulator on macos-latest
  gitlab-ci/
    sensorchaos.gitlab-ci.yml # Android + iOS jobs

Setup

1. Add your license key as a CI secret

GitHub Actions
GitLab CI

Go to Settings → Secrets and variables → Actions → New repository secret:

Name	Value
`SENSORCHAOS_KEY`	Your `sc_live_...` or `sc_trial_...` key

Go to Settings → CI/CD → Variables → Add variable:

Key	Value	Flags
`SENSORCHAOS_KEY`	Your `sc_live_...` or `sc_trial_...` key	Masked ✓

2. Copy the template

Copy examples/github-actions/sensorchaos-android.yml to .github/workflows/ in your app repository. Then update the two placeholders marked with comments:

# Replace with your APK build command
- name: Build debug APK
  run: ./gradlew assembleDebug --no-daemon

# Replace with your APK path and app package name
- adb install -r app/build/outputs/apk/debug/app-debug.apk
- adb shell am start -n com.example.yourapp/.MainActivity

Copy examples/github-actions/sensorchaos-ios.yml to .github/workflows/. Update the Xcode scheme and bundle ID:

# Replace YourAppScheme with your Xcode scheme
xcodebuild build -scheme YourAppScheme ...

# Replace with your app's bundle identifier
xcrun simctl launch "$UDID" com.example.yourapp

The simulator runtime in the template targets iOS 17.5 on iPhone 15. Adjust SimDeviceType and SimRuntime to match your minimum deployment target — list available options with xcrun simctl list.

Merge the jobs from examples/gitlab-ci/sensorchaos.gitlab-ci.yml into your .gitlab-ci.yml, or include the file directly:

include:
  - local: path/to/sensorchaos.gitlab-ci.yml

The Android job requires a self-hosted runner with KVM access (tagged kvm). The iOS job requires a macOS runner with Xcode (tagged macos, xcode) — GitLab-hosted saas-macos-medium-m1 runners work.

3. Choose your scenarios and assertions

Edit the sensorchaos suite call to match your test requirements:

sensorchaos suite \
  --scenarios gnss/gulf-spoofing-2026,gnss/urban-canyon \
  --agent \
  --assert-max-position-error-km 5 \
  --assert-no-crash \
  --report sensorchaos-report.json \
  --exit-code-on-fail \
  --no-progress

Flag	What it checks
`--assert-max-position-error-km <km>`	Fails if the app reports a position more than `<km>` from the baseline. Useful for detecting spoofing acceptance.
`--assert-no-crash`	Fails if any critical findings are recorded (app crash or unhandled signal loss).
`--exit-code-on-fail`	Required to actually fail the CI job on assertion violations.
`--no-progress`	Suppresses the interactive progress bar — always use this in CI.

Run a single scenario instead of a suite with sensorchaos run:

sensorchaos run gnss/gulf-spoofing-2026 \
  --agent \
  --assert-max-position-error-km 5 \
  --report report.json \
  --exit-code-on-fail \
  --no-progress

Report artifact

Both templates upload sensorchaos-report.json as a CI artifact on every run (including failures). The JSON report contains the full event timeline, resilience score, and per-assertion breakdown — useful for tracking score trends across releases.

Runner requirements

Platform	Runner	Notes
Android emulator	`ubuntu-latest` (GitHub) / self-hosted Linux + KVM (GitLab)	KVM must be available for hardware acceleration. GitHub-hosted runners include KVM support.
iOS simulator	`macos-latest` (GitHub) / `saas-macos-medium-m1` (GitLab)	Xcode must be installed.