# How to Run Specific CI Jobs for OpenLogi: Local Development Guide

> Easily run specific CI jobs for OpenLogi locally with the cargo xtask ci command. Replicate the exact GitHub Actions environment for seamless development and testing.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-22

---

**To run specific CI jobs for OpenLogi locally, use `cargo xtask ci <job-name>` from the repository root, where the xtask helper reproduces the exact environment variables and commands defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml).**

OpenLogi centralizes its continuous integration pipeline in a dedicated xtask crate that mirrors the GitHub Actions workflow. Developers can run specific CI jobs for OpenLogi on their local machines using the `cargo xtask ci` command, which handles environment setup and host-specific restrictions automatically.

## Understanding the OpenLogi CI Architecture

The CI pipeline definition lives in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml), but the local execution logic resides in the `xtask` crate. According to the OpenLogi source code, the mapping between CI jobs and local commands is documented in [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md) and implemented in [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs).

The `Job` enum in [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs) defines each available CI job, including host restrictions and command sequences. This architecture ensures that local runs use identical settings to CI runners, including environment variables like `CARGO_TERM_COLOR=always`, `CARGO_INCREMENTAL=0`, and `RUSTFLAGS=-D warnings`.

## Listing Available CI Jobs

Before running specific jobs, list all available options using the `--list` flag. The implementation in [`xtask/src/commands/ci/list.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/list.rs) displays a table mapping job names to their local commands.

```sh
cargo xtask ci --list

```

This outputs all job variants defined in the `Job` enum, including aliases and host requirements. The helper reads the job definitions from [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs) and displays which jobs can execute on your current platform.

## Running Individual CI Jobs Locally

Execute specific jobs by passing the job name (or alias) to the `cargo xtask ci` command. The helper resolves names to enum variants in `Job` and executes the associated plan from [`xtask/src/commands/ci/jobs/steps.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs/steps.rs).

### Code Formatting and Linting

Run the formatting check locally with:

```sh
cargo xtask ci rustfmt

```

This executes `cargo fmt --all -- --check` and can run on any host. For shell script validation:

```sh
cargo xtask ci shell

```

This runs `shfmt` and `shellcheck` against repository shell scripts using `git ls-files`.

### Clippy Checks

The clippy job runs on Linux in CI, but you can execute it locally on any host:

```sh
cargo xtask ci clippy

```

Note that running on macOS or Windows may produce different results because the command compiles platform-specific `cfg` sections. For Windows-specific clippy checks:

```sh
cargo xtask ci clippy-windows

```

On non-Windows hosts, this runs the same command but notes the platform mismatch.

### Test Execution

Run platform-specific test suites using the defined job names:

```sh

# Linux tests (excludes openlogi-desktop)

cargo xtask ci test-linux

# macOS tests (includes all targets, runs on arm64 and x86_64 in CI)

cargo xtask ci test-macos

```

The helper checks host compatibility before execution. If you run `test-linux` on macOS, the tool emits a skip notice rather than failing.

### MSRV Verification

Check the Minimum Supported Rust Version using:

```sh
cargo xtask ci msrv

```

This sets `RUSTUP_TOOLCHAIN` to the floor version defined in the root [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml) and runs `cargo check --workspace --all-targets`. The environment variable handling ensures compatibility with the MSRV requirements specified in [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md).

### Additional Checks

Run cargo-deny license and security checks:

```sh
cargo xtask ci cargo-deny

```

Generate documentation with strict warning settings:

```sh
cargo xtask ci rustdoc

```

This executes with `RUSTDOCFLAGS="-D warnings"` and excludes GPUI crates as configured in the job steps.

## Running Multiple Jobs and Dry Runs

Execute multiple jobs sequentially by listing them as arguments:

```sh
cargo xtask ci rustfmt clippy test-linux

```

The helper processes each job in order, applying host restrictions individually.

To preview commands without executing them, use the `--dry-run` flag implemented in [`xtask/src/commands/ci/list.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/list.rs):

```sh
cargo xtask ci --dry-run clippy

```

This displays the exact commands and environment variables that would be used, matching the behavior verified in [`xtask/src/commands/ci/list/tests.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/list/tests.rs).

## Running the Full CI Pipeline

Execute all jobs compatible with your current host:

```sh
cargo xtask ci

```

Without arguments, the helper invokes `Job::default_run()`, iterating through all jobs and skipping those incompatible with the current platform. It prints a summary of skipped jobs and their host requirements.

## Host-Specific Behavior and Environment Variables

The xtask helper automatically sets CI-equivalent environment variables to ensure consistent behavior:

- `RUSTFLAGS=-D warnings` (treats warnings as errors)
- `CARGO_TERM_COLOR=always`
- `CARGO_INCREMENTAL=0`

For the MSRV job, it additionally configures `RUSTUP_TOOLCHAIN` based on the version specified in [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml).

Platform-specific limitations exist: the `clippy` job runs on Ubuntu in CI, so local Linux execution most accurately reproduces CI results. The `test-macos` job requires macOS for full compatibility, while `test-linux` requires Linux.

## Summary

- OpenLogi's CI pipeline is defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) but executed locally via the `xtask` crate in `xtask/src/commands/ci/`
- Use `cargo xtask ci --list` to view available jobs defined in the `Job` enum in [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs)
- Run individual jobs with `cargo xtask ci <job-name>`, such as `cargo xtask ci rustfmt` or `cargo xtask ci test-linux`
- The helper automatically sets environment variables like `RUSTFLAGS=-D warnings` to match CI behavior
- Use `cargo xtask ci --dry-run` to preview commands without execution
- Host restrictions prevent incompatible jobs (like Linux-only tests on macOS) from running incorrectly

## Frequently Asked Questions

### What is the xtask helper in OpenLogi?

The xtask helper is a Rust-based automation tool located in the `xtask/` directory. According to the OpenLogi source code, it implements the `Job` enum in [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs) to map CI workflow steps to local commands, ensuring that environment variables and tool configurations match the GitHub Actions runners defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml).

### Can I run Linux-specific CI jobs on macOS or Windows?

You cannot fully execute Linux-specific jobs like `test-linux` on non-Linux hosts. The `cargo xtask ci` helper checks host compatibility and emits a skip notice if you attempt to run incompatible jobs. However, jobs like `clippy` will execute but may produce different results because they compile different platform-specific code paths based on the host's `cfg` flags.

### How do I check what commands a CI job will run before executing them?

Use the `--dry-run` flag with the list command or specific job names. For example, `cargo xtask ci --dry-run` shows all commands for the default job set, while `cargo xtask ci --dry-run clippy` displays the specific cargo invocation and environment variables. This functionality is implemented in [`xtask/src/commands/ci/list.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/list.rs).

### Where are the CI job definitions stored in the OpenLogi repository?

The job definitions are stored in multiple locations: [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) contains the GitHub Actions workflow, [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md) documents the job-to-command mapping, and [`xtask/src/commands/ci/jobs.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs.rs) defines the `Job` enum with host restrictions and aliases. The concrete step implementations reside in [`xtask/src/commands/ci/jobs/steps.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/ci/jobs/steps.rs).