# How to Run CI Jobs Locally for OpenLogi: Complete Guide > Run OpenLogi CI jobs locally with cargo xtask ci. Execute the same checks as GitHub Actions on your machine for faster feedback and development. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: how-to-guide - Published: 2026-08-22 --- **You can run OpenLogi's CI jobs locally using the `cargo xtask ci` command, which parses [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) and executes the same checks on your machine that run in GitHub Actions.** OpenLogi is an open-source logistics platform written in Rust that uses GitHub Actions for continuous integration. Instead of waiting for CI runners to validate your changes, you can reproduce the entire CI pipeline locally using the repository's custom `xtask` helper, ensuring code quality before pushing commits. ## Understanding OpenLogi's CI Workflow Structure The continuous integration pipeline is defined in **[`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml)**. This file specifies multiple jobs including `fmt`, `clippy`, `msrv`, `test-linux`, `test-macos`, and `docs`, each with specific platform requirements and shell commands. For example, the **clippy** job runs `cargo clippy --workspace --all-targets -- -D warnings` on an Ubuntu runner. The workflow file contains the canonical mapping between job names and their execution commands, which the local runner parses to ensure identical behavior between local and remote execution. ## The `xtask` Command-Line Helper OpenLogi follows the Rust `xtask` pattern to provide repository-specific tooling. The `xtask` crate contains the implementation that reads the CI workflow, filters jobs based on your host platform, and executes the appropriate steps. The core logic resides in three key files: - **[`xtask/src/commands/ci.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci.rs)** – Main entry point that orchestrates the CI replication - **[`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs)** – Structures per-job metadata including host gating logic - **[`xtask/src/commands/ci/steps.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/steps.rs)** – Executes individual shell steps for each job According to the comment at the top of the workflow file, `cargo xtask ci` is the canonical way to reproduce CI jobs locally. ## How to Run CI Jobs Locally for OpenLogi ### Prerequisites The repository expects you to run commands within a `devenv` shell environment, though direct execution is also possible. Ensure you have the Rust toolchain installed and the repository cloned locally. ### Basic Commands Run all CI jobs compatible with your current operating system: ```bash devenv shell -- cargo xtask ci ``` Show a list of available jobs and see which ones your host can execute: ```bash devenv shell -- cargo xtask ci --list ``` Perform a dry run to see which jobs would run without executing them: ```bash devenv shell -- cargo xtask ci --dry-run ``` Run a specific job, such as the Linux test suite: ```bash devenv shell -- cargo xtask ci test-linux ``` ### Alternative Execution Without devenv If you prefer not to use the `devenv` environment, invoke the xtask directly via Cargo: ```bash cargo run -p xtask -- ci cargo run -p xtask -- ci --list cargo run -p xtask -- ci clippy ``` ## Host Gating and Platform-Specific Jobs The `xtask` implementation automatically filters jobs based on your host platform. When a job specifies a platform like `macos-latest` or requires a specific toolchain unavailable on your machine, the tool skips that job with an explanatory message. This **host gating** mirrors the CI behavior where separate runners handle Linux, macOS, and Windows jobs. For instance, attempting to run `test-macos` on a Linux machine will result in the job being skipped, while compatible jobs like `fmt` or `clippy` will execute normally. ## Summary - OpenLogi stores CI definitions in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) with jobs for formatting, linting, testing, and documentation. - The **`cargo xtask ci`** command parses this workflow file to replicate CI behavior locally. - Use **`--list`** to see available jobs and **`--dry-run`** to preview execution without side effects. - The implementation lives in `xtask/src/commands/ci/` with separate modules for job metadata and step execution. - Host gating automatically skips platform-specific jobs that cannot run on your current operating system. ## Frequently Asked Questions ### What is the `xtask` pattern in Rust? The `xtask` pattern is a convention where repositories include a dedicated Rust crate named `xtask` that contains maintenance and automation scripts. Instead of relying on external build tools like Make or shell scripts, developers write these utilities in Rust and invoke them via `cargo xtask [command]`, ensuring cross-platform compatibility and type safety for build automation. ### Can I run macOS-specific CI jobs on Linux locally? No, you cannot run macOS-specific jobs on Linux. The `xtask` tool implements host gating in [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs), which checks the current platform against each job's requirements. Jobs targeting incompatible platforms are automatically skipped with a notification explaining the platform mismatch, matching the behavior of the separate GitHub Actions runners. ### Where is the CI job logic implemented in the source code? The CI replication logic is implemented in the `xtask/src/commands/ci/` directory. Specifically, **[`xtask/src/commands/ci.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci.rs)** handles command-line parsing and orchestration, **[`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs)** defines the job structures and platform compatibility checks, and **[`xtask/src/commands/ci/steps.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/steps.rs)** handles the actual execution of shell commands defined in the workflow file. ### How do I run only the formatting check locally? Execute `cargo xtask ci fmt` to run only the formatting job. The tool accepts specific job names as positional arguments and will execute only those jobs if they are compatible with your host. You can combine this with the `--dry-run` flag to verify the job exists and can run on your machine before executing it.