# CI

Run each CI job in a fresh full VM, with Docker, systemd and nested KVM, billed by the second.

> **Status:** `harebox run` works from any CI system today. GitHub Actions `runs-on` labels need a registered GitHub App, which isn't connected yet.

## From any CI system: `harebox run`

One command starts a fresh sandbox, runs the job in it, deletes the sandbox, and exits with the job's own exit code:

```sh
harebox run -- echo running tests
```

| Flag | Does |
|---|---|
| `--from TEMPLATE` | Start from a saved template with your toolchain and caches |
| `--size SIZE` | `small`, `default`, `large`, `xlarge`, or a shape like `8c16g` |
| `--environment NAME` | Bring an environment's variables, secrets and setup script |
| `--ttl SECONDS` | Auto-stop, so a hung job can't run forever. One hour by default |
| `--keep-on-failure` | Keep the sandbox when the job fails, and print its ID, so you can inspect it |
| `--keep` | Always keep it |
| `--env K=V`, `--cwd DIR` | Passed to the command |

An interrupt, such as a cancelled CI job, still deletes the sandbox. In GitHub Actions:

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsSL https://harebox.com/install.sh | sh
      - run: ~/.local/bin/harebox run --from ci-base --size large -- "git clone $REPO app && cd app && make test"
        env:
          HAREBOX_API_KEY: ${{ secrets.HAREBOX_API_KEY }}
```

The installer checks that HareBox signed the release before installing anything, with `ssh-keygen`, which GitHub's Ubuntu runners include.

Give CI its own key with the `ci` preset, which can manage only the sandboxes it creates: `harebox api-key new --name ci --preset ci`.

## Step by step

To keep a sandbox between steps, drive it yourself:

```sh
ID=$(harebox new --ttl 1800 --name ci-job | jq -r .id)
harebox exec "$ID" -- echo running tests
harebox delete "$ID"
```

`harebox exec` exits with the job's own code. `--ttl` stops a forgotten job. Spot costs the same as Shared and may be preempted with two minutes' notice, so keep deployments on Shared.

## Planned GitHub Actions labels

```yaml
jobs:
  test:
    runs-on: harebox-spot
```

```sh
harebox ci
```