Local CI and Verification Steps for OpenLogi Development: Complete Workflow Guide

Run cargo xtask ci to execute all applicable CI jobs locally, or use the pre-push gate via devenv tasks run openlogi:check to enforce formatting, Clippy linting, tests, and documentation builds before committing.

OpenLogi is a Rust-based logistics platform that enforces strict cross-platform compatibility through automated continuous integration. Mastering the local CI and verification steps for OpenLogi development allows contributors to reproduce GitHub Actions workflows on their machines, catching formatting errors, lint violations, and test failures before pushing code. The workflow is defined in docs/DEVELOPMENT.md and orchestrated by the automation harness in xtask/src/main.rs.

Running the Full Local CI Suite

The most comprehensive way to validate changes is running the complete CI suite locally. The repository provides a custom xtask command that mirrors the jobs defined in .github/workflows/ci.yml while adapting to your host operating system.

Using cargo xtask ci

The primary entry point for local CI is the xtask ci command, which detects your host OS and runs only the applicable jobs:

cargo xtask ci         # Execute all CI jobs applicable to the current OS

cargo xtask ci --list  # Display the mapping between CI jobs and commands

If you use the optional devenv environment, wrap the command as a task:

devenv tasks run openlogi:ci

Available CI Jobs

The local CI runner executes a subset of the following jobs based on your platform. Linux jobs require installing system libraries such as libudev-dev and libfontconfig-dev before executing Rust commands.

• fmt: Enforces rustfmt style using cargo fmt --all -- --check
• shell: Lints shell scripts using shellcheck and shfmt -d
• clippy: Runs cargo clippy --workspace --all-targets -- -D warnings to catch common mistakes
• msrv: Verifies the Minimum Supported Rust Version (1.98) on macOS and Linux via cargo check --workspace --all-targets
• docs: Builds documentation for non-GUI crates using cargo doc --workspace --no-deps --document-private-items while excluding openlogi-ui, openlogi-desktop, openlogi-overlay, and openlogi-agent
• test-linux: Executes cargo test --workspace --exclude openlogi-desktop on Linux runners
• test-macos: Runs the full suite with cargo test --workspace --all-targets on macOS (both architectures)
• cargo-deny: Checks licensing and security advisories with cargo deny --all-features --manifest-path crates/openlogi/Cargo.toml check
• clippy-windows: Validates Windows-specific code paths using cargo clippy --workspace --all-targets -- -D warnings

The Pre-Push Verification Gate

Before pushing commits, OpenLogi requires a host-OS subset of checks to pass. This gate, defined as the openlogi:check task in docs/DEVELOPMENT.md, ensures baseline quality standards regardless of CI platform.

The Four-Step Validation Sequence

Set strict warning flags and execute the following commands in order:

export RUSTFLAGS="-D warnings"

# 1. Ensure code formatting

cargo fmt --all -- --check

# 2. Lint with Clippy across all targets

cargo clippy --workspace --all-targets -- -D warnings

# 3. Run the full test suite

cargo test --workspace

# 4. Build documentation (excluding GUI crates)

RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \
  --document-private-items \
  --exclude openlogi-ui \
  --exclude openlogi-desktop \
  --exclude openlogi-overlay \
  --exclude openlogi-agent

Only after these four steps succeed should you push changes. Additional jobs covering MSRV validation, Windows-specific linting, and security auditing run exclusively in the GitHub Actions pipeline.

Automation with devenv

If configured, run the pre-push gate automatically using:

devenv tasks run openlogi:check

This invokes the same four-step sequence defined in docs/DEVELOPMENT.md without manual command chaining.

Understanding the Dual Workflow

The repository maintains both local CI and pre-push gates to balance development velocity with code quality:

• Local CI (cargo xtask ci) lets developers iterate quickly by reproducing exact CI jobs that will run on GitHub, eliminating network latency and providing immediate feedback on platform-specific behavior.
• Pre-Push Gate guarantees that every commit entering the repository meets baseline quality standards (formatting, lints, tests, and docs) regardless of the CI platform.
• Platform-Specific Coverage ensures cross-platform correctness through GitHub Actions runners for Windows, Linux x86_64, and macOS (both Intel and Apple Silicon), validating code paths that a single-host local run cannot cover.

Summary

• Run cargo xtask ci to execute all CI jobs applicable to your current operating system locally.
• Use cargo xtask ci --list to view the mapping of job names to shell commands stored in .claude/rules/ci.md.
• Execute the pre-push gate (devenv tasks run openlogi:check) to validate formatting, Clippy warnings, tests, and documentation before committing.
• Set RUSTFLAGS="-D warnings" and RUSTDOCFLAGS="-D warnings" to treat warnings as errors during local validation.
• Reference docs/DEVELOPMENT.md for the complete development workflow and .github/workflows/ci.yml for the authoritative CI job definitions.

Frequently Asked Questions

What is the difference between cargo xtask ci and the pre-push verification gate?

cargo xtask ci runs the full matrix of CI jobs applicable to your host OS, including platform-specific tests and checks like MSRV or cargo-deny when running on compatible systems. The pre-push verification gate focuses on four essential steps—formatting, Clippy, tests, and docs—that must pass on any platform before pushing, ensuring baseline quality without running the entire CI matrix locally.

How do I run only the formatting check locally?

Execute cargo fmt --all -- --check to verify rustfmt compliance without running the full suite. For shell script validation, run shellcheck and shfmt -d on your script files. These commands correspond to the fmt and shell jobs referenced in .github/workflows/ci.yml.

Why are GUI crates excluded from documentation builds?

The docs job and pre-push documentation step exclude openlogi-ui, openlogi-desktop, openlogi-overlay, and openlogi-agent because these crates depend on platform-specific GUI libraries that may not be available in all development environments or CI runners. This exclusion ensures documentation builds remain portable while still covering the core library APIs.

What Rust version does OpenLogi require for MSRV checks?

OpenLogi maintains a Minimum Supported Rust Version (MSRV) of 1.98, verified during CI via cargo check --workspace --all-targets. This requirement is specified in the workspace Cargo.toml and enforced for macOS and Linux builds to ensure compatibility across the supported toolchain range.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}