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 if code compiles on all platforms (Linux, macOS, Windows) - Runs tests to catch regressions - Checks code formatting (cargo fmt) - Runs linters (cargo clippy) - Builds release binaries for all platforms

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 three main workflows:

  1. .github/workflows/ci.yml - Main CI workflow
    • Triggers: Pushes to main branch, all pull requests
    • Platforms: Ubuntu, macOS, Windows
    • Steps:
      • Format check (cargo fmt)
      • Linting (cargo clippy)
      • Tests (cargo test on macOS/Windows, cargo nextest on Ubuntu)
      • GUI/TUI smoke tests (Ubuntu only, with Xvfb)
      • Security audit (cargo deny on Ubuntu)
      • Benchmark compilation check
      • Build release binaries and upload as artifacts
    • HDF5 Setup: Provisioned via the conda env (environment.yml, hdf5=1.12.*) on Ubuntu, macOS, and Windows; Linux additionally installs an MPI-enabled HDF5 build. Windows configures HDF5 too — DIRAC checkpoint support is not disabled there.
  2. .github/workflows/python-tests.yml - Python bridge tests
    • Triggers: Changes to extensions/python-bridge/**, core/**, or the workflow file
    • Platforms: Ubuntu only; Python 3.8 and 3.12 (the abi3 endpoints)
    • Steps:
      • Build Python package with maturin
      • Run Python unit tests
      • Run Jupyter notebook tests
      • Execute tutorial notebook
    • HDF5 Setup: Builds HDF5 1.12.3 from source on Ubuntu (CI itself uses conda); there is no macOS or Windows job.
  3. .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
    • Manual control: You create the tag when ready; CI builds and publishes automatically

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:

# Run the same checks locally
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

# On Ubuntu, also run:
cargo nextest run --workspace
cargo deny check

13.4 Creating Releases

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

  1. Bump the version (single source of truth):

    • Edit version under [workspace.package] in the root Cargo.toml. Every member crate inherits it via version.workspace = true, and the Python package (pyproject.toml / orbitron.__version__) derives from it — so this is the only place to change.
    • Update CHANGELOG.md with release notes.

  2. Create and push a Git tag:

    git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

  3. 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 cp38-abi3)
    • Creates a GitHub release and attaches all of them
    • Signs/notarizes the macOS app if Apple secrets are set (otherwise ships it unsigned)

  4. Verify the release:

    • Go to “Releases” in your GitHub repository
    • Check that binaries are attached
    • Edit the release description if needed (add changelog, known issues, etc.)

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:

  1. HDF5 build failures (Ubuntu):
    • CI provisions HDF5 1.12.x via conda on all platforms (with a retry around the MPI-HDF5 install to ride out transient conda-forge 403s). The statically-vendored hdf5-sys path is only used by the macOS wheel build in release.yml.
    • If it fails, check the “Install MPI-enabled HDF5 (Linux)” / “Verify HDF5 installation” step logs
    • Ensure the download URL is still valid (HDF Group may update URLs)
  2. 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)
  3. Format/clippy failures:
    • Run cargo fmt --all locally to fix formatting
    • Run cargo clippy --workspace --all-targets --all-features -- -D warnings to see clippy suggestions
  4. 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