# How to Run the Full CI Job Matrix Locally for OpenLogi > Run the full CI job matrix locally for OpenLogi with cargo xtask ci. Reproduce all linting, testing, and auditing jobs to ensure code quality before pushing changes. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: how-to-guide - Published: 2026-08-21 --- **Run `cargo xtask ci` from the repository root to execute the complete CI matrix locally, reproducing all linting, testing, and auditing jobs defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml).** OpenLogi validates every code change through a comprehensive GitHub Actions workflow that spans multiple platforms and toolchains. Instead of pushing commits to trigger remote runners, you can execute the full CI job matrix locally using the repository's automation tooling, catching failures before submission while respecting platform-specific configurations like `RUSTFLAGS="-D warnings"`. ## Understanding the CI Matrix Structure The continuous integration pipeline is defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) and orchestrates six distinct verification jobs through the **xtask** automation framework: - **Linux clippy** – Runs `cargo clippy --workspace --all-targets` with `-D warnings` to enforce code quality - **Linux tests** – Executes `cargo test --workspace` while excluding GUI crates that require display servers - **macOS tests** – Runs `cargo test --workspace --all-targets` including GUI components on macOS targets - **Windows clippy** – Performs Windows-specific linting using the cross-compilation toolchain - **Rustdoc** – Generates documentation for non-GUI crates with strict warning flags - **Cargo-deny** – Audits dependencies for license compliance and security advisories The `cargo xtask ci` command reads this matrix definition directly from the workflow file and executes each job sequentially on your host machine. The implementation in [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) maps CI job names to concrete Cargo commands according to the rules defined in [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md). ## Prerequisites for Local CI Execution Before running the full matrix, ensure your environment meets these requirements: 1. **Rust toolchain** – Install via `rustup`. The Minimum Supported Rust Version (MSRV) is the latest stable (currently 1.78). Run: ```bash rustup toolchain install stable rustup default stable ``` 2. **Cross-compilation targets** – To validate Windows and macOS jobs from a Linux host, add the necessary targets: ```bash rustup target add x86_64-pc-windows-gnu rustup target add x86_64-apple-darwin ``` 3. **Optional: Nix development environment** – The repository includes [`devenv.yaml`](https://github.com/AprilNEA/OpenLogi/blob/main/devenv.yaml) and `flake.nix` for reproducible setups. Running `devenv up` automatically installs required toolchains and dependencies. 4. **GitHub Actions secrets** – No secrets are required for local execution; the workflow uses only public tools and crates. ## Running the Full CI Matrix Locally ### Preview Commands Without Executing To see the exact commands that would run without executing them, use the `--list` flag: ```bash cargo xtask ci --list ``` This outputs the sequence of cargo commands that the xtask helper will invoke, parsed from [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) and [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md). ### Execute the Complete Matrix Run the full CI job matrix locally with: ```bash cargo xtask ci ``` The xtask binary executes each job sequentially. If any sub-job fails, the command stops immediately and prints the error, mirroring GitHub Actions behavior. Fix the issue, then rerun the command. ### Run Individual CI Jobs To execute a specific job from the matrix, use the `--job` flag: ```bash # Run only the cargo-deny audit cargo xtask ci --job deny # Run only Linux clippy checks cargo xtask ci --job clippy-linux ``` ## Manual Command Equivalents While `cargo xtask ci` automates the full matrix, you can run individual checks manually using the same commands that CI executes: **Linux clippy validation:** ```bash cargo clippy --workspace --all-targets -- -D warnings ``` **Documentation generation (excluding GUI crates):** ```bash RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \ --exclude openlogi-ui \ --exclude openlogi-desktop \ --exclude openlogi-overlay \ --exclude openlogi-agent ``` **Workspace tests (Linux, excluding GUI):** ```bash cargo test --workspace ``` **Formatting check:** ```bash cargo fmt --all -- --check ``` ## Key Implementation Files Understanding these source files helps when debugging CI behavior: - [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) – Defines the CI matrix and job configurations that `cargo xtask ci` reads and executes - [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) – Contains the xtask binary implementation that maps CI job names to concrete Cargo commands - [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md) – Internal rule file describing how each CI job maps to specific command-line invocations - [`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md) – Documentation for the xtask automation tool and available commands - [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) – General development workflow and environment setup instructions ## Summary - Use `cargo xtask ci` to run the full CI job matrix locally for OpenLogi, executing the same checks as GitHub Actions - The command reads job definitions from [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) and runs them sequentially, failing fast on errors - Install cross-compilation targets (`x86_64-pc-windows-gnu`, `x86_64-apple-darwin`) to validate platform-specific jobs from Linux - Use `cargo xtask ci --list` to preview commands and `cargo xtask ci --job ` to run individual checks - The xtask implementation in [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) and rules in [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md) define how CI jobs map to Cargo commands ## Frequently Asked Questions ### What is the xtask pattern used in OpenLogi? **xtask** is a Rust convention where a Cargo project in the `xtask/` directory contains automation scripts. In OpenLogi, this binary defined in [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) provides the `ci` subcommand that parses [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) and executes the defined matrix locally, eliminating the need for external scripting languages like Python or Bash. ### Do I need GitHub Actions secrets to run the CI matrix locally? No. The OpenLogi CI workflow uses only public crates and tools, requiring no authentication tokens or secrets. The `cargo xtask ci` command runs entirely offline after initial dependency downloads, making local verification straightforward for external contributors. ### How do I debug a failing CI job on my machine? Run `cargo xtask ci --list` to identify the exact cargo command associated with the failing job, then execute that command directly with the `--nocapture` flag for tests or verbose flags for clippy. For example, if Linux tests fail, run `cargo test --workspace -- --nocapture` to see detailed output without the xtask wrapper. ### Can I execute Windows or macOS tests from a Linux development machine? Yes, but with limitations. You can validate compilation and clippy checks for Windows using the `x86_64-pc-windows-gnu` target, but running actual Windows or macOS test binaries requires the respective operating systems or emulation. The xtask will attempt to run the commands, but platform-specific GUI tests will fail on incompatible hosts.