raft / docs
Guides

Run a disposable CI job

raft run creates a disposable box, waits for command readiness, uploads source if requested, runs your command, collects result directories, and attempts cleanup. It does not register a CI runner or replace your scheduler.

Use trusted jobs on dedicated hosts only. Your controller's host SSH identity has passwordless sudo and can control all boxes. Do not expose it to unreviewed pull requests or fork jobs. Boxes share the host kernel, not VM isolation.

You need a configured location, a compatible expiry worker, verified SSH host keys and batch authentication. Git-filtered upload needs Git on the Linux controller. Raft does not forward your environment, GitHub login or SSH agent, or inject managed secrets. Never copy a host private key into a guest.

Run tests and collect a report

From a Git working tree with package-lock.json and an npm test script, choose a local reports destination that does not exist:

RAFT_NO_UPDATE_CHECK=1 raft run \
  --location lab --timeout 600 --cpu 2 --memory 4GiB --disk shared \
  --purpose "Project tests" --owner "Local CI" --next "Delete after collection" \
  --push . --pull /workspace/project/reports ./ci-reports \
  -- bash -lc 'set -euo pipefail; mkdir -p reports; npm ci; npm test 2>&1 | tee reports/test.log'

Payload stdout and stderr stream to your terminal; lifecycle messages, the allocated handle and elapsed time use stderr. For JSONL events, use global raft --json run ...; see scripted output.

--timeout is one deadline for Git filtering, creation, readiness, upload and execution. It defaults to 600 seconds and accepts 1 to 2,591,880. Collection and cleanup each get a separate 30-second grace. The box is always disposable, with a fixed host expiry of timeout plus 120 seconds set before startup. There is no keep or lease-renewal mode, and the payload is never retried.

Choose files and directories deliberately

  • --push DIRECTORY includes Git-tracked and unignored untracked files, including edits. It excludes .git at every level, omits deleted files and rejects submodules. Tracked credentials still copy; this is not a secret scanner.
  • --push-all DIRECTORY copies the entire inspected tree, including ignored files, hidden files and Git metadata. Use it explicitly for a non-Git tree, not to hide a Git error.
  • Uploads use /workspace/project by default. Without upload, commands use /workspace. --cwd changes that path and the upload destination. An upload needs an absent destination with an existing parent, so keep template caches outside it.
  • Repeat --pull GUEST_DIRECTORY NEW_LOCAL_DIRECTORY to collect multiple trees. Local parents must exist and destinations must be absent, including symlinks. Put individual artifacts in a result directory. Collection runs after a failed payload too; one failed pull does not block later pulls unless the shared grace expires.

Read the result and handle interruption

ResultExit status
Payload failureThe payload's nonzero status, including signal-style statuses
Total deadline exceeded124
Ctrl+C or SIGTERM130 or 143
Setup, collection or cleanup failure without an earlier failure1
Successful payload and confirmed collection/cleanup0

Cleanup checks that the box belongs to this run. Cancellation also guards against a queued creation starting after absence was confirmed. If SSH is lost, the controller is killed or cleanup cannot be confirmed, inspect the exact allocated handle printed on stderr before rerunning. The payload may have changed external systems; deleting its box does not undo those changes.

Host expiry is a backstop, not instant deletion. An unavailable host, stopped worker or long locked operation can delay it. Inspect raft list --location lab and host diagnostics rather than assume cleanup happened.

Reuse dependencies or call from CI

Prepare a sanitized snapshot template, then pass --from "$box/prepared" instead of --location. Each job gets an independent same-host copy with the snapshot's size unless explicitly overridden. Its changes do not refresh the template.

In your existing trusted CI runner, install Raft and supply approved host inventory and SSH access. Store the host key, verified known-host lines and inventory outside the uploaded tree. Never disable host-key checking. Set the CI runner's time limit longer than the Raft deadline plus both grace periods; a forcibly terminated runner cannot finish cleanup. Raft does not purchase capacity or estimate your host and CI costs.

On this page