How to Run CI Jobs Locally for OpenLogi: Complete Guide

You can run OpenLogi's CI jobs locally using the cargo xtask ci command, which parses .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. 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 – Main entry point that orchestrates the CI replication
• xtask/src/commands/ci/jobs.rs – Structures per-job metadata including host gating logic
• 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:

devenv shell -- cargo xtask ci

Show a list of available jobs and see which ones your host can execute:

devenv shell -- cargo xtask ci --list

Perform a dry run to see which jobs would run without executing them:

devenv shell -- cargo xtask ci --dry-run

Run a specific job, such as the Linux test suite:

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:

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 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, 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 handles command-line parsing and orchestration, xtask/src/commands/ci/jobs.rs defines the job structures and platform compatibility checks, and 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.

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