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

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.

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, 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 and implemented in xtask/src/commands/ci/jobs.rs.

The Job enum in 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 displays a table mapping job names to their local commands.

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

Code Formatting and Linting

Run the formatting check locally with:

cargo xtask ci rustfmt

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

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:

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:

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:

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

cargo xtask ci msrv

This sets RUSTUP_TOOLCHAIN to the floor version defined in the root 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.

Additional Checks

Run cargo-deny license and security checks:

cargo xtask ci cargo-deny

Generate documentation with strict warning settings:

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:

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:

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.

Running the Full CI Pipeline

Execute all jobs compatible with your current host:

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.

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 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
• 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 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.

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.

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

The job definitions are stored in multiple locations: .github/workflows/ci.yml contains the GitHub Actions workflow, .claude/rules/ci.md documents the job-to-command mapping, and 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.

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