How to Run the Full CI Job Matrix Locally for OpenLogi

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.

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 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 maps CI job names to concrete Cargo commands according to the rules defined in .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:

   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:

   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 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:

cargo xtask ci --list

This outputs the sequence of cargo commands that the xtask helper will invoke, parsed from .github/workflows/ci.yml and .claude/rules/ci.md.

Execute the Complete Matrix

Run the full CI job matrix locally with:

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:

# 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:

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

Documentation generation (excluding GUI crates):

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):

cargo test --workspace

Formatting check:

cargo fmt --all -- --check

Key Implementation Files

Understanding these source files helps when debugging CI behavior:

• .github/workflows/ci.yml – Defines the CI matrix and job configurations that cargo xtask ci reads and executes
• xtask/src/main.rs – Contains the xtask binary implementation that maps CI job names to concrete Cargo commands
• .claude/rules/ci.md – Internal rule file describing how each CI job maps to specific command-line invocations
• xtask/README.md – Documentation for the xtask automation tool and available commands
• 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 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 <name> to run individual checks
• The xtask implementation in xtask/src/main.rs and rules in .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 provides the ci subcommand that parses .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.

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