justci
justci translates a project's just recipe DAG into a process-compose pipeline and runs it. Multi-platform lanes fan out via SSH; commit statuses get posted (in strict mode) under <recipe>@<platform> contexts. Full background in the repo README; the subcommand surface below is what you'll reach for most often.
Invoking
Always invoke via the flake — the consumer may not have justci installed on PATH:
nix run github:juspay/justci -- <subcommand> [args]
Pin to a tag (e.g. github:juspay/justci/v0.2.0) for reproducibility, or omit the ref to follow main. Every command in this skill is shown in the nix run form; substitute a pinned ref if your project requires one.
Modes
| Variable | Effect |
|---|---|
CI unset (default) |
Local mode. Runs against the live working tree. No GitHub status posts, no clean-tree refuse. Use for iterating. |
CI=true |
Strict mode. Refuses a dirty tree, snapshots HEAD via git worktree, posts commit statuses, splits per-recipe logs into .ci/<sha>/<plat>/<recipe>.log. Use for "real" CI runs. |
Both modes share the same verdict-summary at the end (── ci run summary ──) and exit non-zero if any node failed.
Common invocations
# Full pipeline (canonical [metadata("ci")] root, every platform in the fanout)
nix run github:juspay/justci -- run # local mode
CI=true nix run github:juspay/justci -- run # strict mode
# Re-run a single failed recipe on a specific lane — overwrites the same
# GitHub commit-status context the full run wrote (closes the red check).
nix run github:juspay/justci -- run e2e@x86_64-linux
# Re-run a single recipe across every pipeline platform.
nix run github:juspay/justci -- run e2e
# Multiple positional selectors compose — `e2e` AND `lint` both run.
nix run github:juspay/justci -- run e2e lint
# Skip the dependency closure; run ONLY the named nodes. Setup nodes
# auto-ride for remote-platform recipes regardless.
nix run github:juspay/justci -- run --no-deps e2e@aarch64-darwin
# Use a different DAG root instead of the [metadata("ci")] recipe.
nix run github:juspay/justci -- run --root release-pipeline
# One-shot redirect of a platform to a throwaway host (LXC container,
# alternate SSH alias). Repeatable per platform.
nix run github:juspay/justci -- run --host x86_64-linux=root@lxc-foo
# Drive process-compose's interactive TUI instead of headless logs.
nix run github:juspay/justci -- run --tui
# Forward arbitrary args to `process-compose up` after --.
nix run github:juspay/justci -- run -- -t=false
Inspection subcommands (no side effects)
# Print the assembled process-compose YAML — no host prompts, no git
# rev-parse, works offline.
nix run github:juspay/justci -- dump-yaml
# Print the dependency graph in Mermaid flowchart syntax.
nix run github:juspay/justci -- graph
# PATCH GitHub branch-protection's required_status_checks to the
# (recipe, platform) contexts the canonical DAG produces. --dry-run
# prints what would be PATCHed without touching the API.
nix run github:juspay/justci -- protect --dry-run
nix run github:juspay/justci -- protect # writes to default branch
nix run github:juspay/justci -- protect --branch develop
Live introspection (during a backgrounded run)
When justci run is in progress — typically because the agent backgrounded it (e.g. loop until /ci passes) — these subcommands report fine-grained per-node state without disturbing the run. Each resolves the socket and process-compose binary from the same source justci run itself uses, so the client version never drifts from the server.
# Snapshot every node's current state. Pipe `-o json` into jq for
# fields like name / status / exit_code / restarts.
nix run github:juspay/justci -- status
nix run github:juspay/justci -- status -o json
# Live state-transition stream — one line per (recipe, platform)
# transition, no polling. `-o json` emits one event per line.
nix run github:juspay/justci -- monitor
# Tail one node's stdout/stderr; `-f` follows.
nix run github:juspay/justci -- logs ci::e2e@aarch64-darwin
nix run github:juspay/justci -- logs -f ci::e2e@aarch64-darwin
If no run is in progress in this checkout, the subcommand exits non-zero with no justci run in progress in this checkout (no socket at .ci/pc.sock).
Anti-pattern: do not reach for raw process-compose
If you find yourself typing nix run nixpkgs#process-compose -- or hunting through /nix/store/...-process-compose-*/bin/ for a binary, stop — that path is not guaranteed to match the version the running pipeline uses, and the JSON shapes (e.g. process list -o json) may disagree. Always go through nix run github:juspay/justci -- {status,logs,monitor} so client and server stay version-pinned.
Decision flow
- Full canonical run? →
nix run github:juspay/justci -- run(orCI=true …for strict mode). - Flaky check on a PR, only one lane is red? →
nix run github:juspay/justci -- run <recipe>@<platform>— same status context, overwrites the failure. - Iterating on one recipe locally? →
nix run github:juspay/justci -- run <recipe>(no platform pin = fans out to every pipeline platform;<recipe>@<localPlat>if you only want the local lane). - Investigating "what would this run?" →
nix run github:juspay/justci -- dump-yamlor… -- graph. - Setting up a new repo? → run
… -- protect --dry-runafter at least one full run, verify the contexts look right, then… -- protectto lock them in. - Checking on a backgrounded run? →
nix run github:juspay/justci -- statusfor a snapshot,… -- logs -f <recipe>@<platform>to follow one node,… -- monitorfor the live event stream.
Hosts config
justci reads ~/.config/justci/hosts.json:
{
"x86_64-linux": "srid1",
"aarch64-darwin": "sincereintent"
}
Keys are full Nix system tuples (x86_64-linux, aarch64-linux, aarch64-darwin). Values are anything ssh knows how to dial — bare hostname, user@host, alias from ~/.ssh/config. Missing platforms silently drop from the fanout (the user opts in by adding the entry). Override per-run with --host PLATFORM=ADDR.
When NOT to use this skill
- The user is asking about justci's internals (how the YAML is shaped, what the setup node does, why
[metadata("ci")]matters) — that's a docs question, point them at the repo README. - The user wants the runner to do something it doesn't support (parallel cross-platform within one recipe, mid-run config reload) — those are not supported today; check the README's Roadmap section.