Spanda CI is split into three tiers so pull requests stay fast while main and nightly runs
retain full platform coverage.
| Workflow | File | When | Blocks merge? |
|---|---|---|---|
| CI Fast | .github/workflows/ci-fast.yml | Every PR and push to main |
Yes (required checks) |
| CI Integration | .github/workflows/ci-integration.yml | After CI Fast succeeds on main push |
Yes for main health (not individual PRs) |
| CI Nightly | .github/workflows/ci-nightly.yml | Daily cron + manual dispatch | No (signal only) |
Auto release (.github/workflows/auto-release.yml) waits for CI Integration success on
main, not nightly.
When the merged PR has a release:major|minor|patch label:
- Bumps workspace → tag
vX.Y.Z→ cargo-dist Release. - If Control Center paths changed (
scripts/control_center_paths_changed.sh), bumps desktop → tagdesktop-vX.Y.Z→ desktop-release.yml.
Manual ad-hoc bumps: Actions → Bump version (stream workspace or desktop). See control-center-versioning.md.
Runs on every pull request and every push to main.
| Job | Purpose |
|---|---|
lint-rust |
cargo fmt, clippy -D warnings, architecture + blueprint validation, registry index verify |
test-rust |
cargo test --workspace |
test-typescript |
npm test, npm run build |
test-python-sdk |
pytest in sdk/python |
test-ts-sdk |
npm test in sdk/typescript |
cross-surface-check |
scripts/check_cross_surface.sh |
build-spanda |
Release compile; uploads spanda-bin |
cross-interface |
scripts/cross_interface_consistency.sh using artifact (waits for test-rust) |
docs-validate |
Documentation audit when only docs/markdown changed |
Path filters: docs-only PRs skip Rust/TS/Python jobs and run docs-validate instead. Any change
under crates/, src/, sdk/, workflows, etc. runs the full fast gate.
build-spanda runs in parallel with test-rust (after lint-rust only) to shorten the PR
critical path.
Local parity:
./scripts/ci-fast.shOptional pre-push hook (fmt + cross-surface only):
./scripts/setup-githooks.shTriggered by workflow_run after CI Fast completes successfully on a main push.
Reuses the spanda-bin artifact from the triggering CI Fast run (required — no silent
rebuild; prepare-spanda fails if the artifact is missing). Manual workflow_dispatch may still
compile locally when no source run is provided.
Job prepare-spanda downloads from CI Fast when possible; docs-build waits on it and reuses the
artifact instead of compiling again.
Includes: readme smoke + golden output, core smokes, distributed decisions, cognitive resilience, release hardening security/property tests, key golden paths (robotics, telemetry, twin cloud, registry, ci-verify, killer demo), solution blueprint smokes, entity model smoke, entity mesh smoke, LSP, WASM, VS Code extension packaging, and docs/mdBook build.
Scheduled at 06:00 UTC and available via Actions → CI Nightly → Run workflow.
Reuses the spanda-bin artifact from the latest successful CI Integration run for the
checked-out
commit when available; otherwise tries CI Fast, then compiles locally. Job prepare-spanda
fetches or builds once; downstream jobs reuse the artifact.
Includes: cargo audit, promotion gates (Stable hardening scripts with soak/audit skipped in CI),
ROS 2, MQTT, LLVM, embedded cross-compile, live AI/IoT, Python native, desktop/Tauri builds, and
remaining tier-3 golden paths.
Nightly failures do not block PR merge or auto-release. Triage them like production monitoring alerts.
All three tiers share
.github/actions/fetch-or-build-spanda:
| Workflow | Binary source |
|---|---|
| CI Fast | Always compiles (source of truth for PRs and main pushes) |
| CI Integration | Downloads from the triggering CI Fast run (required on workflow_run; fails on miss) |
| CI Nightly | Downloads from latest green CI Integration for HEAD, then CI Fast; builds on miss |
Each workflow still uploads spanda-bin for its own downstream jobs via
.github/actions/with-spanda-bin.
Public API changes must land as one atomic PR across these layers:
| Step | Paths |
|---|---|
| 1. Proto | crates/spanda-api/proto/ |
| 2. Rust API + CLI | crates/spanda-api/src/, crates/spanda-cli/src/ |
| 3. TypeScript mirror | src/ (including AST types such as Program) |
| 4. SDKs | crates/spanda-sdk/, sdk/typescript/, sdk/python/ |
| 5. Cross-interface probe | scripts/cross_interface_consistency.sh, crates/spanda-api/tests/cross_interface_live.rs |
| 6. Docs | CHANGELOG.md, relevant guides |
scripts/check_cross_surface.sh enforces minimum coupling (proto → API → SDK) on every CI Fast run.
Under Settings → Branches → Branch protection for main, require these CI Fast checks on
pull requests:
lint-rusttest-rusttest-typescripttest-python-sdktest-ts-sdkcross-surface-checkcross-interface
Enable Require status checks to pass before merging and Require branches to be up to date before merging.
Optional (recommended): enable merge queue so integration runs against the exact merge commit. See GitHub merge queue.
Do not require nightly or integration jobs on PRs — integration runs after merge to main.
Monitor main health via CI Integration workflow status. Do not push new feature work while CI
Integration is red.
- Run
./scripts/ci-fast.shlocally before opening a PR. - Do not merge PRs with failing CI Fast checks.
- If
mainis red after merge, fix fmt/compile/cross-surface before stacking more commits. - Auto-release only fires after CI Integration succeeds — do not tag manually while integration is failing.
npm install && npm run build:rust
./scripts/ci-fast.shGate script index: scripts/gates/README.md.
Related: ci-verify.md (customer CI for spanda verify),
troubleshooting.md,
tier-3-golden-paths.md (golden path job index).
Use this table when updating docs or stable-hardening guides. Workflow file names are stable; job names match GitHub Actions UI.
| Job | Script / check |
|---|---|
lint-rust |
fmt, clippy, architecture, blueprints, registry index |
test-rust |
cargo test --workspace |
test-typescript |
npm test, npm run build |
test-python-sdk |
pytest sdk/python |
test-ts-sdk |
npm test in sdk/typescript |
cross-surface-check |
scripts/check_cross_surface.sh |
build-spanda |
cargo build -p spanda --release → artifact |
cross-interface |
scripts/cross_interface_consistency.sh |
docs-validate |
validate_documentation.py (docs-only PRs) |
| Job | Script / check |
|---|---|
prepare-spanda |
fetch-or-build-spanda (require-download from triggering CI Fast run) → artifact |
core-smokes |
readiness_smoke, sdk_smoke, check_all_examples, readme smoke + golden |
docs-build |
cargo doc, mdBook, generate_spanda_reference.py |
distributed-decisions |
distributed_decisions_smoke.sh |
bio-inspired-autonomy (cognitive resilience) |
cognitive_resilience_smoke.sh |
release-hardening |
security + property regressions, cross-interface |
robotics-golden-path |
examples/robotics/golden_path_deploy.sh |
telemetry-golden-path |
telemetry_store_golden_path.sh |
twin-cloud-golden-path |
twin_cloud_unified_path.sh, hosted_twin_cloud_smoke.sh |
registry-golden-path |
registry_golden_path.sh |
ci-verify-golden-path |
ci_verify_golden_path.sh |
killer-demo-golden-path |
killer_demo_golden_path.sh |
showcase-smoke |
showcase_smoke.sh |
adas-smoke |
adas_smoke.sh |
agriculture-smoke |
solution_blueprints_smoke.sh |
smart-spaces-smoke |
smart_spaces_smoke.sh |
enterprise-ops-smoke |
enterprise_ops_smoke.sh |
operational-governance-smoke |
operational_governance_smoke.sh (smoke only) |
entity-model-smoke |
entity_model_smoke.sh |
entity-mesh-smoke |
entity_mesh_smoke.sh (CLI, REST, SDK, gRPC mesh RPC test) |
differentiation-smoke |
differentiation_smoke.sh |
lsp |
@spanda/lsp build + tests |
wasm |
wasm32 checks + npm run web:build |
vscode-extension |
VSIX package via editor/vscode |
Path-filtered extension checks also run via
.github/workflows/vscode-extension-ci.yml when
editor/vscode/** or packages/lsp/** change.
| Job | Script / check |
|---|---|
prepare-spanda |
fetch-or-build-spanda (download from Integration/Fast, else compile) → artifact |
security-audit |
cargo audit |
mqtt-golden-path |
mqtt_golden_path.sh |
twin-cloud-stable-promotion-gate |
twin_cloud_stable_promotion_gate.sh |
llvm-golden-path |
llvm_golden_path.sh |
llvm-embedded-golden-path |
llvm_embedded_golden_path.sh |
cpp-native-golden-path |
cpp_native_golden_path.sh |
ledger-golden-path |
ledger_golden_path.sh |
self-host-lexer-golden-path |
self_host_lexer_golden_path.sh |
world-model-golden-path |
world_model_golden_path.sh |
live-ai-golden-path |
live_ai_golden_path.sh |
live-iot-golden-path |
live_iot_golden_path.sh |
python-native-golden-path |
python_native_golden_path.sh |
ros2-golden-path |
ros2_golden_path.sh |
ros2-rclrs-native |
spanda-ros2-rclrs-native + transport_rclrs |
recovery-orchestrator-stable-promotion-gate |
recovery_orchestrator_stable_promotion_gate.sh |
smart-spaces-promotion-gate |
smart_spaces_promotion_gate.sh |
adas-promotion-gate |
adas_stable_promotion_gate.sh |
enterprise-ops-promotion-gate |
enterprise_ops_stable_promotion_gate.sh |
entity-model-promotion-gate |
entity_model_stable_promotion_gate.sh |
entity-mesh-promotion-gate |
entity_mesh_stable_promotion_gate.sh |
differentiation-promotion-gate |
differentiation_promotion_gate.sh |
what-if-stable-promotion-gate |
what_if_stable_promotion_gate.sh |
next-differentiation-stable-gates |
risk, forecast, trust graph, scorecard gates |
later-differentiation-stable-gates |
later_differentiation_stable_promotion_gate.sh |
trust-framework-stable-gate |
trust_framework_stable_promotion_gate.sh |
operational-governance-promotion-gate |
operational_governance_stable_promotion_gate.sh |
control-center-desktop |
Tauri Linux build |
control-center-desktop-bundle |
macOS bundle + optional codesign |