Runners

orun separates compilation from execution. orun plan produces an immutable plan.json — a DAG of jobs and steps with every reference resolved. orun run consumes that plan through an execution backend (a "runner") of your choice.

Same plan, different runners. The plan is the boundary.

→local

Run on the host shell

Each run: step executes through sh -c on your machine. Fast feedback loop for development and any environment that already has the required binaries on $PATH.

▣docker

Run in a container

Pulls the job's image, mounts the workspace at /workspace, and executes inside an isolated container. Use for CI parity and stronger isolation when composition steps shouldn't touch the host.

⚙github-actions

Run Actions-compatible steps

Executes GitHub Actions-style use: steps and compatible workflow commands. Auto-selected when the plan contains any use: step; can be forced with --gha.

Selection order

orun run resolves the runner in a stable, predictable order:

1. --gha                       ← shorthand for --runner github-actions
2. --runner <name>             ← explicit flag
3. $ORUN_RUNNER                ← environment variable
4. auto: github-actions        ← when GITHUB_ACTIONS=true
                                 or any step in plan uses use:
5. local                       ← default

The chosen runner is recorded in the run metadata, so the cockpit always tells you which backend executed which step.

Choosing a runner

Need	Runner
Fast local iteration on a workstation	local
Reproducible execution that matches CI	docker
Plans that embed GitHub Actions	github-actions
Mixed plans (shell + actions)	github-actions (handles both)
CI environment, vendor-agnostic	docker
CI environment, on GitHub Actions	auto-detected

The runner does not affect the plan. Switching runners is a deploy-time choice, not a compile-time one — you can validate against docker and ship with github-actions from the same plan.json.

Preview before execute

--dry-run is the universal preview. It runs every stage up to shell execution: resolves working directories, prepares the runner, picks images — and stops.

orun run --plan plan.json --dry-run

Use it when you want to inspect job ordering, step phases, runtime hints, and the selected runner without actually executing anything.

Resumption

Runs are durable. .orun/runs/<id>/state.json records job and step status on every transition, so orun run --resume <id> picks up where a failed or interrupted run left off. The cockpit shows resumed runs with the ⚡ glyph.

Trigger-aware execution

The plan already encodes how the trigger should shape execution:

• Profile rules select which job profile runs — e.g. plan-only on pull requests, apply on merge to main.
• Dependency rules mark edges as enforced, advisory, or disabled — PR validation runs in parallel; releases enforce order.

Both are baked into the plan at compile time. The runner just executes what it's given.

Next

• orun run — full flag reference.
• Execution model — phases, fail-fast, concurrency.
• Trigger bindings — how CI events shape the plan.
• Docker example — end-to-end Docker workflow.
• GitHub Actions example — end-to-end GHA workflow.