CI/CD

Orbitron uses GitHub Actions for automated testing, building, and releasing. This section explains what the workflows do and how to use them.

13.1 What CI/CD Does

CI (Continuous Integration): Every time you push code or someone opens a pull request, GitHub automatically: - Checks the Rust workspace on the self-hosted Linux and service-run Windows runners - Runs tests to catch regressions - Checks code formatting (cargo fmt) - Runs linters (cargo clippy) - Builds release binaries

Platform coverage is conditional. Ordinary code pushes and pull requests run on self-hosted Linux and Windows. A manual run, the weekly Monday schedule, and tag refs use hosted Ubuntu and macOS plus self-hosted Windows. An optional manual input selects the interactive Windows GUI runner instead of the normal matrix. Trigger a manual full-matrix run before landing anything macOS-sensitive.

CD (Continuous Delivery): When you create a Git tag (e.g., v1.0.0), GitHub automatically: - Builds release binaries for all platforms - Creates a GitHub release with downloadable archives - Attaches binaries to the release page

Why it matters: CI/CD catches bugs before users see them, ensures code works on all platforms, and makes releases easy without manual builds.

13.2 Workflows Overview

The repository includes six workflows:

.github/workflows/ci.yml - Main CI workflow
- Triggers: Pushes to main, v* tags, all pull requests, the weekly Monday schedule, and manual dispatch
- Platforms: self-hosted Linux and Windows on ordinary pushes and PRs; hosted Ubuntu and macOS plus self-hosted Windows on dispatch, schedule, and tags
- Jobs: build-viewer-assets builds the generated viewer_assets/ bundle once and saves an exact-commit cross-platform cache. checks restores it before compiling ui/shell, which include_bytes!s those files. wasm-smoke independently runs the browser suite so a browser failure does not prevent the Rust checks from reporting.
- Steps:
  - Format check (cargo fmt --all -- --check)
  - Linting (./scripts/check-rust-lints.sh)
  - Tests (cargo nextest run --workspace --locked --profile ci on every platform)
  - Doctests (cargo test --workspace --doc --locked, Ubuntu only — nextest runs none)
  - GUI/TUI smoke tests (Ubuntu only, with Xvfb)
  - Security audit (cargo deny on Ubuntu)
  - Benchmark compilation check
  - Strict six-scene render parity on Ubuntu 24.04 Mesa lavapipe
  - Build release binaries and upload as artifacts
- HDF5 Setup: Ubuntu and macOS build the source bundled by hdf5-metno; Windows links to the unpinned conda HDF5 package and configures its Library directory. DIRAC checkpoint support is enabled on all three platforms.
.github/workflows/python-tests.yml - Python bridge tests
- Triggers: Pushes and PRs on main or develop that touch extensions/python-bridge/**, core/**, io/pipelines/**, or the workflow file
- Platforms: self-hosted Linux; Python 3.10 and 3.13
- Steps:
  - Build Python package through the PEP 517 wrapper
  - Run API, bundle, animation, and configuration tests
  - Run Jupyter notebook tests
  - Execute tutorial notebook
  - Build an asset-bearing package and run embedding tests in a separate job
- HDF5 Setup: Builds the source bundled by hdf5-metno through CMake; there is no macOS or Windows job.
.github/workflows/release.yml - Automated releases
- Triggers: Git tags matching v* (e.g., v1.0.0, v0.2.1)
- Platforms: Ubuntu, macOS, Windows
- Steps:
  - Build release binaries for all platforms
  - Create GitHub release with tag name
  - Attach binaries as downloadable archives
  - Build cp310-abi3 wheels and versioned web-viewer artifacts
- Manual control: You create the tag when ready; CI builds and publishes automatically
.github/workflows/docs-lint.yml - Documentation integrity
- Checks local links and removed-token denylist rules on documentation changes.
.github/workflows/macos-signing-check.yml - Signing readiness
- Manually verifies that the configured Apple signing identity is available before a release tag depends on it.
.github/workflows/runner-health.yml - Self-hosted runner pickup check
- Runs daily and on demand from both self-hosted runners.
- Fails when a workflow has remained queued for more than 45 minutes.
- Cannot report the case where both self-hosted runners are offline; that needs monitoring outside the runner pair.

13.3 Checking CI Status

On GitHub: - Go to the “Actions” tab in your repository - Click on a workflow run to see detailed logs - Green checkmark = all tests passed - Red X = tests failed (click to see which step failed)

In Pull Requests: - CI status appears at the bottom of the PR page - All checks must pass before merging (if branch protection is enabled) - Click “Details” next to a check to see logs

Local testing before pushing — the same commands CI runs, in order:

cargo fmt --all -- --check
./scripts/check-rust-lints.sh
cargo nextest run --workspace --locked --profile ci
cargo test --workspace --doc --locked
cargo deny check

Locally, drop --profile ci so .config/nextest.toml caps the thread count, and prefix each command with conda run -n orbitron-dev (see §11.3).

13.4 Creating Releases

Manual release process (recommended for first-time open source):

Bump both package-version fields:
- Edit version under [workspace.package] in the root Cargo.toml. Every Rust workspace member inherits it via version.workspace = true.
- Edit project.version in extensions/python-bridge/pyproject.toml. Installed Python packages expose that metadata as orbitron.__version__.
- Run python scripts/check_version_sync.py --tag vX.Y.Z. CI checks the two fields on every push, and the release workflow checks them against the tag.
- Update CHANGELOG.md with release notes.

Create and push a Git tag:

git tag -a v0.5.0-rc.1 -m "Orbitron v0.5.0-rc.1"
git push origin v0.5.0-rc.1

GitHub Actions (release.yml) automatically:
- Builds desktop apps (macOS/Linux/Windows), CLI binaries, the web viewer, and Python wheels (Linux manylinux + macOS arm64 + Windows, all cp310-abi3)
- Creates a GitHub release and attaches all of them
- Signs/notarizes the macOS app if Apple secrets are set (otherwise ships it unsigned)
Verify the release candidate before the final tag:
- Go to “Releases” in your GitHub repository
- Check that binaries are attached
- Follow the artifact and platform checks in RELEASE_CHECKLIST.md.

Pre-release tags (for testing): - Use tags like v1.0.0-beta.1 or v1.0.0-rc.1 - The workflow marks these as “pre-release” automatically - Test the binaries before creating the final release tag

13.5 Troubleshooting CI Failures

Common issues:

HDF5 build failures (Ubuntu):
- Linux and macOS compile the HDF5 source bundled by hdf5-metno.
- Check that CMake is installed and inspect the hdf5-metno-src build output.
- Windows still uses conda HDF5; inspect the “Configure HDF5 environment (Windows)” step there.
Tests failing on one platform:
- Check platform-specific differences (file paths, line endings, etc.)
- Some tests may be platform-specific (GUI tests require X11/Wayland on Linux)
Format/clippy failures:
- Run cargo fmt --all locally to fix formatting
- Run ./scripts/check-rust-lints.sh to see clippy suggestions
Missing dependencies:
- Ensure all dependencies are declared in Cargo.toml
- Check that optional dependencies are properly gated behind feature flags

Getting help: - Check workflow logs for detailed error messages - Run the same commands locally to reproduce issues - See §15 Debugging Playbook for more troubleshooting tips

13.6 Customizing CI/CD

Adding new checks: - Edit .github/workflows/ci.yml to add new steps - Use the same HDF5 setup steps if your check needs HDF5

Changing release behavior: - Edit .github/workflows/release.yml to modify release creation - Configure signing/notarization credentials for macOS releases (see §14.2) - Add code signing for Windows (requires certificates)

Platform-specific builds: - The matrix strategy in ci.yml makes it easy to add new platforms - Ensure HDF5 setup is added for new platforms if needed