XCI

XCI is a local GitHub Actions runner UX for running workflows locally with a polished terminal experience, delegating execution to act.

Features

• Discover workflows under .github/workflows/*.yml
• Interactive selection of workflows and jobs
• Non-interactive usage with flags
• Local runs via act with Docker/Podman
• Run history and logs under .xci/runs/<run-id>/

Architecture

XCI is built as a small set of layers with strict dependency direction:

core -> engine + store -> cli + tui

Key modules:

• src/core/: workflow discovery + parsing
• src/engines/: engine adapters (v1: act)
• src/store/: run persistence
• src/cli/: CLI wiring and non-interactive usage
• src/tui/: Ink UI rendering

See docs/architecture.md for details.

Demo

Requirements

• Node.js 18+
• act installed and available on PATH
• Docker or Podman running

Install

npm i -g @artsnlabs/xci

Homebrew (tap, available now):

brew tap moehaje/tap
brew install xci

Tap installs xci with act; Docker or Podman still needs to be running.

Homebrew one-command install:

brew install moehaje/tap/xci

For release/update flow, see docs/homebrew-core.md.

Usage

Examples below use both xci and xci run forms.

Global install:

xci
xci run
xci run --workflow ci.yml --event push --job build-and-test
xci run --workflow ci.yml --all --json

Without global install:

npx xci
npx xci run
npx xci run --workflow ci.yml --event push --job build-and-test
npx xci run --workflow ci.yml --all --json

Configuration

Create a .xci.yml at the repo root:

engine: act
runtime:
  container: docker
  architecture: amd64
  cleanupMode: fast
  image:
    ubuntu-latest: ghcr.io/catthehacker/ubuntu:act-latest
presets:
  quick:
    jobs: [build-and-test, code-quality]

Cleanup modes:

• off: skip post-run cleanup
• fast (default): remove act containers and ephemeral act volumes, keep act-toolcache + images
• full: remove act containers, all act volumes (including act-toolcache), and act images

Use --no-cleanup to force off for one run, or --cleanup-mode off|fast|full to override per run.

Project Health

• CI workflow
• Contributing guide
• Security policy
• Code of conduct
• Changelog
• Versioning policy

Development

npm install
npm run build
npm run type-check

Docs:

• docs/architecture.md
• docs/testing.md
• docs/exit-codes.md

License

MIT